kanbo-cli 0.1.0

package/dist/lib/index.d.mts

@@ -0,0 +1,1608 @@
+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-fsHqNAip.mjs";
+import { a as BoardStore, c as IssueContextRefStore, d as IssuePullRequestStore, f as IssueRelationStore, g as KanbanMetaStore, h as IssueStatusStore, i as BoardRunProjectionScope, l as IssueFieldChangeStore, m as IssueRunStore, n as BoardLinkedPullRequest, o as BoardTransactionMode, p as IssueRowStore, r as BoardRunProjection, s as IssueCommentStore, t as BoardActiveRun, u as IssueMilestoneStore } from "./board-store-B16YarvX.mjs";
+import { a as ENTRY_RULES, c as EntryRuleFacts, d as evaluateEntryRules, f as readChecklist, i as KanboToolName, l as UNMET_ENTRY_RULE_REASONS, m as serializeEntryRules, n as KANBO_TOOL_NAMES, o as ENTRY_RULE_DESCRIPTIONS, p as readEntryRules, r as KanboToolCliEquivalent, s as EntryRule, t as KANBO_TOOL_CLI_EQUIVALENTS, u as UnmetEntryRule } from "./tool-names-Dxg1UTUl.mjs";
+import { z } from "zod";
+//#region src/cli/output.d.ts
+/**
+ * Every exit code this tool promises, and what it means — the capabilities
+ * manifest's `exitCodes` reads this rather than naming the codes again. `0` and
+ * `1` are not declared above: they need no name of their own, success and "I
+ * could not do that" being every command line's baseline.
+ */
+declare const CLI_EXIT_CODES: readonly [{
+  readonly code: 0;
+  readonly meaning: "Success.";
+}, {
+  readonly code: 1;
+  readonly meaning: "The command did not do what it was asked. See the message.";
+}, {
+  readonly code: 2;
+  readonly meaning: "Nothing to work on, or nothing told the command what to work on.";
+}, {
+  readonly code: 3;
+  readonly meaning: "The database is older than the board schema this build speaks.";
+}, {
+  readonly code: 4;
+  readonly meaning: "The command is a person's to run, and this shell is not a person.";
+}];
+//#endregion
+//#region src/capabilities/manifest.d.ts
+/**
+ * A machine-readable description of this board, for an agent that has never
+ * seen it before: an orchestrator deciding how to work a card, a host wiring
+ * up its own tools against the board, anything that is not a person reading
+ * the README.
+ *
+ * Every list below is read out of the same constants and registrations the
+ * board itself runs on — `KANBO_TOOLS`, `registerKanboCommands`,
+ * `BOARD_RULES`, the canonical strings `ops/cards.ts` and `ops/runs.ts` write,
+ * the roles `roles.sql.ts` creates — rather than written out a second time.
+ * `manifest.test.ts` is what keeps that true: it fails the day one of those
+ * sources gains something this file was not told about.
+ *
+ * `buildCapabilitiesManifest` and `renderCapabilitiesMarkdown` are the one
+ * source two servings come from: `kanbo capabilities` prints either shape
+ * from a terminal, and `kanbo mcp` serves both as resources
+ * (`kanbo://capabilities`, `kanbo://capabilities.md`).
+ */
+/** The manifest's own shape version, bumped when a field is added or removed — not the package's version. */
+declare const CAPABILITIES_MANIFEST_VERSION = "3";
+/** The board's name and the build that is answering, as `kanbo mcp` itself reports them. */
+interface KanboCapabilitiesPackage {
+  name: string;
+  version: string;
+}
+/** One of the three places a board can live, and what tells them apart. */
+interface KanboCapabilityStorage {
+  /** `own-file` is `kanbo init --file`; `host-file` is a host app's own database; `postgres` is external. */
+  kind: 'host-file' | 'own-file' | 'postgres';
+  label: string;
+  description: string;
+  /** The board schema generation this build speaks, from `BOARD_SCHEMA_EPOCH` — the same number in all three. */
+  schemaEpoch: number;
+}
+/** One of the board's MCP tools, with the JSON Schema an orchestrator validates a call against. */
+interface KanboCapabilityTool {
+  name: string;
+  title: string;
+  description: string;
+  /** `tool.inputSchema` converted with zod's own `toJSONSchema` — never hand-written. */
+  inputSchema: Record<string, unknown>;
+  /** What to type instead, from `KANBO_TOOL_CLI_EQUIVALENTS`: the `kanbo` command. */
+  cli: KanboToolCliEquivalent;
+}
+/** One flag a CLI command takes, as commander itself declares it. */
+interface KanboCapabilityCommandOption {
+  /** The flag spelling commander prints in `--help`, e.g. `--title <title>`. */
+  flags: string;
+  description: string;
+  /** Set by `.requiredOption(...)`: the command refuses to run without it. */
+  mandatory: boolean;
+}
+/** One positional argument a CLI command takes, as commander itself declares it. */
+interface KanboCapabilityCommandArgument {
+  name: string;
+  description: string;
+  required: boolean;
+}
+/** One leaf command of the `kanbo` binary — a command with no subcommands of its own. */
+interface KanboCapabilityCommand {
+  /** How a person types it, without the leading `kanbo`: `card create`, `approve`. */
+  path: string;
+  description: string;
+  arguments: KanboCapabilityCommandArgument[];
+  options: KanboCapabilityCommandOption[];
+  /** `true` for the commands `requireHumanActor` guards: refused in a shell that says it belongs to an agent. */
+  humanOnly: boolean;
+  /** Every exit code this build promises, from `CLI_EXIT_CODES` — the same table for every command. */
+  exitCodes: typeof CLI_EXIT_CODES;
+}
+/** The two database roles an external board is worked through, and what the database itself refuses the agent. */
+interface KanboCapabilitiesRoles {
+  person: string;
+  agent: string;
+  /** What the database says back when the agent role tries the two things that are a person's. */
+  refusals: string[];
+}
+/** One rule a column may ask of a card before an agent moves the card in (ruling 6-1). */
+interface KanboCapabilityEntryRule {
+  rule: EntryRule;
+  description: string;
+}
+/** Everything an orchestrator can read about this board before it has opened one. */
+interface KanboCapabilities {
+  version: string;
+  package: KanboCapabilitiesPackage;
+  storages: KanboCapabilityStorage[];
+  tools: KanboCapabilityTool[];
+  commands: KanboCapabilityCommand[];
+  /** The board-independent rules `kanbo prime` states — no columns here, because a column is per board. */
+  rules: string[];
+  /** Every rule a column may ask of a card, from `ENTRY_RULES` — which columns ask for which is per board, in `kanbo_columns`. */
+  entryRules: KanboCapabilityEntryRule[];
+  /** The literal strings the board writes for a run's lifecycle, an approval and a return — prefixes end in the punctuation or space that precedes the part a caller fills in. */
+  canonicalStrings: Record<string, string>;
+  roles: KanboCapabilitiesRoles;
+  limits: string[];
+}
+/** Everything this build of the board can tell an orchestrator about itself. */
+declare function buildCapabilitiesManifest(): KanboCapabilities;
+//#endregion
+//#region src/capabilities/markdown.d.ts
+/** The manifest, laid out under one heading per field — stable and diffable, never a snapshot to update by hand. */
+declare function renderCapabilitiesMarkdown(manifest: KanboCapabilities): string;
+//#endregion
+//#region src/cli/binding.d.ts
+/** The binding file itself, relative to the project root. */
+declare const BINDING_FILE_PATH: string;
+declare const BindingSchema: z.ZodObject<{
+  schemaVersion: z.ZodLiteral<1>;
+  workspaceId: z.ZodString;
+  boardId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  dbPath: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  databaseUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  agentDatabaseUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  identifier: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+/** The project's binding, as it is written and read back. */
+type KanboBinding = z.infer<typeof BindingSchema>;
+/**
+ * The binding this project folder has of its own — not a parent's.
+ *
+ * `kanbo init` merges into it rather than replacing it: a person re-running
+ * the command to refresh an instruction block never said anything about the
+ * board, and a second `init` that quietly dropped the connection string would
+ * leave a project bound to nothing.
+ */
+declare function readProjectBinding(projectDir: string): KanboBinding | null;
+/** The binding in that exact file, or `null` when there is none to read. */
+declare function readBinding(path: string): KanboBinding | null;
+/**
+ * Bind the project folder to a board.
+ *
+ * The binding itself is kept out of git, because the workspace id in it means
+ * nothing in anyone else's checkout. The ignore rule names the files kanbo
+ * writes rather than `*`, so a person who does want something in `.kanbo`
+ * committed can still add it. The user's own `.gitignore` is not touched at
+ * all; it is not kanbo's file to edit.
+ *
+ * It is written `0600`, because it may hold one or two connection strings and
+ * keeping a file out of a repository is not keeping it away from the other
+ * accounts on the machine. `mode` only applies to a file this call creates, so
+ * an existing one — a second `init`, or a file written before this rule — is
+ * narrowed explicitly. Windows has no such bits and `chmodSync` does nothing
+ * there, which is the right nothing: no permission to narrow, and no failure
+ * to handle.
+ */
+declare function writeBinding(projectDir: string, binding: KanboBinding): string;
+/**
+ * Make sure `.kanbo/.gitignore` also covers a board file of this project's
+ * own — `kanbo init --file` calls this once, right after creating it — and
+ * the two files SQLite leaves beside it in WAL mode, `-wal` and `-shm`, which
+ * hold committed data of their own and are exactly as much a secret as the
+ * database itself.
+ *
+ * Only when the file is inside `.kanbo`, which is where `--file` puts it by
+ * default: the ignore rule only ever grows kanbo's own directory, and a path
+ * chosen elsewhere in the project gets no line here, the same way the user's
+ * own `.gitignore` is never touched at all.
+ */
+declare function ignoreBoardFile(projectDir: string, absoluteDbPath: string): void;
+//#endregion
+//#region src/default-board-file-path.d.ts
+/**
+ * Where a board file of a project's own goes when nobody names a path —
+ * `kanbo init --file` writes it here, and an app that attaches a project's
+ * board file can import the same constant rather than spelling it again.
+ */
+declare const DEFAULT_BOARD_FILE_PATH: string;
+//#endregion
+//#region src/domain/issue-view.d.ts
+/** An issue row with its `labels` column decoded from JSON. */
+type IssueView = Omit<Issue, 'labels'> & {
+  labels: string[];
+};
+/**
+ * Who a board change is attributed to. The `issue_field_changes.actor_kind`
+ * column owns the union; comment authors carry the same kinds plus the
+ * `system.*` markers that `normalizeCommentAuthorKind` folds away.
+ */
+type IssueActorKind = IssueFieldChange['actorKind'];
+declare function toIssueView(issue: Issue): IssueView;
+/**
+ * Fold a comment's author kind onto the actor kinds a reader renders: only a
+ * person, an agent and a provider target speak for themselves, so every
+ * `system.*` marker — whatever it marks — is the board speaking as `system`.
+ */
+declare function normalizeCommentAuthorKind(authorKind: IssueComment['authorKind']): IssueActorKind;
+/** Who a row is filed under, as the row stores it — what a host resolves into a name to show. */
+interface IssueActorReference {
+  kind: IssueActorKind;
+  id: string | null;
+  sourceChatSessionId: string | null;
+}
+/** What a stored row says about who wrote it: the name its writer gave, and the chat session it came from. */
+interface IssueWriterProvenance {
+  authorId: IssueComment['authorId'];
+  sourceChatSessionId: IssueComment['sourceChatSessionId'];
+}
+/**
+ * Was this row written by an outside writer?
+ *
+ * An outside writer is stored as `system`, the same kind the board writes
+ * under, so the kind alone cannot say. What a row carries can: a writer from
+ * outside — the `kanbo` command line, an agent someone ran themselves — gives
+ * a name and speaks from no chat session, while the board writing on its
+ * own behalf gives no name (`BOARD_ACTOR`) and an app's agent runtime filed under
+ * `system` always carries the session it was called in. The caller establishes
+ * the `system` kind first; this answers the rest of the question, and says in
+ * its type that such a writer has a name to show.
+ */
+declare function isOutsideWriter(provenance: IssueWriterProvenance): provenance is IssueWriterProvenance & {
+  authorId: string;
+};
+//#endregion
+//#region src/domain/numbering.d.ts
+/**
+ * What numbering needs to know about a workspace: enough to build the key stem,
+ * and nothing else. A host app's workspace row satisfies it; so does a workspace
+ * a command-line tool resolved from a path, without the board reading anybody's
+ * tables to find it.
+ *
+ * Written out rather than `Pick`ed from a row type, because the board has no row
+ * to pick from: a workspace belongs to whoever tracks it, and this package declares only what it
+ * needs of one.
+ */
+interface BoardWorkspaceIdentity {
+  id: string;
+  identifier: string;
+  name: string;
+}
+/** The three-letter stem every issue key in the workspace starts with. */
+declare function readIssuePrefix(workspace: BoardWorkspaceIdentity): string;
+declare function formatIssueId(prefix: string, number: number): string;
+/**
+ * The key and number the next issue of this workspace gets. The loop skips keys
+ * an earlier prefix already took, so a renamed workspace never collides with its
+ * own history.
+ */
+declare function nextIssueIdentity(workspace: BoardWorkspaceIdentity, store: BoardStore): Promise<{
+  id: string;
+  number: number;
+}>;
+declare function nextIssueNumber(workspaceId: string, tx: BoardStore): Promise<number>;
+declare function nextIssueOrder(workspaceId: string, tx: BoardStore): Promise<number>;
+//#endregion
+//#region src/domain/activity-types.d.ts
+type IssueActivityValueToken = 'changed' | 'current-user' | 'empty' | 'no-due-date' | 'no-labels' | 'no-milestone' | 'no-parent' | 'no-status' | 'priority-high' | 'priority-low' | 'priority-medium' | 'priority-none' | 'priority-urgent' | 'unassigned' | 'unknown-issue' | 'unknown-milestone' | 'unknown-status' | 'unknown-user';
+type IssueActivityValueView = {
+  kind: 'date';
+  timestamp: number;
+} | {
+  kind: 'text';
+  text: string;
+} | {
+  kind: 'token';
+  token: IssueActivityValueToken;
+};
+type IssueActivityField = 'assignee' | 'description' | 'due-date' | 'labels' | 'metadata' | 'milestone' | 'parent' | 'priority' | 'status' | 'status-line' | 'title' | 'workspace';
+type IssueActivityAction = 'added-description' | 'changed-field' | 'cleared-description' | 'renamed-issue' | 'updated-description';
+interface IssueActivityFieldChangeView {
+  action: IssueActivityAction;
+  field: IssueActivityField | null;
+  fromValue: IssueActivityValueView | null;
+  toValue: IssueActivityValueView | null;
+}
+interface IssueActivityCommentView {
+  content: string;
+  systemKind: 'delegated' | 'system' | 'undelegated' | null;
+}
+/** The actor a board shows beside a comment or an activity row. */
+interface IssueCommentAuthorView {
+  kind: IssueActorKind;
+  id: string | null;
+  displayName: string;
+  avatarUrl: string | null;
+  label: string | null;
+}
+interface IssueActivityItemView {
+  id: string;
+  issueId: string;
+  kind: 'comment' | 'created' | 'field-change';
+  actor: IssueCommentAuthorView;
+  comment: IssueActivityCommentView | null;
+  fieldChange: IssueActivityFieldChangeView | null;
+  sourceChatSessionId: string | null;
+  createdAt: number;
+}
+/**
+ * The rows an Activity projection resolves ids against, read once per issue so
+ * formatting a change never goes back to the store.
+ */
+interface IssueActivityLookup {
+  issue: Issue;
+  issueById: Map<string, Pick<Issue, 'id' | 'title'>>;
+  milestoneById: Map<string, Pick<IssueMilestone, 'id' | 'title'>>;
+  statusById: Map<string, Pick<IssueStatus, 'id' | 'name'>>;
+  workspaceById: Map<string, Pick<BoardWorkspaceIdentity, 'id' | 'name'>>;
+}
+//#endregion
+//#region src/domain/card-display-title.d.ts
+/**
+ * What a card is called wherever a person or an agent reads it by name.
+ *
+ * A card written as a description alone is titled with its own key (every
+ * writer does that). Named by its key, such a card says nothing — so its name
+ * is the first line of its description instead. A browser bundle that does not
+ * load this package keeps the same rule on its own, tested with the same
+ * examples.
+ */
+declare function cardDisplayTitle(card: {
+  id: string;
+  title: string;
+  description?: string | null;
+}): string;
+//#endregion
+//#region src/domain/database-url.d.ts
+/**
+ * A board's connection string, as it may be said out loud.
+ *
+ * Everything a person needs to recognise which board they are talking to is
+ * the host and the database name. The password is the one part that must never
+ * reach a terminal, a log, a `--json` result or a tool's answer — and it is not
+ * the only part: a connection string carries options in its query, and a
+ * `?password=…` there is as much a secret as the one in front of the host.
+ *
+ * It is a fact about the value rather than about the command line, which is why
+ * it lives here: the MCP tools hand back messages they did not write either,
+ * and they must not be made to carry the board tool's own runtime to say them
+ * safely.
+ */
+/**
+ * The connection string with everything secret taken out of it.
+ *
+ * A string this cannot take apart is not examined to find out why — it is
+ * replaced entirely, because whatever is wrong with it, the secret is still
+ * somewhere inside. A missing scheme counts as that: `user:secret@host/db`
+ * parses, as a `user:` URL whose whole password is in the path, and printing it
+ * back would say the secret out loud.
+ */
+declare function maskDatabaseUrl(url: string): string;
+/**
+ * Every connection string inside a line of text, masked.
+ *
+ * A message this package did not write — a driver's, a migrator's — may carry
+ * the whole connection string in the middle of a sentence, and it reaches the
+ * same terminal, or the same agent, as everything else.
+ */
+declare function maskDatabaseUrls(text: string): string;
+//#endregion
+//#region src/domain/errors.d.ts
+/**
+ * Every failure the board itself can name. HTTP status codes are not part of
+ * this list: what each code is over HTTP is `BOARD_ERROR_RESPONSES`
+ * (`../serve/board-error-responses.ts`), the one table `kanbo serve` and any app
+ * serving the board over HTTP answer with.
+ *
+ * Five of them are about where a board lives rather than about what is on it,
+ * and they are named here for the same reason as the rest: a host that keeps
+ * one board in a file and another in a database still answers its callers in
+ * one vocabulary. `board_storage_not_prepared` is a connection string pointing
+ * at a database that holds no board this build can speak for,
+ * `board_storage_unavailable` is one the host could not reach at all,
+ * `board_storage_not_configured` is a workspace that names no board to look at,
+ * `board_storage_not_empty` is a board still holding cards when something asked
+ * to point the workspace somewhere else, and `board_mixed_workspaces` is a
+ * single operation naming cards that turned out to live in two different
+ * boards — which no transaction can commit as one.
+ */
+type BoardErrorCode = 'board_approval_requires_user' | 'board_column_rules_requires_user' | 'board_column_rules_unmet' | 'board_copy_conflict' | 'board_entry_rule_invalid' | 'board_execution_mode_locked' | 'board_mixed_workspaces' | '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' | 'board_storage_not_configured' | 'board_storage_not_empty' | 'board_storage_not_prepared' | 'board_storage_unavailable' | 'issue_comment_delete_requires_user' | 'issue_comment_not_found' | 'issue_context_ref_invalid_index' | 'issue_milestone_not_found' | 'issue_not_found' | '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`. */
+declare class BoardError extends Error {
+  readonly code: BoardErrorCode;
+  readonly details?: Record<string, unknown>;
+  constructor(code: BoardErrorCode, details?: Record<string, unknown>);
+}
+//#endregion
+//#region src/domain/external-session-ref.d.ts
+/**
+ * Where an external agent's own log of a run lives, once it has said (ruling
+ * 7-1): which tool wrote it, and the id that tool knows the session by.
+ */
+interface ExternalSessionRef {
+  provider: 'claude' | 'codex';
+  /**
+   * The tool's own id for the session — a Claude Code session id, or a Codex
+   * session id (the one in the rollout's `session_meta`, which Codex prints).
+   */
+  id: string;
+}
+/**
+ * Read an external session reference out of what an agent passed to
+ * `kanbo run start --session` or `kanbo run attach-session`: `claude:<id>` —
+ * a Claude Code session id — or `codex:<id>` — a Codex session id. Anything
+ * else is refused with `board_run_session_ref_invalid` rather than stored
+ * unread, because a ref this build cannot parse back is a transcript nobody
+ * can ever open.
+ *
+ * Doubles as the validator: a caller that only needs to know whether a string
+ * is well formed calls this and catches the throw, the same as
+ * `parsePullRequestRef`.
+ */
+declare function parseExternalSessionRef(input: string): ExternalSessionRef;
+/** The stored and printed form: `claude:<id>` or `codex:<id>`. */
+declare function formatExternalSessionRef(ref: ExternalSessionRef): string;
+//#endregion
+//#region src/domain/field-changes.d.ts
+/**
+ * The issue columns whose edits are written to the audit trail.
+ *
+ * `statusLine` is absent on purpose: `writeStatusLine` records every line it
+ * writes itself, and no patch ever carries the column. `waitingFor` is absent
+ * too — whose turn it is shows in the card's own line and in the
+ * `system.approved` / `system.returned` comments around it, so a row saying the
+ * same thing a third time would only crowd the history.
+ */
+declare const TRACKED_FIELDS: readonly ["workspaceId", "title", "description", "priority", "labels", "milestoneId", "parentIssueId", "statusId", "assigneeKind", "assigneeId", "dueDate", "delegateAgentId", "delegateProviderTargetId", "contextRefs", "executionMode", "order"];
+/** Who an issue edit is attributed to, with the chat session it came from. */
+interface IssueMutationActor {
+  kind: IssueActorKind;
+  id: string | null;
+  sourceChatSessionId?: string | null;
+}
+/**
+ * The audit rows one patch produces: a row per tracked field whose stringified
+ * value actually changed. Nothing is written here — the caller inserts what
+ * comes back, so the diff stays a pure function of the row, the patch, the
+ * actor and the clock.
+ */
+declare function diffFieldChanges(before: Issue, updates: Partial<typeof issues.$inferInsert>, actor: IssueMutationActor, now: number): Array<typeof issueFieldChanges.$inferInsert>;
+//#endregion
+//#region src/domain/issue-activity.d.ts
+declare function activityKindOrder(kind: IssueActivityItemView['kind']): number;
+/**
+ * The badge a system comment renders under. Delegation owns two of its own; the
+ * rest of the `system.*` markers read as plain system comments until they earn
+ * a badge.
+ *
+ * A plain `system` row is where provenance decides: a writer from outside —
+ * the command line, an agent someone ran themselves — is stored as `system` too, and what it wrote is an ordinary comment
+ * rather than a line about the board — `isOutsideWriter` is that question.
+ */
+declare function readSystemCommentKind(authorKind: IssueComment['authorKind'], provenance: IssueWriterProvenance): IssueActivityCommentView['systemKind'];
+/**
+ * Who a comment is shown under. A `system.*` marker is the board's own line
+ * about what happened — a run launched, a person's decision — so the id it
+ * carries names whoever caused the line, never its author. Only a plain
+ * `system` row can name a writer.
+ */
+declare function commentAuthorReference(comment: IssueComment): IssueActorReference;
+declare function formatActivityIssueReference(value: string | null, lookup: IssueActivityLookup): IssueActivityValueView;
+declare function formatPlainActivityValue(value: string | null): IssueActivityValueView;
+declare function parseActivityStringArray(value: string | null): string[] | null;
+declare function isEmptyActivityValue(value: string | null): value is null | '' | '[]';
+declare function activityText(text: string | null): IssueActivityValueView | null;
+declare function activityToken(token: IssueActivityValueToken): IssueActivityValueView;
+//#endregion
+//#region src/domain/pull-request-fact-keys.d.ts
+/**
+ * The dedupe keys the facts about one pull request are written under on a card.
+ *
+ * Whatever watches a pull request writes them — opened, merged, closed and a CI
+ * verdict per head — and whatever reads a card's pull requests, this package's
+ * `ci_green` entry rule included, reads them back (rulings 4-7, 6-2), so the spelling lives here,
+ * with the board, rather than being copied into each. Owner and repo are lower-cased
+ * because GitHub names are case-insensitive (ruling 4-6): `Acme/Repo#7` and
+ * `acme/repo#7` key to the same facts.
+ */
+interface PullRequestFactKeys {
+  opened: string;
+  merged: string;
+  closed: string;
+  /** GitHub answered 404/422 for this link on enough consecutive ticks that the watcher dropped it (`pr-watcher.ts`). */
+  gone: string;
+  /** What every CI verdict key of this pull request starts with; the head sha and `:green` or `:red` follow. */
+  ciPrefix: string;
+}
+declare function pullRequestFactKeys({ owner, repo, number }: {
+  owner: string;
+  repo: string;
+  number: number;
+}): PullRequestFactKeys;
+//#endregion
+//#region src/domain/status-name.d.ts
+/**
+ * The columns a workspace gets the first time someone opens its board, in board
+ * order. A workspace that already holds statuses is never re-seeded.
+ */
+declare const DEFAULT_STATUSES: readonly [{
+  readonly name: "Backlog";
+  readonly description: "Idea captured, not ready to work on";
+  readonly color: "#6b7280";
+  readonly category: "backlog";
+}, {
+  readonly name: "To Do";
+  readonly description: "Spelled out, ready to launch";
+  readonly color: "#9ca3af";
+  readonly category: "unstarted";
+}, {
+  readonly name: "In Progress";
+  readonly description: "The orchestrator and its agents are working";
+  readonly color: "#f59e0b";
+  readonly category: "started";
+}, {
+  readonly name: "In Review";
+  readonly description: "Work done; being checked or waiting for you";
+  readonly color: "#8b5cf6";
+  readonly category: "started";
+}, {
+  readonly name: "Done";
+  readonly description: "Accepted";
+  readonly color: "#22c55e";
+  readonly category: "completed";
+}, {
+  readonly name: "Canceled";
+  readonly description: "Canceled";
+  readonly color: "#6b7280";
+  readonly category: "canceled";
+}];
+/**
+ * The slug two status names have in common when they mean the same column:
+ * case and the run of spaces or dashes between words are ignored, so `In
+ * Progress`, `in-progress` and `IN_PROGRESS` all resolve to one status.
+ */
+declare function normalizeStatusName(value: string): string;
+//#endregion
+//#region src/domain/time.d.ts
+/**
+ * Unix seconds — the unit every board timestamp column stores.
+ *
+ * The package carries its own clock, so it depends on nothing of its host's.
+ */
+declare function currentUnixSeconds(): number;
+//#endregion
+//#region src/ops/change-seq.d.ts
+/**
+ * One board write in progress: the store to work through, and — behind it — the
+ * transaction and the change flag the whole write shares.
+ *
+ * An operation that takes a scope joins the write it belongs to instead of
+ * opening one of its own, which is how a card operation that seeds columns, a
+ * status line and a comment still counts as a single change.
+ */
+interface BoardWriteScope<TStore extends BoardStore = BoardStore> {
+  /** The transactional store, wrapped so every write through it is noticed. */
+  readonly tx: TStore;
+}
+/**
+ * Run `fn` as one board write: everything it writes commits together, and the
+ * board's change counter goes up by exactly one if it wrote anything at all.
+ *
+ * The counter is what tells a reader — the board UI polling, a CLI, another
+ * agent — that the board is not the board it last read. It is bumped from the
+ * outermost scope only, after `fn` returns and only when a mutating store method
+ * was actually called, so a read-only pass and a transaction that rolls back
+ * both leave it untouched. Pass `scope` to join a write that is already open
+ * instead of starting a second one.
+ *
+ * The transaction takes its write lock up front (`immediate`), so two writers
+ * racing for the same board file fail fast rather than half-way through. A write
+ * that starts while the host already holds a transaction of its own becomes a
+ * savepoint inside it — the board counter then commits, or rolls back, with
+ * whatever the host is doing.
+ *
+ * The caller rule of the underlying transaction applies in full: `fn` must be
+ * the only database-touching async chain in flight, and inside it only
+ * operations that resolve without I/O may be awaited.
+ */
+declare function runBoardWrite<TStore extends BoardStore, TResult>(store: TStore, fn: (scope: BoardWriteScope<TStore>) => Promise<TResult>, scope?: BoardWriteScope<TStore>): Promise<TResult>;
+/**
+ * How many times the board has changed. A reader that holds a number and reads
+ * the same one back is looking at the board it already has.
+ */
+declare function readChangeSeq(store: BoardStore): Promise<number>;
+//#endregion
+//#region src/ops/types.d.ts
+/**
+ * Who is acting on the board.
+ *
+ * Four kinds reach it: a person, an agent an app launched and knows, a provider
+ * target standing in for one, and anything else — a command-line tool, a
+ * script, an agent someone ran themselves. `id` is whatever the host calls that
+ * actor, or `null` when it has no name to give; `chatSessionId` is the app's
+ * chat session the action came from, and means nothing to a board written from
+ * outside.
+ */
+interface BoardActor {
+  kind: 'user' | 'agent' | 'provider-target' | 'external';
+  id: string | null;
+  name?: string;
+  chatSessionId?: string | null;
+  /**
+   * A person's own terminal placing a card (ruling 6-6): the write is still
+   * filed under `kind`/`id`, but a column's entry rules warn instead of
+   * refusing, as they do for a person on the board page. Only the entry-rule check reads
+   * it; it is never stored.
+   */
+  placesForPerson?: boolean;
+}
+/**
+ * The board writing on its own behalf: the lines and comments the board produces
+ * from a run's lifecycle, which no person and no agent typed.
+ *
+ * This matters beyond provenance. Whether a failed run ends with "no report"
+ * depends on the agent having written a status line since it started, so a line
+ * the board wrote itself must never be filed under the agent that was running.
+ */
+declare const BOARD_ACTOR: BoardActor;
+/** A comment as the board writes it, before the row exists. */
+interface BoardCommentInput {
+  issueId: string;
+  content: string;
+  authorKind: IssueComment['authorKind'];
+  authorId?: string | null;
+  sourceChatSessionId?: string | null;
+  agentActivityId?: string | null;
+  /**
+   * The key that makes the comment a fact rather than a message: writing it
+   * again with the same key leaves the first one standing.
+   */
+  dedupeKey?: string | null;
+}
+//#endregion
+//#region src/ops/cards.d.ts
+/** Which column a caller means, when it may name either. */
+interface ColumnReference {
+  statusId?: string | null;
+  statusName?: string | null;
+}
+/** A new card. The workspace comes in resolved: the board never reads anybody else's tables to find it. */
+interface CreateCardInput extends ColumnReference {
+  workspace: BoardWorkspaceIdentity;
+  /** Optional: a card written as a description alone is titled with its own key. */
+  title?: string | null;
+  description?: string | null;
+  priority?: Issue['priority'];
+  labels?: string[];
+  milestoneId?: string | null;
+  parentIssueId?: string | null;
+  dueDate?: number | null;
+  assigneeKind?: string | null;
+  assigneeId?: string | null;
+  executionMode?: Issue['executionMode'];
+}
+/** Everything a card's fields can be changed to. */
+interface UpdateCardInput extends ColumnReference {
+  workspaceId?: string;
+  title?: string;
+  description?: string | null;
+  priority?: Issue['priority'];
+  labels?: string[];
+  milestoneId?: string | null;
+  parentIssueId?: string | null;
+  assigneeKind?: string | null;
+  assigneeId?: string | null;
+  dueDate?: number | null;
+  order?: number;
+  executionMode?: Issue['executionMode'];
+}
+/**
+ * A card as a write that may have put it in a column hands it back. `unmetRules`
+ * is there only when a person put the card in a column whose entry rules it does
+ * not meet (ruling 6-3) — the write went through, and this is what to warn them
+ * about. An agent never sees it: it is refused instead.
+ */
+type BoardCardWrite = Issue & {
+  unmetRules?: UnmetEntryRule[];
+};
+/** A comment a person or an agent writes; the author defaults to the actor. */
+interface AddCommentInput extends Omit<BoardCommentInput, 'authorKind' | 'dedupeKey'> {
+  authorKind?: BoardCommentInput['authorKind'];
+}
+/** A fact the board records once, however many times it is told. */
+interface CreateCommentOnceInput {
+  issueId: string;
+  authorKind: BoardCommentInput['authorKind'];
+  content: string;
+  dedupeKey: string;
+  actor: BoardActor;
+}
+//#endregion
+//#region src/ops/card-batch.d.ts
+/** The fields one change can set on many cards at once. */
+interface BulkUpdateCardsInput {
+  statusId?: string | null;
+  priority?: Issue['priority'];
+  labels?: string[];
+  milestoneId?: string | null;
+  assigneeKind?: string | null;
+  assigneeId?: string | null;
+  dueDate?: number | null;
+}
+/** What a bulk change did: how many cards it wrote, and — for a person — which of them entered a column short of its rules. */
+interface BulkUpdateCardsResult {
+  updated: number;
+  unmetRules?: Array<{
+    issueId: string;
+    unmet: UnmetEntryRule[];
+  }>;
+}
+//#endregion
+//#region src/ops/migrate.d.ts
+/** Which workspace's cards move where, and how their columns and milestones are matched up. */
+interface MigrateCardsInput {
+  sourceId: string;
+  targetId: string;
+  /**
+   * Both workspaces' columns, in board order. The host reads them from each
+   * workspace's own board, which is not always the board the cards are moved on:
+   * a preview of a move across two boards reads the target's columns from the
+   * target while the cards are still on the source.
+   */
+  sourceStatuses: IssueStatus[];
+  targetStatuses: IssueStatus[];
+  /** A source column name → the target column name it becomes, when the names differ. */
+  statusMappings?: Record<string, string>;
+  /** A source milestone title → the target milestone title it becomes, when the titles differ. */
+  milestoneMappings?: Record<string, string>;
+  /** Count what would happen, and write nothing. */
+  dryRun?: boolean;
+}
+/** What a move of every card from one workspace to another did — or, for a dry run, would do. */
+interface MigrateCardsResult {
+  processed: number;
+  updated: number;
+  numbersReassigned: number;
+  statusesMapped: {
+    from: string;
+    to: string;
+  }[];
+  milestonesMapped: {
+    from: string;
+    to: string | null;
+  }[];
+  parentIssuesCleared: number;
+}
+//#endregion
+//#region src/ops/relations.d.ts
+/** The card on the other end of an edge, as much of it as a relation row shows. */
+type IssueRelationCounterpart = Pick<Issue, 'id' | 'workspaceId' | 'number' | 'title' | 'statusId' | 'priority'>;
+/** An edge as seen from one of the two cards it touches. */
+type IssueRelationView = IssueRelation & {
+  /** Orientation of the edge relative to the issue the relations were listed for. */
+  direction: 'outgoing' | 'incoming';
+  /** The issue on the other end of the edge, resolved across workspaces. */
+  counterpart: IssueRelationCounterpart | null;
+};
+/** A new edge between two cards. */
+interface CreateRelationInput {
+  sourceIssueId: string;
+  targetIssueId: string;
+  type: IssueRelation['type'];
+}
+//#endregion
+//#region src/ops/approval.d.ts
+/** Where a card stands with the person who has to approve it. */
+interface BoardApproval {
+  state: 'none' | 'pending' | 'approved' | 'returned';
+  /** When the person decided, in unix seconds; `null` while nobody has. */
+  decidedAt: number | null;
+  /** What the person wrote alongside the decision, if anything. */
+  comment: string | null;
+}
+//#endregion
+//#region src/ops/pull-requests.d.ts
+/**
+ * A pull request a card names, with where it stands as the card's own facts
+ * say (ruling 4-7): `merged` or `closed` once the watcher has written that,
+ * `open` once it has written «opened», `unknown` before it has read GitHub at
+ * all; `ci` is the newest CI verdict written for it, whatever head it was for.
+ */
+type BoardPullRequestStanding = IssuePullRequest & {
+  state: 'open' | 'merged' | 'closed' | 'unknown';
+  ci: 'green' | 'red' | null;
+};
+//#endregion
+//#region src/ops/sprints.d.ts
+/**
+ * A milestone read as a sprint (ruling 5x-3): the row itself, how many of its
+ * cards are still open and how many are done, and whether it is the sprint
+ * running right now.
+ *
+ * `done` counts the cards in a `completed` or `canceled` column — the ones
+ * closing the sprint leaves where they are; `open` counts every other card,
+ * a card in no column at all included — the ones closing it carries on.
+ */
+interface BoardSprint extends IssueMilestone {
+  cards: {
+    open: number;
+    done: number;
+  };
+  current: boolean;
+}
+/**
+ * What a milestone is created with; `startDate` and `dueDate` are unix seconds,
+ * kept as the first and the last second of their UTC days.
+ */
+interface CreateMilestoneInput {
+  workspaceId: string;
+  title: string;
+  description?: string | null;
+  startDate?: number | null;
+  dueDate?: number | null;
+  status?: IssueMilestone['status'];
+}
+/** What of a milestone can change. */
+type UpdateMilestoneInput = Partial<Omit<CreateMilestoneInput, 'workspaceId'>>;
+/** What closing a sprint did: how many unfinished cards it moved on, and that the sprint is closed. */
+interface CloseSprintResult {
+  carried: number;
+  closed: true;
+}
+//#endregion
+//#region src/ops/runs.d.ts
+/** What is known about a run when it starts. */
+interface StartRunInput {
+  agentName: string;
+  agentId?: string | null;
+  host?: string | null;
+  /** Defaults to the mode the card carries. */
+  executionMode?: Issue['executionMode'];
+  /** Defaults to the actor's own kind and id. */
+  launchedByKind?: IssueRun['launchedByKind'];
+  launchedById?: string | null;
+  chatSessionId?: string | null;
+  branch?: string | null;
+  worktreePath?: string | null;
+  /** Where the agent's own log of this run lives, if it said: `claude:<id>` or `codex:<id>` (ruling 7-1). */
+  externalSessionRef?: string | null;
+}
+/** What a run turned out to be running in, once the host knows. */
+interface AttachRunExecutionInput {
+  chatSessionId?: string | null;
+  branch?: string | null;
+  worktreePath?: string | null;
+  /** Where the agent's own log of this run lives, if it said: `claude:<id>` or `codex:<id>` (ruling 7-1). */
+  externalSessionRef?: string | null;
+}
+/** How a run ended, and — for a failure or a stop — what to say about it. */
+interface FinishRunInput {
+  state: 'finished' | 'failed' | 'stopped';
+  errorText?: string | null;
+  /**
+   * Why a `stopped` run ended, when the answer is neither a person pressing
+   * stop nor the app that launched it tidying up quietly: the comment then reads
+   * `Run stopped: <reason>` instead of `Run stopped`.
+   */
+  reason?: string;
+  /**
+   * What the card says it is doing once that stop is recorded, whoever the
+   * actor is. A stop with no line of its own leaves the rule as it was: the
+   * person who pressed stop is named, and anything else says nothing.
+   */
+  statusLine?: string;
+}
+/** A run with the attempt number it is, counting from the card's first launch. */
+type BoardRunView = IssueRun & {
+  attempt: number;
+};
+//#endregion
+//#region src/ops/activity.d.ts
+/**
+ * What the host knows and the board does not: the names of its workspaces, who
+ * an actor is, and what an agent is called. A board holds ids for all three and
+ * nothing more, so an Activity feed is the board's rows read through these.
+ */
+interface IssueActivityResolver {
+  workspaceById: IssueActivityLookup['workspaceById'];
+  /** Who a reader sees beside a row. */
+  resolveActor: (actor: IssueActorReference) => Promise<IssueCommentAuthorView>;
+  /** The agent's name, or `null` when the host has no such agent. */
+  resolveAgentName: (agentId: string) => Promise<string | null>;
+}
+//#endregion
+//#region src/ops/columns.d.ts
+/** What a column is made of, beyond the workspace it belongs to and its position. */
+interface BoardColumnInput {
+  workspaceId: string;
+  name: string;
+  description?: string | null;
+  color?: string | null;
+  category?: IssueStatus['category'];
+  /** What a card must satisfy before an agent may put it here — `ENTRY_RULES`, none by default. */
+  entryRules?: readonly string[] | null;
+}
+/** What `updateColumn` may change about a column. */
+interface BoardColumnPatch {
+  name?: string;
+  description?: string | null;
+  color?: string | null;
+  /** `ENTRY_RULES`; `null` or an empty list asks for nothing. */
+  entryRules?: readonly string[] | null;
+}
+//#endregion
+//#region src/ops/index.d.ts
+/**
+ * Everything the board can be asked to do, bound to one store.
+ *
+ * This is the layer the semantics live in — numbering, columns, the status line,
+ * approval, runs — and there is exactly one of it. `kanbo serve`, an app's server, the
+ * command-line tool and the MCP server all call these operations rather than
+ * writing rows of their own, which is why a card launched from a terminal and a
+ * card launched from the app end up telling the same story.
+ *
+ * Every write takes an actor, and every write may take a `scope`: passing the
+ * scope of a write already in progress joins it, so a caller composing several
+ * operations gets one transaction and one board version bump.
+ */
+declare function createBoardOps<TStore extends BoardStore>(store: TStore): {
+  createCard: (input: CreateCardInput, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<BoardCardWrite>;
+  createSubCard: (parentIssueId: string, input: Omit<CreateCardInput, "parentIssueId">, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<BoardCardWrite>;
+  updateCard: (issueId: string, input: UpdateCardInput, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<BoardCardWrite>;
+  moveCard: (issueId: string, nameOrId: string, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<BoardCardWrite>;
+  addComment: (input: AddCommentInput, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<{
+    id: string;
+    createdAt: number;
+    sourceChatSessionId: string | null;
+    issueId: string;
+    content: string;
+    authorKind: "user" | "agent" | "system" | "provider-target" | "system.delegated" | "system.undelegated" | "system.run" | "system.approved" | "system.returned" | "system.pr";
+    authorId: string | null;
+    agentActivityId: string | null;
+    dedupeKey: string | null;
+  }>;
+  createCommentOnce: (input: CreateCommentOnceInput, scope?: BoardWriteScope<TStore>) => Promise<{
+    id: string;
+    createdAt: number;
+    sourceChatSessionId: string | null;
+    issueId: string;
+    content: string;
+    authorKind: "user" | "agent" | "system" | "provider-target" | "system.delegated" | "system.undelegated" | "system.run" | "system.approved" | "system.returned" | "system.pr";
+    authorId: string | null;
+    agentActivityId: string | null;
+    dedupeKey: string | null;
+  }>;
+  listComments: (issueId: string) => Promise<{
+    id: string;
+    createdAt: number;
+    sourceChatSessionId: string | null;
+    issueId: string;
+    content: string;
+    authorKind: "user" | "agent" | "system" | "provider-target" | "system.delegated" | "system.undelegated" | "system.run" | "system.approved" | "system.returned" | "system.pr";
+    authorId: string | null;
+    agentActivityId: string | null;
+    dedupeKey: string | null;
+  }[]>;
+  deleteComment: (commentId: string, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<void>;
+  deleteCard: (issueId: string, scope?: BoardWriteScope<TStore>) => Promise<{
+    runIds: string[];
+  }>;
+  searchCards: (query: string, limit: number) => Promise<{
+    number: number;
+    id: string;
+    workspaceId: string;
+    description: string | null;
+    order: number;
+    createdAt: number;
+    title: string;
+    dueDate: number | null;
+    updatedAt: number;
+    statusId: string | null;
+    milestoneId: string | null;
+    parentIssueId: string | null;
+    priority: "none" | "low" | "medium" | "high" | "urgent";
+    labels: string;
+    assigneeKind: string | null;
+    assigneeId: string | null;
+    createdByKind: "user" | "agent" | "system" | "provider-target";
+    createdById: string;
+    sourceChatSessionId: string | null;
+    delegateAgentId: string | null;
+    delegateProviderTargetId: string | null;
+    contextRefs: string;
+    statusLine: string | null;
+    waitingFor: "human" | null;
+    executionMode: "worktree" | "main";
+  }[]>;
+  bulkUpdateCards: (issueIds: string[], input: BulkUpdateCardsInput, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<BulkUpdateCardsResult>;
+  reorderCards: (workspaceId: string, orderedIds: string[], scope?: BoardWriteScope<TStore>) => Promise<void>;
+  migrateCards: (input: MigrateCardsInput) => Promise<MigrateCardsResult>;
+  addContextRef: (issueId: string, ref: string, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<{
+    number: number;
+    id: string;
+    workspaceId: string;
+    description: string | null;
+    order: number;
+    createdAt: number;
+    title: string;
+    dueDate: number | null;
+    updatedAt: number;
+    statusId: string | null;
+    milestoneId: string | null;
+    parentIssueId: string | null;
+    priority: "none" | "low" | "medium" | "high" | "urgent";
+    labels: string;
+    assigneeKind: string | null;
+    assigneeId: string | null;
+    createdByKind: "user" | "agent" | "system" | "provider-target";
+    createdById: string;
+    sourceChatSessionId: string | null;
+    delegateAgentId: string | null;
+    delegateProviderTargetId: string | null;
+    contextRefs: string;
+    statusLine: string | null;
+    waitingFor: "human" | null;
+    executionMode: "worktree" | "main";
+  }>;
+  removeContextRef: (issueId: string, index: number, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<{
+    number: number;
+    id: string;
+    workspaceId: string;
+    description: string | null;
+    order: number;
+    createdAt: number;
+    title: string;
+    dueDate: number | null;
+    updatedAt: number;
+    statusId: string | null;
+    milestoneId: string | null;
+    parentIssueId: string | null;
+    priority: "none" | "low" | "medium" | "high" | "urgent";
+    labels: string;
+    assigneeKind: string | null;
+    assigneeId: string | null;
+    createdByKind: "user" | "agent" | "system" | "provider-target";
+    createdById: string;
+    sourceChatSessionId: string | null;
+    delegateAgentId: string | null;
+    delegateProviderTargetId: string | null;
+    contextRefs: string;
+    statusLine: string | null;
+    waitingFor: "human" | null;
+    executionMode: "worktree" | "main";
+  }>;
+  listRelations: (issueId: string) => Promise<IssueRelationView[]>;
+  createRelation: (input: CreateRelationInput, scope?: BoardWriteScope<TStore>) => Promise<{
+    id: string;
+    createdAt: number;
+    sourceIssueId: string;
+    targetIssueId: string;
+    type: "blocks" | "duplicates" | "relates_to";
+  }>;
+  deleteRelation: (relationId: string, scope?: BoardWriteScope<TStore>) => Promise<void>;
+  listFieldChanges: (issueId: string) => Promise<{
+    id: string;
+    createdAt: number;
+    sourceChatSessionId: string | null;
+    issueId: string;
+    field: string;
+    fromValue: string | null;
+    toValue: string | null;
+    actorKind: "user" | "agent" | "system" | "provider-target";
+    actorId: string | null;
+  }[]>;
+  listActivity: (issueId: string, resolver: IssueActivityResolver) => Promise<IssueActivityItemView[]>;
+  setStatusLine: (issueId: string, statusLine: string | null, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<{
+    number: number;
+    id: string;
+    workspaceId: string;
+    description: string | null;
+    order: number;
+    createdAt: number;
+    title: string;
+    dueDate: number | null;
+    updatedAt: number;
+    statusId: string | null;
+    milestoneId: string | null;
+    parentIssueId: string | null;
+    priority: "none" | "low" | "medium" | "high" | "urgent";
+    labels: string;
+    assigneeKind: string | null;
+    assigneeId: string | null;
+    createdByKind: "user" | "agent" | "system" | "provider-target";
+    createdById: string;
+    sourceChatSessionId: string | null;
+    delegateAgentId: string | null;
+    delegateProviderTargetId: string | null;
+    contextRefs: string;
+    statusLine: string | null;
+    waitingFor: "human" | null;
+    executionMode: "worktree" | "main";
+  }>;
+  waitApproval: (issueId: string, input: {
+    statusLine?: string | null;
+  }, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<{
+    number: number;
+    id: string;
+    workspaceId: string;
+    description: string | null;
+    order: number;
+    createdAt: number;
+    title: string;
+    dueDate: number | null;
+    updatedAt: number;
+    statusId: string | null;
+    milestoneId: string | null;
+    parentIssueId: string | null;
+    priority: "none" | "low" | "medium" | "high" | "urgent";
+    labels: string;
+    assigneeKind: string | null;
+    assigneeId: string | null;
+    createdByKind: "user" | "agent" | "system" | "provider-target";
+    createdById: string;
+    sourceChatSessionId: string | null;
+    delegateAgentId: string | null;
+    delegateProviderTargetId: string | null;
+    contextRefs: string;
+    statusLine: string | null;
+    waitingFor: "human" | null;
+    executionMode: "worktree" | "main";
+  }>;
+  approve: (issueId: string, input: {
+    comment?: string | null;
+  }, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<{
+    number: number;
+    id: string;
+    workspaceId: string;
+    description: string | null;
+    order: number;
+    createdAt: number;
+    title: string;
+    dueDate: number | null;
+    updatedAt: number;
+    statusId: string | null;
+    milestoneId: string | null;
+    parentIssueId: string | null;
+    priority: "none" | "low" | "medium" | "high" | "urgent";
+    labels: string;
+    assigneeKind: string | null;
+    assigneeId: string | null;
+    createdByKind: "user" | "agent" | "system" | "provider-target";
+    createdById: string;
+    sourceChatSessionId: string | null;
+    delegateAgentId: string | null;
+    delegateProviderTargetId: string | null;
+    contextRefs: string;
+    statusLine: string | null;
+    waitingFor: "human" | null;
+    executionMode: "worktree" | "main";
+  }>;
+  returnCard: (issueId: string, input: {
+    comment: string;
+    toStatusName?: string | null;
+  }, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<{
+    card: Issue;
+    stoppedRunIds: string[];
+  }>;
+  readApproval: (issueId: string) => Promise<BoardApproval>;
+  linkPullRequest: (issueId: string, urlOrRef: string, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<{
+    number: number;
+    id: string;
+    createdAt: number;
+    createdByKind: "user" | "agent" | "system" | "provider-target";
+    createdById: string | null;
+    issueId: string;
+    owner: string;
+    repo: string;
+    url: string;
+  }>;
+  unlinkPullRequest: (issueId: string, linkId: string, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<{
+    number: number;
+    id: string;
+    createdAt: number;
+    createdByKind: "user" | "agent" | "system" | "provider-target";
+    createdById: string | null;
+    issueId: string;
+    owner: string;
+    repo: string;
+    url: string;
+  }>;
+  listPullRequests: (issueId: string) => Promise<{
+    number: number;
+    id: string;
+    createdAt: number;
+    createdByKind: "user" | "agent" | "system" | "provider-target";
+    createdById: string | null;
+    issueId: string;
+    owner: string;
+    repo: string;
+    url: string;
+  }[]>;
+  listPullRequestStandings: (issueId: string) => Promise<BoardPullRequestStanding[]>;
+  listMilestones: (workspaceId: string | null) => Promise<{
+    id: string;
+    workspaceId: string;
+    description: string | null;
+    createdAt: number;
+    title: string;
+    startDate: number | null;
+    dueDate: number | null;
+    status: "open" | "closed";
+    updatedAt: number;
+  }[]>;
+  deleteMilestone: (milestoneId: string, scope?: BoardWriteScope<TStore>) => Promise<void>;
+  createMilestone: (input: CreateMilestoneInput, scope?: BoardWriteScope<TStore>) => Promise<{
+    id: string;
+    workspaceId: string;
+    description: string | null;
+    createdAt: number;
+    title: string;
+    startDate: number | null;
+    dueDate: number | null;
+    status: "open" | "closed";
+    updatedAt: number;
+  }>;
+  updateMilestone: (milestoneId: string, input: UpdateMilestoneInput, scope?: BoardWriteScope<TStore>) => Promise<{
+    id: string;
+    workspaceId: string;
+    description: string | null;
+    createdAt: number;
+    title: string;
+    startDate: number | null;
+    dueDate: number | null;
+    status: "open" | "closed";
+    updatedAt: number;
+  }>;
+  listSprints: (workspaceId: string, now?: number) => Promise<BoardSprint[]>;
+  currentSprint: (workspaceId: string, now?: number) => Promise<BoardSprint | null>;
+  closeSprint: (milestoneId: string, input: {
+    carryTo?: string | null;
+  }, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<CloseSprintResult>;
+  listColumns: (workspaceId: string) => Promise<{
+    id: string;
+    workspaceId: string;
+    name: string;
+    description: string | null;
+    color: string | null;
+    category: "triage" | "backlog" | "unstarted" | "started" | "completed" | "canceled";
+    order: number;
+    entryRules: string | null;
+    createdAt: number;
+  }[]>;
+  findColumn: (workspaceId: string, nameOrId: string) => Promise<{
+    id: string;
+    workspaceId: string;
+    name: string;
+    description: string | null;
+    color: string | null;
+    category: "triage" | "backlog" | "unstarted" | "started" | "completed" | "canceled";
+    order: number;
+    entryRules: string | null;
+    createdAt: number;
+  } | null>;
+  requireColumn: (workspaceId: string, nameOrId: string) => Promise<{
+    id: string;
+    workspaceId: string;
+    name: string;
+    description: string | null;
+    color: string | null;
+    category: "triage" | "backlog" | "unstarted" | "started" | "completed" | "canceled";
+    order: number;
+    entryRules: string | null;
+    createdAt: number;
+  }>;
+  ensureDefaultColumns: (workspaceId: string, scope?: BoardWriteScope<TStore>) => Promise<{
+    id: string;
+    workspaceId: string;
+    name: string;
+    description: string | null;
+    color: string | null;
+    category: "triage" | "backlog" | "unstarted" | "started" | "completed" | "canceled";
+    order: number;
+    entryRules: string | null;
+    createdAt: number;
+  }[]>;
+  createColumn: (input: BoardColumnInput, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<{
+    id: string;
+    workspaceId: string;
+    name: string;
+    description: string | null;
+    color: string | null;
+    category: "triage" | "backlog" | "unstarted" | "started" | "completed" | "canceled";
+    order: number;
+    entryRules: string | null;
+    createdAt: number;
+  }>;
+  updateColumn: (statusId: string, patch: BoardColumnPatch, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<{
+    id: string;
+    workspaceId: string;
+    name: string;
+    description: string | null;
+    color: string | null;
+    category: "triage" | "backlog" | "unstarted" | "started" | "completed" | "canceled";
+    order: number;
+    entryRules: string | null;
+    createdAt: number;
+  }>;
+  describeColumn: (workspaceId: string, nameOrId: string, description: string | null, scope?: BoardWriteScope<TStore>) => Promise<{
+    id: string;
+    workspaceId: string;
+    name: string;
+    description: string | null;
+    color: string | null;
+    category: "triage" | "backlog" | "unstarted" | "started" | "completed" | "canceled";
+    order: number;
+    entryRules: string | null;
+    createdAt: number;
+  }>;
+  setColumnEntryRules: (workspaceId: string, nameOrId: string, entryRules: readonly string[] | null, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<{
+    id: string;
+    workspaceId: string;
+    name: string;
+    description: string | null;
+    color: string | null;
+    category: "triage" | "backlog" | "unstarted" | "started" | "completed" | "canceled";
+    order: number;
+    entryRules: string | null;
+    createdAt: number;
+  }>;
+  enforceColumnEntryForCards: (issueIds: string[], statusId: string, actor: BoardActor) => Promise<{
+    issueId: string;
+    unmet: UnmetEntryRule[];
+  }[]>;
+  deleteColumn: (statusId: string, scope?: BoardWriteScope<TStore>) => Promise<void>;
+  reorderColumns: (workspaceId: string, orderedIds: string[], scope?: BoardWriteScope<TStore>) => Promise<void>;
+  addStandardColumns: (workspaceId: string, scope?: BoardWriteScope<TStore>) => Promise<{
+    statuses: IssueStatus[];
+    added: string[];
+  }>;
+  startRun: (issueId: string, input: StartRunInput, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<{
+    id: string;
+    executionMode: "worktree" | "main";
+    issueId: string;
+    launchedByKind: "user" | "agent" | "external";
+    launchedById: string | null;
+    agentId: string | null;
+    agentName: string;
+    host: string | null;
+    branch: string | null;
+    worktreePath: string | null;
+    state: "running" | "finished" | "failed" | "stopped";
+    chatSessionId: string | null;
+    externalSessionRef: string | null;
+    startedAt: number;
+    endedAt: number | null;
+  }>;
+  attachRunExecution: (runId: string, input: AttachRunExecutionInput, scope?: BoardWriteScope<TStore>) => Promise<{
+    id: string;
+    executionMode: "worktree" | "main";
+    issueId: string;
+    launchedByKind: "user" | "agent" | "external";
+    launchedById: string | null;
+    agentId: string | null;
+    agentName: string;
+    host: string | null;
+    branch: string | null;
+    worktreePath: string | null;
+    state: "running" | "finished" | "failed" | "stopped";
+    chatSessionId: string | null;
+    externalSessionRef: string | null;
+    startedAt: number;
+    endedAt: number | null;
+  }>;
+  recordRunSessionRef: (runId: string, ref: string, scope?: BoardWriteScope<TStore>) => Promise<{
+    id: string;
+    executionMode: "worktree" | "main";
+    issueId: string;
+    launchedByKind: "user" | "agent" | "external";
+    launchedById: string | null;
+    agentId: string | null;
+    agentName: string;
+    host: string | null;
+    branch: string | null;
+    worktreePath: string | null;
+    state: "running" | "finished" | "failed" | "stopped";
+    chatSessionId: string | null;
+    externalSessionRef: string | null;
+    startedAt: number;
+    endedAt: number | null;
+  }>;
+  clearRunSessionRef: (runId: string, actor: BoardActor, options?: {
+    replaceWith?: string;
+  }, scope?: BoardWriteScope<TStore>) => Promise<{
+    id: string;
+    executionMode: "worktree" | "main";
+    issueId: string;
+    launchedByKind: "user" | "agent" | "external";
+    launchedById: string | null;
+    agentId: string | null;
+    agentName: string;
+    host: string | null;
+    branch: string | null;
+    worktreePath: string | null;
+    state: "running" | "finished" | "failed" | "stopped";
+    chatSessionId: string | null;
+    externalSessionRef: string | null;
+    startedAt: number;
+    endedAt: number | null;
+  }>;
+  finishRun: (runId: string, input: FinishRunInput, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<{
+    id: string;
+    executionMode: "worktree" | "main";
+    issueId: string;
+    launchedByKind: "user" | "agent" | "external";
+    launchedById: string | null;
+    agentId: string | null;
+    agentName: string;
+    host: string | null;
+    branch: string | null;
+    worktreePath: string | null;
+    state: "running" | "finished" | "failed" | "stopped";
+    chatSessionId: string | null;
+    externalSessionRef: string | null;
+    startedAt: number;
+    endedAt: number | null;
+  }>;
+  stopRunningRuns: (issueId: string, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<string[]>;
+  listRuns: (issueId: string) => Promise<BoardRunView[]>;
+  findRunByChatSessionId: (chatSessionId: string) => Promise<{
+    id: string;
+    executionMode: "worktree" | "main";
+    issueId: string;
+    launchedByKind: "user" | "agent" | "external";
+    launchedById: string | null;
+    agentId: string | null;
+    agentName: string;
+    host: string | null;
+    branch: string | null;
+    worktreePath: string | null;
+    state: "running" | "finished" | "failed" | "stopped";
+    chatSessionId: string | null;
+    externalSessionRef: string | null;
+    startedAt: number;
+    endedAt: number | null;
+  } | null>;
+  readBoardProjection: (workspaceId: string) => Promise<BoardRunProjection[]>;
+  readBoardProjectionForIssues: (issueIds: string[]) => Promise<BoardRunProjection[]>;
+  readBoardProjectionForIssue: (issueId: string) => Promise<BoardRunProjection>;
+  listReady: (input: {
+    workspaceId: string;
+    limit?: number;
+  }) => Promise<{
+    number: number;
+    id: string;
+    workspaceId: string;
+    description: string | null;
+    order: number;
+    createdAt: number;
+    title: string;
+    dueDate: number | null;
+    updatedAt: number;
+    statusId: string | null;
+    milestoneId: string | null;
+    parentIssueId: string | null;
+    priority: "none" | "low" | "medium" | "high" | "urgent";
+    labels: string;
+    assigneeKind: string | null;
+    assigneeId: string | null;
+    createdByKind: "user" | "agent" | "system" | "provider-target";
+    createdById: string;
+    sourceChatSessionId: string | null;
+    delegateAgentId: string | null;
+    delegateProviderTargetId: string | null;
+    contextRefs: string;
+    statusLine: string | null;
+    waitingFor: "human" | null;
+    executionMode: "worktree" | "main";
+  }[]>;
+  buildPrimeText: (workspaceId: string) => Promise<string>;
+};
+/** The board's operations, as a type callers can name. */
+type BoardOps = ReturnType<typeof createBoardOps<BoardStore>>;
+//#endregion
+//#region src/ops/board-copy.d.ts
+/** How many rows of each kind a copy wrote into the target board. */
+interface BoardCopyCounts {
+  statuses: number;
+  milestones: number;
+  issues: number;
+  comments: number;
+  runs: number;
+  relations: number;
+  fieldChanges: number;
+  /** Cards that carried refs, not rows: context refs are a column on the card. */
+  contextRefs: number;
+  pullRequests: number;
+}
+/** Everything one workspace has on a board, read before anything is written. */
+interface BoardSlice {
+  statuses: IssueStatus[];
+  milestones: IssueMilestone[];
+  /** In an order where a card's parent always comes before it. */
+  issues: Issue[];
+  comments: IssueComment[];
+  runs: IssueRun[];
+  relations: IssueRelation[];
+  fieldChanges: IssueFieldChange[];
+  pullRequests: IssuePullRequest[];
+  /** What reading it had to leave behind, said to a person. */
+  warnings: string[];
+}
+/** Nothing copied — what a move that had nothing to move reports. */
+declare function emptyCopyCounts(): BoardCopyCounts;
+/**
+ * Everything the workspace has on this board, read in one pass before a single
+ * row is written anywhere.
+ *
+ * Links are collected by id because an edge is listed by both of the cards it
+ * touches, and one reaching a card outside this workspace is left behind rather
+ * than copied: the target holds this workspace's board and nothing else, so the
+ * far end of that edge is not there to point at.
+ */
+declare function readBoardSlice(from: BoardStore, workspaceId: string): Promise<BoardSlice>;
+/**
+ * Write a slice into the target board, in one transaction, and say what was
+ * written and what a person should know about it — the slice's own warnings
+ * first.
+ *
+ * It is idempotent by id. A row the target already has is left exactly as it
+ * is and counted as already present, so a copy interrupted half-way is finished
+ * by running it again, and a second run of a finished one copies nothing. A
+ * clash that is not the same row — a column name or a card number the target
+ * holds under another id — refuses the whole copy before its first insert
+ * (`board_copy_conflict`, ruling 3-55).
+ */
+declare function writeBoardSlice(to: BoardStore, slice: BoardSlice, workspaceId: string): Promise<{
+  copied: BoardCopyCounts;
+  warnings: string[];
+}>;
+/**
+ * Empty the slice off the board it was read from, in a transaction of its own.
+ *
+ * Only the cards, the columns and the milestones are named: comments, runs,
+ * links, pull request links and the field-change history hang off a card by a
+ * foreign key that cascades on both engines, so deleting the card takes them
+ * with it.
+ */
+declare function deleteBoardSlice(from: BoardStore, slice: BoardSlice): Promise<void>;
+//#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 {
+  status: number;
+  message: string;
+  code?: string;
+}
+/**
+ * What each board failure becomes over HTTP.
+ *
+ * The board names its failures and nothing else (`../domain/errors.ts`); the
+ * status code and the sentence a client reads are decided here, once, for both
+ * edges that serve it over HTTP — `kanbo serve` and any app that serves the
+ * same routes — so a client written against one reads the other's failures the
+ * same way. The
+ * table is exhaustive on purpose — a new code in the package fails to compile
+ * until this module says what it means to a caller — and it follows one rule: something the caller asked for that is not
+ * there is 404, something the caller asked for that cannot be done is 400,
+ * 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
+ * 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.
+ *
+ * The five failures about where a board is kept read the same rule. A database
+ * that holds no board this build can speak for is 409 — the setting is there,
+ * the board behind it is not yet, and `board-storage prepare` is what settles
+ * that — and one nobody could reach at all is 503, because nothing about the
+ * request was wrong. A workspace naming no board at all is 404: the caller
+ * asked about a setting that is not there. A board still holding cards when
+ * somebody asks to point the workspace elsewhere is 409, because the answer
+ * would have been yes on an empty board and `board-storage migrate` is what
+ * makes it one. An operation naming cards from two different boards is 400: no
+ * transaction reaches both, so the caller asked for something that cannot be
+ * done. A copy that would land on a card number or a column name the target
+ * already holds under a different id is 409 for the same reason the others
+ * are: the answer would have been yes on a target that did not hold that
+ * board, and `details.conflicts` names every value that clashed.
+ *
+ * A failure may also be renamed here: the package names its codes after the
+ * board, while every error the `/issues` routes answer with is named after the
+ * issue, and a client matching on `issue_*` should not have to learn a second
+ * spelling. The code carries through unchanged when no `code` is given.
+ */
+declare const BOARD_ERROR_RESPONSES: Record<BoardErrorCode, BoardErrorResponse>;
+//#endregion
+export { type AddCommentInput, type AttachRunExecutionInput, BINDING_FILE_PATH, BOARD_ACTOR, BOARD_ERROR_RESPONSES, type BoardActiveRun, type BoardActor, type BoardApproval, type BoardCardWrite, type BoardColumnInput, type BoardColumnPatch, type BoardCopyCounts, BoardError, type BoardErrorCode, type BoardErrorResponse, type BoardLinkedPullRequest, type BoardOps, type BoardPullRequestStanding, type BoardRunProjection, type BoardRunProjectionScope, type BoardRunView, type BoardSlice, type BoardSprint, type BoardStore, type BoardTransactionMode, type BoardWorkspaceIdentity, type BoardWriteScope, type BulkUpdateCardsInput, type BulkUpdateCardsResult, CAPABILITIES_MANIFEST_VERSION, type CloseSprintResult, type CreateCardInput, type CreateCommentOnceInput, type CreateMilestoneInput, type CreateRelationInput, DEFAULT_BOARD_FILE_PATH, DEFAULT_STATUSES, 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 StartRunInput, TRACKED_FIELDS, UNMET_ENTRY_RULE_REASONS, type UnmetEntryRule, type UpdateCardInput, type UpdateMilestoneInput, activityKindOrder, activityText, activityToken, buildCapabilitiesManifest, cardDisplayTitle, commentAuthorReference, createBoardOps, currentUnixSeconds, deleteBoardSlice, diffFieldChanges, emptyCopyCounts, evaluateEntryRules, formatActivityIssueReference, formatExternalSessionRef, formatIssueId, formatPlainActivityValue, ignoreBoardFile, isEmptyActivityValue, isOutsideWriter, maskDatabaseUrl, maskDatabaseUrls, nextIssueIdentity, nextIssueNumber, nextIssueOrder, normalizeCommentAuthorKind, normalizeStatusName, parseActivityStringArray, parseExternalSessionRef, pullRequestFactKeys, readBinding, readBoardSlice, readChangeSeq, readChecklist, readEntryRules, readIssuePrefix, readProjectBinding, readSystemCommentKind, renderCapabilitiesMarkdown, runBoardWrite, serializeEntryRules, toIssueView, writeBinding, writeBoardSlice };
+//# sourceMappingURL=index.d.mts.map