@anchrd/intel-ui 0.16.1 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-ui",
-  "version": "0.16.1",
+  "version": "0.18.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -16,6 +16,10 @@
     "scripts",
     "!src/**/*.unit.ts",
     "!src/**/*.unit.tsx",
+    "!src/**/*.int.ts",
+    "!src/**/*.int.tsx",
+    "!src/**/*.e2e.ts",
+    "!src/**/*.e2e.tsx",
     "index.html",
     "vite.config.ts",
     "tsconfig.json",
@@ -29,16 +33,20 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@anchrd/intel-contract": "^0.10.0",
+    "@anchrd/intel-contract": "^0.12.0",
     "@assistant-ui/react": "^0.15.4",
     "@assistant-ui/react-ai-sdk": "^1.4.4",
     "@blocknote/core": "^0.52.1",
     "@blocknote/react": "^0.52.1",
     "@blocknote/shadcn": "^0.52.1",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
     "@react-sigma/core": "^5.0.6",
     "@tailwindcss/vite": "^4.3.3",
     "@tanstack/react-query": "^5.101.4",
     "@tanstack/react-router": "^1.170.18",
+    "@tanstack/react-table": "^9.1.0",
     "@vitejs/plugin-react": "^6.0.4",
     "@xyflow/react": "^12.11.2",
     "class-variance-authority": "^0.7.1",

package/src/agent/agent-calendar/agent-calendar.tsx

@@ -30,24 +30,40 @@ const PerSchedule = 5;
  * ⚠️ And only for a zone somebody SET. `useChosenTimezone` answers `null` where nothing was chosen,
  * and then this screen is exactly what it was — no browser guess dressed up as "your time", and no
  * second time on every row for a reader who never asked for one.
+ *
+ * ⚠️ A paused agent gets a sentence over the list, because this is the tab somebody opens to find
+ * out WHETHER something runs (#203). Without it two places on one page said opposite things: the
+ * header read `Paused · no schedule fires`, and this list went on naming the next five times as if
+ * they would happen. The list is kept rather than emptied — what the agent WOULD do is still the
+ * answer to "what did I switch off" — but it may not read as a plan.
  */
 export function AgentCalendar({
   definition,
   now,
+  paused,
 }: {
   definition: AgentDefinition | null;
   // Handed in rather than read from the clock, so the view is a function of its input and a test
   // does not have to travel in time to assert on it.
   now: Date;
+  // ⚠️ Handed in for the same reason, and not read from `useAgentState` here: that hook needs the
+  // router context and a query client, and reaching for it would turn every test of this view into
+  // an integration test of two providers. The caller already holds the state for the header.
+  paused: boolean;
 }) {
   const i18n = useI18n();
   const mine = useChosenTimezone();
   const schedules = definition?.schedules ?? [];
   const upcoming = schedules
-    .flatMap((schedule) =>
+    // ⚠️ The schedule's own position rides along, and it is the only thing that separates two
+    // LITERALLY identical entries (#323). Two schedules with the same cron, zone and target are a
+    // definition somebody can save, and every other part of the key would be equal for them —
+    // including the fire time, which is computed from exactly those three.
+    .flatMap((schedule, position) =>
       nextCronFires(schedule.cron, now, PerSchedule, schedule.timezone).map((at) => ({
         at,
         schedule,
+        position,
       })),
     )
     .sort((left, right) => left.at.getTime() - right.at.getTime());
@@ -94,6 +110,15 @@ export function AgentCalendar({
       {/* ⚠️ An agent with no schedule shows an empty calendar and nothing else (#254). The sentence
           that used to stand here described the emptiness the reader is already looking at; the two
           other states below are different, because each of them is a fact the list cannot show. */}
+      {/* ⚠️ Only where there is a list to qualify. A paused agent WITHOUT schedules shows the same
+          empty calendar it always did — the two states have to stay distinguishable, and a sentence
+          about times that do not happen, over no times at all, describes nothing. Same reason it
+          does not appear over `calendarUnreadable`: that one already says nothing is planned. */}
+      {paused && upcoming.length > 0 ? (
+        <p role="status" className="mt-4 rounded-lg border bg-muted px-4 py-3 text-sm">
+          {i18n.t("agent.calendarPaused")}
+        </p>
+      ) : null}
       {schedules.length === 0 ? null : upcoming.length === 0 ? (
         // Schedules exist and none of them fires: every expression is unusable. A different answer
         // from "no schedules", because it is a different problem and needs a different fix.
@@ -104,7 +129,7 @@ export function AgentCalendar({
         <ol className="mt-4 space-y-2">
           {upcoming.map((entry) => (
             <li
-              key={`${entry.schedule.cron}@${entry.schedule.timezone}:${entry.schedule.target.id}:${entry.at.toISOString()}`}
+              key={`${entry.position}:${entry.schedule.cron}@${entry.schedule.timezone}:${entry.schedule.target.id}:${entry.at.toISOString()}`}
               className="flex flex-wrap items-center gap-3 rounded-lg border bg-card px-4 py-3 text-sm"
             >
               <CalendarClock aria-hidden="true" className="size-4 shrink-0 text-muted-foreground" />

package/src/agent/agent-profile/agent-profile.tsx

@@ -584,6 +584,20 @@ function ToolsSection({
         <ul className="space-y-2">
           {selected.map((handle) => {
             const known = servers.data?.items.find((server) => server.handle === handle);
+            /**
+             * ⚠️ Silence about the question is not a negative answer to it (#350). While the list is
+             * loading — and after a failed read — `servers.data` is `undefined`, and `known` is
+             * then falsy for exactly the same reason as "the portal answered and this handle was
+             * not in it". Drawn as one, a row said `You no longer reach this server` for half a
+             * second on every visit: a statement about a REVOKED permission, and the sentence that
+             * makes somebody re-delegate, sign in to the portal again, or open a ticket.
+             *
+             * It is the same rule `adapters/tools` keeps for `portalConnected` and `reached` on the
+             * server side, where `packages/api/CLAUDE.md` spells it out — a missing field is a
+             * reason to say less, never to refuse more. This is the one place that said it the
+             * other way round.
+             */
+            const answered = servers.isSuccess;
             return (
               <li
                 key={handle}
@@ -597,11 +611,15 @@ function ToolsSection({
                 </span>
                 {/* A server the signed-in person no longer reaches still stands in the definition,
                     and saying so beats drawing it as if it worked. The agent gets nothing from it
-                    either — the catalog is cut against what the delegator reaches. */}
+                    either — the catalog is cut against what the delegator reaches. But only once
+                    the portal has actually answered: until then the row carries the handle and
+                    nothing else, which is everything that is known about it. */}
                 <span className="text-xs text-muted-foreground">
                   {known
                     ? i18n.t("tools.toolCount", { count: String(known.toolCount) })
-                    : i18n.t("agent.toolServerUnavailable")}
+                    : answered
+                      ? i18n.t("agent.toolServerUnavailable")
+                      : null}
                 </span>
                 <button
                   type="button"

package/src/agent/agent.tsx

@@ -104,7 +104,14 @@ export function AgentPanel({ node }: { node: Node }) {
         </TabsContent>
         <TabsContent value="calendar" className="flex min-h-0 flex-col">
           {tab === "calendar" ? (
-            <AgentCalendar definition={agent.definition} now={new Date()} />
+            <AgentCalendar
+              definition={agent.definition}
+              now={new Date()}
+              // ⚠️ The same `state` the header reads, so the two cannot disagree about one agent —
+              // and the pause button writes its answer straight into this query key, so the note
+              // goes the moment somebody resumes, without this tab refetching (#203).
+              paused={state.data?.paused ?? false}
+            />
           ) : null}
         </TabsContent>
         <TabsContent value="log" className="flex min-h-0 flex-col">
@@ -314,7 +321,25 @@ export function AgentActions({
     onSuccess: () => queryClient.invalidateQueries({ queryKey: ["agent-runs", agentId] }),
   });
 
-  const targets = definition?.schedules.map((schedule) => schedule.target) ?? [];
+  /**
+   * ⚠️ One entry per TARGET, not per schedule (#323). Two schedules on the same flow — 08:00 and
+   * 17:00 — are the ordinary configuration this list exists for, and they produced two menu items
+   * nobody could choose between: both start the same run, and the time that tells them apart is
+   * not on either. They also shared a React key.
+   *
+   * Deduplicating is the honest reading of what this button does. "Run now" fires the target
+   * immediately; the schedule is the thing it is deliberately NOT waiting for, so which of the two
+   * entries somebody picked could never have meant anything. The alternative — two entries labelled
+   * with their cron — offers a choice that has no consequence.
+   */
+  const targets = [
+    ...new Map(
+      (definition?.schedules ?? []).map((schedule) => [
+        `${schedule.target.kind}:${schedule.target.id}`,
+        schedule.target,
+      ]),
+    ).values(),
+  ];
   const reason = denied
     ? i18n.t("agent.notPermitted")
     : state.isError

package/src/board/board-calendar/board-calendar.tsx

@@ -0,0 +1,89 @@
+import { useMemo, useState } from "react";
+import { shownTasks } from "@/board/board-data/board-data.ts";
+import { type BoardItem, boardSchedule } from "@/board/board-items/board-items.ts";
+import type { BoardViewProps } from "@/board/board-views/board-views.types.ts";
+import { ItemCalendar } from "@/components/ui/item-calendar.tsx";
+import { useI18n } from "@/i18n/i18n-context.tsx";
+
+// Which day a week starts on, in the reader's own language rather than fixed at Sunday. Intl knows
+// it; a hard-coded 0 would draw a German month the way an American reads one.
+function weekStart(locale: string): number {
+  const info = new Intl.Locale(locale);
+  // Not every runtime answers, and the ones that do disagree on where it lives. Monday is the ISO
+  // default and the safer of the two guesses for a European installation.
+  const week = (info as unknown as { getWeekInfo?(): { firstDay: number } }).getWeekInfo?.();
+  const firstDay = week?.firstDay ?? 1;
+  // Intl counts Monday as 1 and Sunday as 7; `Date.getDay()` counts Sunday as 0.
+  return firstDay % 7;
+}
+
+/**
+ * The board as a month (anchrd/intel#286).
+ *
+ * ⚠️ It draws `boardSchedule` and nothing else. That adapter is the ONE reading of a task as a
+ * dated thing, and Gantt (anchrd/intel#293) is a second renderer over the same list — a calendar
+ * that read `dueDate` itself would be the second reading, and the two would disagree about the case
+ * that is actually subtle (a task with a start date and no due date).
+ *
+ * ⚠️ A task without a due date is NOT in the grid and is counted underneath it. Nothing vanishes
+ * quietly: a month showing eleven of twenty tasks with no word about the other nine is a month
+ * that answers "what is due" with a number that is wrong.
+ */
+export function BoardCalendar({ board, select, showArchived }: BoardViewProps) {
+  const i18n = useI18n();
+  const [month, setMonth] = useState(() => {
+    const now = new Date();
+    return new Date(now.getFullYear(), now.getMonth(), 1);
+  });
+
+  const schedule = useMemo(
+    () => boardSchedule(shownTasks(board.tasks, showArchived), board.statuses, board.blockedBy),
+    [board.tasks, board.statuses, board.blockedBy, showArchived],
+  );
+
+  return (
+    <div className="flex min-h-0 flex-1 flex-col gap-3 p-6">
+      <ItemCalendar<BoardItem>
+        items={schedule.items}
+        month={month}
+        onMonthChange={setMonth}
+        locale={i18n.locale}
+        weekStartsOn={weekStart(i18n.locale)}
+        labels={{
+          previous: i18n.t("board.calendar.previous"),
+          next: i18n.t("board.calendar.next"),
+          today: i18n.t("board.calendar.today"),
+          more: (count) => i18n.t("board.calendar.more", { count }),
+        }}
+        renderItem={(item) => (
+          <button
+            type="button"
+            onClick={() => select(item.id)}
+            // ⚠️ The same click as a card in a lane and a node in the graph: it opens the one
+            // detail panel. Three views with three different ideas of what selecting means would
+            // be three products.
+            // The status is on the left edge as well as in the dot: at this size a two-millimetre
+            // dot is the whole of the colour coding, and a bar down the side survives a glance
+            // across a whole month.
+            className={`flex w-full min-w-0 items-center gap-1.5 rounded border-l-2 bg-muted/60 px-1.5 py-0.5 text-left text-xs outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring ${item.status.tone.chip}`}
+          >
+            <span
+              aria-hidden="true"
+              className={`size-1.5 shrink-0 rounded-full ${item.status.tone.dot}`}
+            />
+            <span className="min-w-0 truncate">{item.name}</span>
+            {/* The status in words as well as in colour — the grid is the one place a reader has
+                no column heading to fall back on. */}
+            <span className="sr-only">{item.status.label}</span>
+            {item.blocked ? <span className="sr-only">{i18n.t("board.blocked")}</span> : null}
+          </button>
+        )}
+      />
+      {schedule.undated.length > 0 ? (
+        <p className="text-sm text-muted-foreground">
+          {i18n.t("board.calendar.undated", { count: schedule.undated.length })}
+        </p>
+      ) : null}
+    </div>
+  );
+}

package/src/board/board-card/board-card.tsx

@@ -0,0 +1,106 @@
+import type { BoardAssignee, BoardTask } from "@anchrd/intel-contract";
+import { Ban, Bot, CalendarDays, ListTree, User } from "lucide-react";
+import { useEntryTitle } from "@/agent/agent-entry-title/agent-entry-title.ts";
+import { useI18n } from "@/i18n/i18n-context.tsx";
+import { useUserName } from "@/user-name/user-name.ts";
+
+/**
+ * Who a task is on.
+ *
+ * ⚠️ An id is never shown, and never falls back to being shown. Intel has no user directory
+ * (`useUserName`), so most person ids cannot be resolved here — but an unassigned card and a card
+ * assigned to somebody this browser cannot name are two different facts, and drawing them the same
+ * would be the lie the DoD's "assignee on the card" exists to prevent. So the marker stays and only
+ * the name goes: "assigned", with nobody named.
+ */
+export function BoardAssigneeLabel({ assignee }: { assignee: BoardAssignee }) {
+  const i18n = useI18n();
+  const person = useUserName(assignee.type === "user" ? assignee.id : null);
+  const agent = useEntryTitle(assignee.type === "agent" ? assignee.nodeId : "");
+  const Icon = assignee.type === "agent" ? Bot : User;
+  const name =
+    assignee.type === "agent" ? agent.title : (person ?? i18n.t("board.assignee.unnamed"));
+  return (
+    <span className="inline-flex min-w-0 items-center gap-1 text-xs text-muted-foreground">
+      <Icon aria-hidden="true" className="size-3.5 shrink-0" />
+      <span className="truncate">{name}</span>
+    </span>
+  );
+}
+
+/**
+ * The card, wherever it is drawn: in a lane, and in the overlay that follows the pointer.
+ *
+ * ⚠️ It never renders the description. A card is a card — what needs more than a line is opened,
+ * and the panel is where the description lives. The board arrives as ONE document (#285), so no
+ * card causes a request of its own either; there is nothing left for a card to load.
+ */
+export function BoardCardBody({
+  task,
+  statusLabel,
+  toneDot,
+  blocked,
+  subtasks,
+}: {
+  task: BoardTask;
+  statusLabel: string;
+  toneDot: string;
+  blocked: boolean;
+  subtasks: { done: number; total: number };
+}) {
+  const i18n = useI18n();
+  return (
+    <div className="flex min-w-0 flex-col gap-2">
+      <div className="flex min-w-0 items-start gap-2">
+        <span
+          aria-hidden="true"
+          className={`mt-1 size-2 shrink-0 rounded-full ${toneDot}`}
+          data-slot="board-card-status"
+        />
+        <span className="min-w-0 text-sm font-medium break-words">{task.title}</span>
+      </div>
+      {/* The colour above says the status to whoever sees colour; this says it to everybody else,
+          and it is what makes the card readable in a screen reader's list of cards. */}
+      <span className="sr-only">{statusLabel}</span>
+      {blocked ? (
+        <span className="inline-flex w-fit items-center gap-1 rounded-md border border-destructive px-1.5 py-0.5 text-xs text-destructive">
+          <Ban aria-hidden="true" className="size-3" />
+          {i18n.t("board.blocked")}
+        </span>
+      ) : null}
+      {task.labels.length > 0 ? (
+        <ul className="flex flex-wrap gap-1">
+          {/* Once per word, which is what makes `key={label}` unique by construction rather than by
+              decoration (anchrd/intel#318) — the same reading the detail panel has. */}
+          {[...new Set(task.labels)].map((label) => (
+            <li
+              key={label}
+              className="rounded-md border bg-muted px-1.5 py-0.5 text-xs text-muted-foreground"
+            >
+              {label}
+            </li>
+          ))}
+        </ul>
+      ) : null}
+      <div className="flex flex-wrap items-center gap-3">
+        {task.assignee ? <BoardAssigneeLabel assignee={task.assignee} /> : null}
+        {task.dueDate ? (
+          <span className="inline-flex items-center gap-1 text-xs text-muted-foreground">
+            <CalendarDays aria-hidden="true" className="size-3.5" />
+            <time dateTime={task.dueDate}>
+              {new Date(`${task.dueDate}T00:00:00`).toLocaleDateString(i18n.locale)}
+            </time>
+          </span>
+        ) : null}
+        {/* ⚠️ A counter and not the children themselves. Drawing a subtask as a card of its own
+            would put the same work on the board twice — once under its parent and once beside it. */}
+        {subtasks.total > 0 ? (
+          <span className="inline-flex items-center gap-1 text-xs text-muted-foreground">
+            <ListTree aria-hidden="true" className="size-3.5" />
+            {i18n.t("board.subtaskCount", { done: subtasks.done, total: subtasks.total })}
+          </span>
+        ) : null}
+      </div>
+    </div>
+  );
+}

package/src/board/board-data/board-data.ts

@@ -0,0 +1,241 @@
+import {
+  ArchivedBoardStatusId,
+  type BoardDocument,
+  type BoardStatus,
+  type BoardTask,
+  type NodeBoard,
+} from "@anchrd/intel-contract";
+import { type QueryClient, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useMemo } from "react";
+import { useIntelRouterContext } from "@/router/router-context.ts";
+import type { BoardHandle } from "./board-data.types.ts";
+
+export const boardKey = (nodeId: string) => ["board", nodeId] as const;
+
+// The columns somebody works in. `archived` is a shelf and not a stage, so it is out of every list
+// that offers a status to move a task to and out of the lanes drawn by default.
+export function visibleStatuses(statuses: BoardStatus[]): BoardStatus[] {
+  return statuses.filter((status) => status.id !== ArchivedBoardStatusId);
+}
+
+/**
+ * The board in the order it is drawn: by column, then by the server's fractional key.
+ *
+ * ⚠️ `order` is only defined WITHIN a column — the server mints a key between the neighbours a
+ * move named, and those neighbours are the ones in the column it lands in. Sorting the whole board
+ * by `order` alone would therefore interleave columns by an accident of key history. An unknown
+ * status sorts last rather than being dropped: a task whose column was configured away is still a
+ * task, and a view that silently loses it is worse than one that shows it at the end.
+ *
+ * ⚠️ And one entry per task id, however often the document names it (anchrd/intel#321). Here rather
+ * than in each renderer, for the same reason `shownTasks` is here: the kanban keys its cards by
+ * `task.id`, the table its rows, Gantt its bars and the graph its nodes, and React's answer to two
+ * children under one key is "duplicated and/or omitted — the behavior is unsupported". Four views
+ * would otherwise need four copies of one sentence, and the first bug is the day two of them
+ * disagree about which of the pair is on the board.
+ *
+ * ⚠️ Folded AFTER the sort, so the entry that survives is the one that would have been drawn first,
+ * and `byId` therefore answers with the card the reader is looking at.
+ *
+ * ⚠️ This is a decision about a drawing and not the one `upgradeStoredBoard` deliberately does not
+ * make (`repeatedBoardId`, packages/api). Two tasks under one id are two whole tasks; folding them
+ * on the SERVER's read would be written back by the next save and the second one would be gone for
+ * good. Nothing here writes anything — the document still holds both, and the day the pair is
+ * repaired the board draws both again.
+ */
+export function orderedTasks(document: BoardDocument): BoardTask[] {
+  const rank = new Map(document.statuses.map((status, index) => [status.id, index]));
+  const last = document.statuses.length;
+  const sorted = [...document.tasks].sort(
+    (left, right) =>
+      (rank.get(left.status) ?? last) - (rank.get(right.status) ?? last) ||
+      (left.order < right.order ? -1 : left.order > right.order ? 1 : 0) ||
+      left.id.localeCompare(right.id),
+  );
+  const seen = new Set<string>();
+  return sorted.filter((task) => {
+    if (seen.has(task.id)) return false;
+    seen.add(task.id);
+    return true;
+  });
+}
+
+/**
+ * Which columns mean the work is finished (anchrd/intel#311).
+ *
+ * ⚠️ Read off the status list's own `terminal` flag, never off a position. This used to be "the last
+ * column before `archived`", reasoned by symmetry with the server's rule for a new task — and a
+ * board configured to `… done → blocked → archived` then counted "blocked" as finished, with a wrong
+ * blocked marker as the only symptom. A status says it for itself now, and this is the ONE place the
+ * UI asks.
+ *
+ * ⚠️ A status a task still stands in that the board no longer lists is NOT finished: nothing says it
+ * is, and treating an unknown column as done would let deleting a column clear blockers.
+ */
+export function settledIn(statuses: BoardStatus[]): ReadonlySet<string> {
+  return new Set(statuses.filter((status) => status.terminal).map((status) => status.id));
+}
+
+/**
+ * What a view draws once the shelf switch has had its say.
+ *
+ * ⚠️ One rule for every view, here rather than in each of them. The kanban could have done it by
+ * leaving out a lane, the table by filtering a column, the graph by dropping nodes and Gantt by
+ * leaving a bar undrawn — four implementations of one sentence, and the first bug is the day two of
+ * them disagree about whether an archived subtask under a live parent counts as hidden.
+ */
+export function shownTasks(tasks: BoardTask[], showArchived: boolean): BoardTask[] {
+  return showArchived ? tasks : tasks.filter((task) => task.status !== ArchivedBoardStatusId);
+}
+
+/**
+ * The board document with one task's write folded in.
+ *
+ * ⚠️ Patched, never refetched. Every task operation answers with the ONE task it wrote (#285), and
+ * a board of five thousand cards would otherwise re-read all of them after each drag. The status
+ * list travels along because `configureBoard` writes that instead of a task.
+ */
+export function withTask(document: BoardDocument, task: BoardTask): BoardDocument {
+  const index = document.tasks.findIndex((existing) => existing.id === task.id);
+  const tasks =
+    index === -1
+      ? [...document.tasks, task]
+      : document.tasks.map((existing) => (existing.id === task.id ? task : existing));
+  return { ...document, tasks };
+}
+
+/**
+ * The board with a task and everything under it gone.
+ *
+ * ⚠️ Two things go, not one. The server cascades to every descendant AND clears the `dependsOn`
+ * entries that pointed into the hole, so a cache that only dropped the named task would keep
+ * showing subtasks whose parent no longer exists and blocked markers waiting on nothing. The
+ * server's answer carries a count and no ids, so the same walk is done here — from the same
+ * `parentId` field, which is the whole hierarchy.
+ */
+export function withoutTask(document: BoardDocument, taskId: string): BoardDocument {
+  const gone = new Set([taskId]);
+  // A board is capped at five thousand tasks and five levels, so repeating the sweep until it
+  // stops growing is bounded and needs no ordering of its own.
+  for (let grew = true; grew; ) {
+    grew = false;
+    for (const task of document.tasks) {
+      if (task.parentId !== null && gone.has(task.parentId) && !gone.has(task.id)) {
+        gone.add(task.id);
+        grew = true;
+      }
+    }
+  }
+  return {
+    ...document,
+    tasks: document.tasks
+      .filter((task) => !gone.has(task.id))
+      .map((task) =>
+        task.dependsOn.some((id) => gone.has(id))
+          ? { ...task, dependsOn: task.dependsOn.filter((id) => !gone.has(id)) }
+          : task,
+      ),
+  };
+}
+
+// One place writes the cache, so a mutation that forgets the version id cannot exist: the next
+// read has to see the version the write produced, or the board would offer to write against one
+// that is already superseded.
+function patch(
+  client: QueryClient,
+  nodeId: string,
+  change: (document: BoardDocument) => BoardDocument,
+  versionId: string,
+): void {
+  client.setQueryData<NodeBoard>(boardKey(nodeId), (current) =>
+    current ? { ...current, board: change(current.board), versionId } : current,
+  );
+}
+
+/**
+ * One board, and the only way any of its views reads or writes it (anchrd/intel#286).
+ *
+ * ⚠️ Every mutation mints its own `idempotencyKey`. A retried drag must not move a card twice, and
+ * a key minted by the view would be one the view has to remember across a re-render it does not
+ * control.
+ *
+ * ⚠️ A failed write invalidates rather than patching. The five operations are the only writers,
+ * but they are not the only ones: an agent holds the same board over MCP, and a refusal is the one
+ * moment this screen knows its copy may be behind.
+ */
+export function useBoard(nodeId: string): BoardHandle {
+  const { data } = useIntelRouterContext();
+  const client = useQueryClient();
+  const query = useQuery({ queryKey: boardKey(nodeId), queryFn: () => data.getBoard(nodeId) });
+  const document = query.data?.board ?? null;
+
+  const derived = useMemo(() => {
+    const statuses = document?.statuses ?? [];
+    const tasks = document ? orderedTasks(document) : [];
+    const byId = new Map(tasks.map((task) => [task.id, task]));
+    const childrenOf = new Map<string, BoardTask[]>();
+    for (const task of tasks) {
+      if (task.parentId === null) continue;
+      const siblings = childrenOf.get(task.parentId);
+      if (siblings) siblings.push(task);
+      else childrenOf.set(task.parentId, [task]);
+    }
+    const settledStatuses = settledIn(statuses);
+    return {
+      statuses,
+      tasks,
+      byId,
+      childrenOf,
+      settled: (task: BoardTask) => settledStatuses.has(task.status),
+      // A dependency on a task that is not on this board cannot exist (#285 refuses it on the
+      // write path), so an id that resolves to nothing here is one the reader may not see — and it
+      // is left out rather than counted as blocking, because a marker nobody can explain is worse
+      // than none.
+      blockedBy: (task: BoardTask) =>
+        task.dependsOn.flatMap((id) => {
+          const other = byId.get(id);
+          return other && !settledStatuses.has(other.status) ? [other] : [];
+        }),
+    };
+  }, [document]);
+
+  const failed = () => client.invalidateQueries({ queryKey: boardKey(nodeId) });
+
+  const add = useMutation({
+    mutationFn: (input: Parameters<BoardHandle["add"]["mutate"]>[0]) =>
+      data.addBoardTask({ ...input, nodeId, idempotencyKey: crypto.randomUUID() }),
+    onSuccess: (result) =>
+      patch(client, nodeId, (d) => withTask(d, result.task), result.version.id),
+    onError: failed,
+  });
+  const update = useMutation({
+    mutationFn: (input: Parameters<BoardHandle["update"]["mutate"]>[0]) =>
+      data.updateBoardTask({ ...input, nodeId, idempotencyKey: crypto.randomUUID() }),
+    onSuccess: (result) =>
+      patch(client, nodeId, (d) => withTask(d, result.task), result.version.id),
+    onError: failed,
+  });
+  const move = useMutation({
+    mutationFn: (input: Parameters<BoardHandle["move"]["mutate"]>[0]) =>
+      data.moveBoardTask({ ...input, nodeId, idempotencyKey: crypto.randomUUID() }),
+    onSuccess: (result) =>
+      patch(client, nodeId, (d) => withTask(d, result.task), result.version.id),
+    onError: failed,
+  });
+  const remove = useMutation({
+    mutationFn: (input: { taskId: string }) =>
+      data.deleteBoardTask({ ...input, nodeId, idempotencyKey: crypto.randomUUID() }),
+    onSuccess: (result, input) =>
+      patch(client, nodeId, (d) => withoutTask(d, input.taskId), result.version.id),
+    onError: failed,
+  });
+  const configure = useMutation({
+    mutationFn: (statuses: Parameters<BoardHandle["configure"]["mutate"]>[0]) =>
+      data.configureBoard({ nodeId, statuses, idempotencyKey: crypto.randomUUID() }),
+    onSuccess: (result) =>
+      patch(client, nodeId, (d) => ({ ...d, statuses: result.statuses }), result.version.id),
+    onError: failed,
+  });
+
+  return { nodeId, query, ...derived, add, update, move, remove, configure };
+}