Skip to main content
@clawboo/board-core declares the board’s rules once: which statuses a task can have, which moves between them are legal, when the board fires a task again on its own, why a task is waiting for a person, and what its runs cost. Every layer imports this one copy, so a newly legal move reaches the server, the team engine and the board view together, and a mismatch is a compile error. Use this page when you change a task rule. How the database enforces the rules is on Board internals, and the board as users see it is on The board.

Who uses it

  • @clawboo/db enforces the transition table inside updateStatus and wraps the other rules for whole boards (attentionForTasks, runCostForTasks, isLedgerAutoFireable).
  • @clawboo/team-orchestration uses the fire policy and the person-assignment markers when it dispatches work.
  • The server attaches attention and runCost to every task the board API returns.
  • The SPA builds the status editor from legalTargets, routes tasks into the Needs you column, and shows run cost on cards.
The package has no dependencies at all and imports nothing outside its own files, so it can ship to the browser. apps/web/src/__tests__/browserBundlePurity.test.ts checks that the built files declare no bare import and that state-machine.ts imports nothing; the package’s own tsconfig pins types: [], so a Node global fails the type check. TASK_STATUSES lists the seven statuses in lifecycle order. done and cancelled are terminal.
  • canTransition(from, to) answers one move; a move to the same status is a harmless no-op and returns true.
  • legalTargets(from) returns the targets in table order as a fresh array, empty for a terminal status.
  • isLocked(status) is true for in_progress and in_review: a task someone is working on keeps its assignee.
  • isTerminal(status) is true for done and cancelled.
The server is the authority: updateStatus re-checks the table against the freshly read row, and an illegal move through the board API returns 409. The orphan reaper (reconcileOrphans) writes rows directly but follows the table: a stale in_progress task goes to todo, and a stale in_review task goes to blocked. The board view shows Needs you and then five status columns (Backlog, To do, In progress, Done, Cancelled). An in_review task sits in In progress under a Verifying badge, and every blocked task appears in Needs you.

When a task fires again on its own

ledgerAllowsAutoFire(execs) reads a task’s run ledger, oldest run first, and decides whether the ready-pump may start it again. The team engine’s pump and the server’s scan both call it, so they agree on what will run. autoFireRefusal(execs, now) names why it refuses, including the no-progress brake (brakeUntil, over trailingNoProgressRuns and the verdict runMadeProgress leaves on each run). ledgerWillAutoFire asks whether the task will ever fire by itself: a braked one will. wakes.ts holds the rules for a saved wake: commentMayWake, the one function that decides which comment wakes anyone, and wakeDecision, what the pump does with a waiting wake. trailingFailedRuns counts the runs at the end of the ledger that ended neither succeeded nor cancelled. A task’s sourceDelegationId records who it is bound to: delegationTargetOf reads the agent out of it, and encodeHumanAssignment writes the marker for a task a person assigned, which isHumanAssignment detects. A person-assigned task reports its result on its card instead of to the team’s leader.

Why a task needs a person

taskAttention returns the reason a task waits on a person, or null when the board will move it on its own. The board view puts every task with a reason in Needs you. The result carries the reason, the number of trailing failed runs, and a detail taken from the last run’s error (trimmed to a short excerpt). When the provider refused the account on the last run, it also carries cause (sign_in or billing) and runtime, the runtime whose sign-in to fix; the board shows Fix sign-in for it. accountFailureOf(run) makes that call for one ledger run. It reads the run’s errorClass, which spells the Auth and Billing classes of the error taxonomy in @clawboo/obs; this package imports nothing, so a test in @clawboo/db holds the two spellings together.

Run cost

summarizeRunCost(runs, taskCostUsd) adds up what a task’s runs cost, for the card and the drawer:
  • A run counts only when its costUsd is a finite number, so a run stopped before it priced itself adds nothing.
  • The total is marked as an estimate unless every counted run’s costSource is reported or local; a missing or unknown source counts as an estimate.
  • When every counted run is local, the result also carries local: true: the task ran only on a model the user’s own Ollama served, and the board shows its cost as free.
  • With no counted run, a positive cost stored on the task row itself is returned as an estimate; otherwise the cost is null.
RUN_COST_SOURCES lists reported, local, token-estimate and char-estimate, most trustworthy first. local is a run on a model the user’s own Ollama served, so its $0 is exact.

Priority

A task’s priority column is an integer, and the ready queue serves the higher one first. priority.ts reads and writes it through four named levels, TASK_PRIORITIES: urgent (2), high (1), normal (0, every task’s default) and low (-1), with TASK_PRIORITY_VALUE and TASK_PRIORITY_LABEL for each.
  • clampTaskPriority(n) is the value to store for any requested one: rounded, then held to -1 to 2; anything that is not a finite number is 0. @clawboo/db applies it to every create and update, so a large number cannot jump the queue.
  • taskPriorityOf(n) is the level a stored value reads as. A value written before the clamp, outside the range, reads as the nearest level, and the ready queue orders it the same way.

Text from people and agents

A model reads everything Clawboo hands it as one pile, so text a teammate, a person or a sub-task wrote could read like Clawboo’s own instructions. untrustedText.ts frames such text as data, the same way everywhere:
  • formatInterSessionMessage({ from, kind, seq? }, body) writes one header, [Inter-session message · from=… · kind=… · isUser=false], then every line of the body quoted with | . A value in the header cannot close it early, and an inter-session header inside the body is neutralised (defangInterSessionHeaders), so the body can never present itself as a second header or as the person. formatPeerPost is this for a peer-room post. The team engine uses it for each result in a [Task Update], the Tasks server for each mailbox note riding a tool result, and the server for the comments and results in a task run’s ticket block.
  • defangSectionMarkers(text, labels) turns a line shaped like one of a surface’s own section markers into plain text, for text a surface renders unquoted between its markers (the turn envelope).
  • oneLine(text, max?) folds a title or a name onto one line, cut with … past max.

Test it

Run pnpm --filter @clawboo/board-core test, and pnpm --filter @clawboo/board-core typecheck, which checks the source and the tests against separate tsconfigs. A rule change usually needs a matching case in the board tests of @clawboo/db and in the cascade contract of @clawboo/team-orchestration.
Last modified on November 7, 2026