@anchrd/intel-ui 0.33.0 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-ui",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -33,7 +33,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@anchrd/intel-contract": "^0.20.0",
+    "@anchrd/intel-contract": "^0.21.0",
     "@blocknote/core": "^0.52.1",
     "@blocknote/react": "^0.52.1",
     "@blocknote/shadcn": "^0.52.1",

package/src/app/app-tree/app-tree.tsx

@@ -150,7 +150,47 @@ export function AppTree() {
     return calls.items.map((flow) => flowEntry(flow, openable.has(flow.id)));
   }
 
-  const parents: Level[] = [{ id: null, type: "folder" }, ...expanded];
+  /**
+   * The levels that still have a row to hang on — `expanded` minus everything the tree no longer
+   * shows (#521).
+   *
+   * ⚠️ `expanded` is only ever added to. A folder that was opened and has since left the tree —
+   * archived, moved away, its share revoked — used to keep its level in `useQueries` for the rest
+   * of the session, and every write from then on re-read a list nothing draws. Nothing was wrong on
+   * screen (`isOpen` needs the row, so the level was never rendered); the requests were simply paid
+   * for, and the number grew with the length of the SESSION rather than with what is on screen.
+   *
+   * ⚠️ Read from the cache rather than from `levels` below, and that is not a shortcut: the answer
+   * is needed BEFORE `useQueries` is told what to load, and deriving it from the results afterwards
+   * can only correct the list one render too late — by which time the request has been made.
+   *
+   * ⚠️ A walk down from the root, not "is the row anywhere": a level whose own row is gone must not
+   * keep vouching for the levels under it, or a whole opened branch would survive its top.
+   *
+   * ⚠️ A row is enough, and `openable` is deliberately NOT part of it although `isOpen` checks it.
+   * `reveal` opens a folder BEFORE the invalidation that gives it its arrow, so a folder that was
+   * empty a moment ago still says `openable: false` at that instant — judging on it would close the
+   * folder #519 exists to have opened. A refetch does not make a level unknown either: TanStack
+   * keeps the previous data while it refetches, so an ordinary invalidation closes nothing.
+   */
+  const rowLevel = (entry: TreeEntry) =>
+    `${entry.kind === "folder" ? "folder" : "flow"}:${entry.id}`;
+  const rootLevel: Level = { id: null, type: "folder" };
+  const open: Level[] = [];
+  let frontier: Level[] = [rootLevel];
+  let waiting = [...expanded];
+  while (frontier.length > 0 && waiting.length > 0) {
+    const shown = new Set(
+      frontier.flatMap((level) =>
+        (queryClient.getQueryData<TreeEntry[]>(levelKey(level)) ?? []).map(rowLevel),
+      ),
+    );
+    frontier = waiting.filter((level) => shown.has(`${level.type}:${level.id}`));
+    waiting = waiting.filter((level) => !frontier.includes(level));
+    open.push(...frontier);
+  }
+
+  const parents: Level[] = [rootLevel, ...open];
   const levels = useQueries({
     queries: parents.map((parent) => ({
       queryKey: levelKey(parent),
@@ -167,10 +207,19 @@ export function AppTree() {
     levels[parents.findIndex((entry) => entry.id === level.id && entry.type === level.type)];
   const root = levels[0];
 
-  function toggle(level: Level & { id: string }, open: boolean) {
+  // ⚠️ The list the reader opened is also trimmed here, and not only where it is read: `open`
+  // above keeps a departed level from being LOADED, but the entry itself would otherwise sit in
+  // `expanded` until the tab is closed — and a folder that comes back would come back open, which
+  // is a claim about a gesture nobody made in this tree. A gesture is where trimming is free: it
+  // is an event, so there is no render to loop through.
+  function toggle(level: Level & { id: string }, wanted: boolean) {
     setExpanded((current) => {
-      const rest = current.filter((entry) => entry.id !== level.id || entry.type !== level.type);
-      return open ? [...rest, level] : rest;
+      const rest = current.filter(
+        (entry) =>
+          (entry.id !== level.id || entry.type !== level.type) &&
+          open.some((live) => live.id === entry.id && live.type === entry.type),
+      );
+      return wanted ? [...rest, level] : rest;
     });
   }
 
@@ -441,8 +490,10 @@ export function AppTree() {
     // reader may see" (#59). The difference is an arrow that keeps its promise — before, it stood
     // on every folder and every flow, empty ones included.
     const expandable = entry.openable;
+    // ⚠️ `open`, not `expanded`: what is drawn and what is loaded answer the same question, or the
+    // tree would draw a level it never asked for (#521).
     const isOpen =
-      expandable && expanded.some((open) => open.id === entry.id && open.type === level.type);
+      expandable && open.some((live) => live.id === entry.id && live.type === level.type);
     const Icon = isOpen && isFolder ? FolderOpen : kindIcons[entry.kind];
     const area = entry.type === "flow" ? "/flows" : "/nodes";
     const isActive = location.select === entry.id && location.pathname === area;

package/src/app/tree-move/tree-move.tsx

@@ -47,11 +47,11 @@ export function treeLevelKey(parentId: string | null): readonly unknown[] {
  * level is not always the one the record names: since #429 a shared row also stands at the root
  * (`levelsToClear`).
  *
- * ⚠️ What it costs is one request per MOUNTED level, and that is not the same as "per level on
- * screen": `expanded` in `app-tree.tsx` is only ever added to, so a folder that was opened and has
- * since left the tree — archived, moved away — keeps its query mounted for the rest of the session
- * and is re-read by every write from then on. Nothing is wrong on screen; the requests are simply
- * paid for. #521 prunes that list, and until it does, this is the honest bound.
+ * ⚠️ What it costs is one request per level the reader has OPEN — bounded by the screen, not by how
+ * long the tab has been sitting there. `app-tree.tsx` loads a level only while the row it hangs on
+ * still stands in the level above it, so a folder that was opened and has since left the tree —
+ * archived, moved away, its share revoked — takes its query with it rather than being re-read by
+ * every write for the rest of the session.
  *
  * The same prefix is what `archive.tsx` has always used for the same reason: a row can come back
  * anywhere, and the screen writing it does not know where.

package/src/data/request-refusal/refusal-notice.tsx

@@ -0,0 +1,36 @@
+import type { Refusal } from "@/data/request-refusal/request-refusal.ts";
+import { useI18n } from "@/i18n/i18n-context.tsx";
+
+/**
+ * What a refusal is told with, on every surface that has one.
+ *
+ * ⚠️ A refusal is not a failure, and the difference is the whole of #430. Somebody whose share was
+ * revoked was left in front of "Loading…" — the worst answer of all, because it says the program is
+ * still working. They get a sentence and no retry button: the answer was final, and a button that
+ * changes nothing is an invitation to keep waiting.
+ *
+ * ⚠️ One sentence for `404`, whichever of its two reasons applies. Intel answers the same status
+ * for "no such node" and "not for you" on purpose — `requireVisible` in
+ * `packages/api/src/nodes/nodes.ts` — and a screen that told them apart would undo that from the
+ * other side.
+ *
+ * ⚠️ One function rather than a block per branch, because two answers to one question on one
+ * surface IS #445. A screen's halves — the empty level, the selected item, the view beside it — are
+ * asked the same thing, and copies drift.
+ *
+ * ⚠️ **Why this became shared here and not one copy earlier.** `nodes.tsx` (#445) and `flows.tsx`
+ * (#557) each carried an identical version, and #557 wrote its reason on the second one: this
+ * repository builds an abstraction after the third time it hurts, not the second. #568 is the third
+ * time — `?view=graph` and `?view=runs` are the third and fourth surface asking for the same
+ * sentence — so what would have been a third copy is this file. The rule did not bend; it was met.
+ */
+export function RefusalNotice({ refusal }: { refusal: Refusal }) {
+  const i18n = useI18n();
+  return (
+    <div role="status" className="grid flex-1 place-items-center p-8 text-center text-sm">
+      <p className="max-w-sm text-muted-foreground">
+        {i18n.t(refusal === "no-permission" ? "common.noPermission" : "common.noAccess")}
+      </p>
+    </div>
+  );
+}

package/src/entry-picker/entry-picker.tsx

@@ -92,6 +92,24 @@ export function EntryPicker({
   }, [wanted]);
   const eligible = useMemo(() => nodes.filter(pickable), [nodes, pickable]);
 
+  /**
+   * Whether an entry stands on the picker's start level.
+   *
+   * ⚠️ The root is not `parentId === null` but the upper edge of what the reader may see — the same
+   * rule #429 gave the server in `levelPredicate`, at the second surface (#447). A recipient whose
+   * only access is a NESTED share carries a `parentId` pointing at a folder that is not in the list
+   * at all: under the old rule their start level was empty and STAYED empty, because the folder
+   * that would open it can never be clicked. Only searching reached them.
+   *
+   * ⚠️ Nothing is added by this. The list is what `getNodeGraph()` — and `listFlows()` where flows
+   * were asked for — answered, and the answer is already the authorized one. What changes is only
+   * which level an entry stands on.
+   */
+  const rooted = useMemo(() => {
+    const present = new Set(nodes.map((node) => node.id));
+    return (entry: PickerEntry) => entry.parentId === null || !present.has(entry.parentId);
+  }, [nodes]);
+
   // Searching looks at every eligible node wherever it sits; browsing looks at one level. The two
   // are the same list seen two ways, which is why a result can be picked from either.
   const searching = query.trim().length > 0;
@@ -100,8 +118,10 @@ export function EntryPicker({
       const needle = query.trim().toLowerCase();
       return eligible.filter((node) => node.title.toLowerCase().includes(needle)).slice(0, 50);
     }
-    return nodes.filter((node) => node.parentId === openFolder);
-  }, [searching, query, eligible, nodes, openFolder]);
+    return nodes.filter((node) =>
+      openFolder === null ? rooted(node) : node.parentId === openFolder,
+    );
+  }, [searching, query, eligible, nodes, openFolder, rooted]);
 
   // The way back up, as the chain of folders that leads to the open one.
   const trail = useMemo(() => {
@@ -111,10 +131,13 @@ export function EntryPicker({
       const folder = nodes.find((node) => node.id === current);
       if (!folder) break;
       chain.unshift(folder);
-      current = folder.parentId;
+      // ⚠️ The chain ends where the start level begins, and by the same rule that decides it. A
+      // folder at the upper edge has an ancestor the reader cannot see; walking into it would look
+      // for a level that does not exist here, and the "top" button above leads to this one.
+      current = rooted(folder) ? null : folder.parentId;
     }
     return chain;
-  }, [openFolder, nodes]);
+  }, [openFolder, nodes, rooted]);
 
   const chosen = nodes.find((node) => node.id === value) ?? null;
 

package/src/flow-runs/flow-runs.tsx

@@ -2,6 +2,8 @@ import type { FlowRunSummary } from "@anchrd/intel-contract/flow-run";
 import { useInfiniteQuery, useQuery } from "@tanstack/react-query";
 import { ChevronDown, ChevronRight, CornerDownRight } from "lucide-react";
 import { useState } from "react";
+import { RefusalNotice } from "@/data/request-refusal/refusal-notice.tsx";
+import { refusalOf } from "@/data/request-refusal/request-refusal.ts";
 import type { I18n } from "@/i18n/i18n.types.ts";
 import { useI18n } from "@/i18n/i18n-context.tsx";
 import { useIntelRouterContext } from "@/router/router-context.ts";
@@ -45,6 +47,11 @@ export function FlowRuns({ flowId }: { flowId: string }) {
     getNextPageParam: (last) => last.nextCursor,
   });
   const items = runs.data?.pages.flatMap((page) => page.items) ?? [];
+  // ⚠️ This list's own refusal, told here rather than upstream (#568). The screen above answers
+  // whether the flow may be opened; `listFlowRuns` answers whether its history may be read, and it
+  // can refuse on its own. Everything that is not a refusal keeps the sentence and the button
+  // below — a `502` really can answer differently next time.
+  const refusal = refusalOf(runs.error);
 
   return (
     <section aria-label={i18n.t("runs.title")} className="flex min-h-0 flex-1 flex-col">
@@ -68,7 +75,8 @@ export function FlowRuns({ flowId }: { flowId: string }) {
         {runs.isPending && (
           <p className="text-sm text-muted-foreground">{i18n.t("common.loading")}</p>
         )}
-        {runs.isError && (
+        {refusal && <RefusalNotice refusal={refusal} />}
+        {runs.isError && !refusal && (
           <div role="alert" className="space-y-3 text-sm">
             <p className="text-destructive">{i18n.t("runs.failedToLoad")}</p>
             <button

package/src/flows/flows.tsx

@@ -24,15 +24,19 @@ import {
   useReactFlow,
 } from "@xyflow/react";
 import { FileSearch, Info, Send, Wrench } from "lucide-react";
-import { useEffect, useId, useMemo, useState } from "react";
+import { createContext, useContext, useEffect, useId, useMemo, useState } from "react";
 import { TreeEntryMediaType } from "@/app/app-tree/app-tree.tsx";
 import { ViewToggle } from "@/app/view-toggle/view-toggle.tsx";
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip";
+import { IntelRequestError } from "@/data/intel-data-provider/intel-data-provider.ts";
+import { RefusalNotice } from "@/data/request-refusal/refusal-notice.tsx";
+import { refusalOf } from "@/data/request-refusal/request-refusal.ts";
 import { EntryPicker } from "@/entry-picker/entry-picker.tsx";
 import { FlowRuns } from "@/flow-runs/flow-runs.tsx";
 import { nodeIcon } from "@/flows/node-icon/node-icon.ts";
 import { NodePalette, usePaletteOpen } from "@/flows/node-palette/node-palette.tsx";
 import { GraphPane } from "@/graph-pane/graph-pane.tsx";
+import type { I18n } from "@/i18n/i18n.types.ts";
 import { useI18n } from "@/i18n/i18n-context.tsx";
 import { Modal } from "@/modal/modal.tsx";
 import { useIntelRouterContext } from "@/router/router-context.ts";
@@ -90,9 +94,24 @@ const flowKindOfEntry: Record<string, FlowNode["kind"] | undefined> = {
   flow: "subflow",
 };
 
+/**
+ * The tree links of this flow that name nothing any more, by resource id (#509).
+ *
+ * ⚠️ A context rather than a field on the node's `data`, because the canvas nodes are React state
+ * that the loaded version owns: writing the answer of a query into them would put a second writer
+ * on that state and let a background refetch land in the middle of an edit. The set is read where
+ * it is drawn and nowhere else.
+ */
+const InvalidLinks = createContext<ReadonlySet<string>>(new Set());
+
 function FlowCard({ data, selected }: NodeProps<CanvasNode>) {
   const i18n = useI18n();
   const contract = data.node;
+  const invalidLinks = useContext(InvalidLinks);
+  // ⚠️ Said in a WORD, not by colour alone. A card that only turned red would say nothing to a
+  // colour-blind reader and nothing at all to a screen reader — and this is the one state on the
+  // canvas that stops the flow from running (#509).
+  const broken = isLinkNode(contract) && invalidLinks.has(contract.configuration.resourceId);
   const Icon = nodeIcon[contract.kind];
   const branching = contract.kind === "condition";
   // ⚠️ The start is told apart by silhouette first (#39): a pill among rectangles, in the primary
@@ -117,9 +136,14 @@ function FlowCard({ data, selected }: NodeProps<CanvasNode>) {
         <span className="min-w-0">
           <span className="block truncate text-sm font-medium">{contract.label}</span>
           {/* The kind through the catalog, not the raw key: the start node is called Start on the
-              canvas as well, and `trigger` would name an event that no longer exists (#39). */}
-          <span className="block text-xs text-muted-foreground">
-            {i18n.t(`flows.node.${contract.kind}`)}
+              canvas as well, and `trigger` would name an event that no longer exists (#39).
+              ⚠️ A broken link says so INSTEAD of naming its kind, because "Document" beside a
+              reference that names nothing is the sentence #509 is about: the card looked like every
+              valid link on the canvas. */}
+          <span
+            className={`block text-xs ${broken ? "text-destructive" : "text-muted-foreground"}`}
+          >
+            {broken ? i18n.t("flows.nodeInvalid") : i18n.t(`flows.node.${contract.kind}`)}
           </span>
         </span>
         {riding === "follows" || riding === "pinned" ? (
@@ -348,6 +372,31 @@ function newNode(
   }
 }
 
+/**
+ * Which sentence a refused SAVE is told with.
+ *
+ * ⚠️ `400 flow_graph_invalid` and `409` are two different answers, and until #508 they shared one
+ * sentence — the conflict one. For a rejected graph that advice is not merely useless but
+ * destructive: reloading discards the unsaved canvas, and the next attempt is refused for exactly
+ * the same reason, so following it costs the work and changes nothing.
+ *
+ * The graph rule therefore shows the API's OWN sentence: only the server knows which step broke
+ * which rule, and it names that step by its label since #508. A conflict keeps the reload sentence,
+ * because there reloading IS the way out. Everything else gets neither — a timeout or a `502` is
+ * worth repeating, and nothing about it says the loaded version is stale.
+ *
+ * ⚠️ Not `resourceErrorKey`: that maps a code onto a catalog key, and this case has no key to map
+ * onto — its whole content is the server's sentence.
+ */
+function saveRefusalText(error: unknown, i18n: I18n): string {
+  const refusal = error instanceof IntelRequestError ? error : null;
+  if (refusal?.status === 400 && refusal.code === "flow_graph_invalid") {
+    return i18n.t("flows.saveInvalid", { detail: refusal.message });
+  }
+  if (refusal?.status === 409) return i18n.t("flows.saveConflict");
+  return i18n.t("flows.saveFailed");
+}
+
 // ⚠️ The provider wraps the editor rather than sitting inside it: `useReactFlow` — which is how the
 // drop turns a screen point into a graph point — has to be called from a component UNDER it, and
 // the hook lives in the same component that renders the canvas.
@@ -401,6 +450,21 @@ function FlowsEditor() {
     queryKey: ["flows"],
     queryFn: () => data.listFlows(),
   });
+  /**
+   * The refusal of the top level, read off the query the picker already holds.
+   *
+   * ⚠️ No second query, and that is the whole difference to #445 next door: `["flows"]` is asked
+   * with or without a selection, so the answer for the empty screen is already in the cache. What
+   * the screen did was throw it away — `listTreeChildren` fails whole once `flows/read` is missing,
+   * the sidebar has said so since #430, and the main area beside it went on inviting the reader to
+   * pick a flow they cannot see (#557).
+   *
+   * ⚠️ Off the ERROR rather than off a missing answer. A sentence about a permission, shown while
+   * the request is still travelling, claims a refusal nobody has spoken yet — the mistake from #350,
+   * and `packages/ui/CLAUDE.md` has the rule: a missing answer is a reason to say less, never to
+   * refuse more. Until a refusal arrives, what stands is the invitation, which claims nothing.
+   */
+  const rootRefusal = refusalOf(callable.error);
   // The tree in the sidebar and the header search both name the flow to open through `?select=`;
   // `?view=` says how it is shown — the editor, the relation graph (#19) or the runs (#35).
   const selection = useRouterState({
@@ -426,6 +490,10 @@ function FlowsEditor() {
     queryFn: () => data.getFlow(selectedFlowId ?? ""),
     enabled: Boolean(selectedFlowId),
   });
+  // ⚠️ A refusal is not a failure. "Reload the latest version and try again." is advice for a
+  // network that came back; against a `403` or a `404` it sends somebody to reload a screen that
+  // will answer the same thing forever, and it hides that the answer was final (#430).
+  const documentRefusal = refusalOf(document.error);
   const initial = useMemo(() => canvas(defaultGraph()), []);
   const [nodes, setNodes] = useState<CanvasNode[]>(initial.nodes);
   const [edges, setEdges] = useState<CanvasEdge[]>(initial.edges);
@@ -450,6 +518,19 @@ function FlowsEditor() {
     setDirty(false);
   }, [document.data, selectedFlowId]);
   const selectedNode = nodes.find((node) => node.id === selectedNodeId) ?? null;
+  // ⚠️ The same query `FlowNeeds` asks, under the same key: TanStack answers both from one cache
+  // entry, so the canvas and the panel cannot end up disagreeing about which link is dead. A second
+  // key would be a second answer to one question, and the one people would trust is the one they
+  // happen to be looking at (#509).
+  const needs = useQuery({
+    queryKey: ["flow-requirements", selectedFlowId],
+    queryFn: () => data.getFlowRequirements(selectedFlowId ?? ""),
+    enabled: Boolean(selectedFlowId),
+  });
+  const invalidLinks = useMemo(
+    () => new Set(needs.data?.invalidNodes ?? []),
+    [needs.data?.invalidNodes],
+  );
 
   const save = useMutation({
     mutationFn: () =>
@@ -496,9 +577,25 @@ function FlowsEditor() {
       ) : null}
       <UnsavedChangesGuard dirty={dirty} />
       <div className="flex min-h-0 flex-1">
-        {selectedFlowId && selection.view === "runs" ? (
+        {!selectedFlowId ? (
+          rootRefusal ? (
+            <RefusalNotice refusal={rootRefusal} />
+          ) : (
+            <div className="grid flex-1 place-items-center p-8 text-sm text-muted-foreground">
+              {i18n.t("flows.select")}
+            </div>
+          )
+        ) : /* ⚠️ The refusal comes BEFORE the view switch, and that placement is the whole of #568.
+               `?view=graph` and `?view=runs` used to be read first, so a flow the reader may not
+               open still rendered its two side views — each with a failure sentence and a "Try
+               again" button on an answer that will not change (#430). Whether the reader may see
+               this flow at all is answered by `getFlow`, once, for every view of it; asking it
+               after the switch means asking it three times and getting two of them wrong. */
+        documentRefusal ? (
+          <RefusalNotice refusal={documentRefusal} />
+        ) : selection.view === "runs" ? (
           <FlowRuns flowId={selectedFlowId} />
-        ) : selectedFlowId && selection.view === "graph" ? (
+        ) : selection.view === "graph" ? (
           <GraphPane
             query={relations}
             select={(node) =>
@@ -508,10 +605,6 @@ function FlowsEditor() {
               })
             }
           />
-        ) : !selectedFlowId ? (
-          <div className="grid flex-1 place-items-center p-8 text-sm text-muted-foreground">
-            {i18n.t("flows.select")}
-          </div>
         ) : document.isError ? (
           <div
             role="alert"
@@ -566,102 +659,104 @@ function FlowsEditor() {
                   media query that sets the class, so both turn together and mid-session. What the
                   surfaces are actually coloured with is in `styles.css`, through the library's own
                   theming variables — for the same reason `.react-sigma` is there. */}
-              <ReactFlow<CanvasNode, CanvasEdge>
-                colorMode={theme}
-                nodes={nodes}
-                edges={edges}
-                nodeTypes={nodeTypes}
-                fitView
-                onNodesChange={(changes: NodeChange<CanvasNode>[]) => {
-                  if (editsNodes(changes)) setDirty(true);
-                  setNodes((current) => applyNodeChanges(changes, current));
-                }}
-                onEdgesChange={(changes: EdgeChange<CanvasEdge>[]) => {
-                  if (editsEdges(changes)) setDirty(true);
-                  setEdges((current) => applyEdgeChanges(changes, current));
-                }}
-                // ⚠️ The two meanings cannot be mixed on one edge: a line from a context point into
-                // a flow input would be stored as context and drawn as an attachment, while the
-                // author meant "and then". Refused at the point where it is still visible.
-                isValidConnection={(connection) =>
-                  (connection.sourceHandle === ContextHandle) ===
-                  (connection.targetHandle === ContextHandle)
-                }
-                onConnect={(connection: Connection) => {
-                  setDirty(true);
-                  setEdges((current) =>
-                    addEdge(
+              <InvalidLinks.Provider value={invalidLinks}>
+                <ReactFlow<CanvasNode, CanvasEdge>
+                  colorMode={theme}
+                  nodes={nodes}
+                  edges={edges}
+                  nodeTypes={nodeTypes}
+                  fitView
+                  onNodesChange={(changes: NodeChange<CanvasNode>[]) => {
+                    if (editsNodes(changes)) setDirty(true);
+                    setNodes((current) => applyNodeChanges(changes, current));
+                  }}
+                  onEdgesChange={(changes: EdgeChange<CanvasEdge>[]) => {
+                    if (editsEdges(changes)) setDirty(true);
+                    setEdges((current) => applyEdgeChanges(changes, current));
+                  }}
+                  // ⚠️ The two meanings cannot be mixed on one edge: a line from a context point into
+                  // a flow input would be stored as context and drawn as an attachment, while the
+                  // author meant "and then". Refused at the point where it is still visible.
+                  isValidConnection={(connection) =>
+                    (connection.sourceHandle === ContextHandle) ===
+                    (connection.targetHandle === ContextHandle)
+                  }
+                  onConnect={(connection: Connection) => {
+                    setDirty(true);
+                    setEdges((current) =>
+                      addEdge(
+                        {
+                          ...connection,
+                          id: crypto.randomUUID(),
+                          ...contextEdgeStyle(connection.sourceHandle === ContextHandle),
+                        },
+                        current,
+                      ),
+                    );
+                  }}
+                  onNodeClick={(_event, node) => setSelectedNodeId(node.id)}
+                  onPaneClick={() => {
+                    setSelectedNodeId(null);
+                    setPaletteOpen(false);
+                  }}
+                  // ⚠️ `copy`, not `move` (#75). The tree's own drop targets say `move`, and the two
+                  // have to feel different while the pointer is still travelling: dropping here makes
+                  // a node that POINTS at the row, it does not take the row out of its folder.
+                  onDragOver={(event) => {
+                    if (!event.dataTransfer.types.includes(TreeEntryMediaType)) return;
+                    event.preventDefault();
+                    event.dataTransfer.dropEffect = "copy";
+                  }}
+                  onDrop={(event) => {
+                    const payload = event.dataTransfer.getData(TreeEntryMediaType);
+                    if (!payload) return;
+                    event.preventDefault();
+                    const dropped = droppedEntry(payload);
+                    if (!dropped) return;
+                    const kind = flowKindOfEntry[dropped.kind];
+                    if (!kind) return;
+                    // Where the pointer let go, in the graph's own coordinates — not the screen's, or
+                    // the node would land somewhere else at every zoom level.
+                    const position = flow.screenToFlowPosition({
+                      x: event.clientX,
+                      y: event.clientY,
+                    });
+                    setDirty(true);
+                    setNodes((current) => [
+                      ...current,
                       {
-                        ...connection,
-                        id: crypto.randomUUID(),
-                        ...contextEdgeStyle(connection.sourceHandle === ContextHandle),
-                      },
-                      current,
-                    ),
-                  );
-                }}
-                onNodeClick={(_event, node) => setSelectedNodeId(node.id)}
-                onPaneClick={() => {
-                  setSelectedNodeId(null);
-                  setPaletteOpen(false);
-                }}
-                // ⚠️ `copy`, not `move` (#75). The tree's own drop targets say `move`, and the two
-                // have to feel different while the pointer is still travelling: dropping here makes
-                // a node that POINTS at the row, it does not take the row out of its folder.
-                onDragOver={(event) => {
-                  if (!event.dataTransfer.types.includes(TreeEntryMediaType)) return;
-                  event.preventDefault();
-                  event.dataTransfer.dropEffect = "copy";
-                }}
-                onDrop={(event) => {
-                  const payload = event.dataTransfer.getData(TreeEntryMediaType);
-                  if (!payload) return;
-                  event.preventDefault();
-                  const dropped = droppedEntry(payload);
-                  if (!dropped) return;
-                  const kind = flowKindOfEntry[dropped.kind];
-                  if (!kind) return;
-                  // Where the pointer let go, in the graph's own coordinates — not the screen's, or
-                  // the node would land somewhere else at every zoom level.
-                  const position = flow.screenToFlowPosition({
-                    x: event.clientX,
-                    y: event.clientY,
-                  });
-                  setDirty(true);
-                  setNodes((current) => [
-                    ...current,
-                    {
-                      id: `${kind}-${crypto.randomUUID()}`,
-                      type: "intel" as const,
-                      position,
-                      data: {
-                        node: {
-                          id: `${kind}-${crypto.randomUUID()}`,
-                          kind,
-                          label: dropped.title,
-                          position,
-                          configuration:
-                            kind === "subflow"
-                              ? { flowId: dropped.id, version: { mode: "latest" as const } }
-                              : { resourceId: dropped.id },
-                        } as FlowNode,
+                        id: `${kind}-${crypto.randomUUID()}`,
+                        type: "intel" as const,
+                        position,
+                        data: {
+                          node: {
+                            id: `${kind}-${crypto.randomUUID()}`,
+                            kind,
+                            label: dropped.title,
+                            position,
+                            configuration:
+                              kind === "subflow"
+                                ? { flowId: dropped.id, version: { mode: "latest" as const } }
+                                : { resourceId: dropped.id },
+                          } as FlowNode,
+                        },
                       },
-                    },
-                  ]);
-                }}
-              >
-                <Background />
-                {/* The overview map has no room for a label, so the start is marked there the only
+                    ]);
+                  }}
+                >
+                  <Background />
+                  {/* The overview map has no room for a label, so the start is marked there the only
                     way that is left: its own colour, from the tokens rather than a fixed value. */}
-                <MiniMap
-                  pannable
-                  zoomable
-                  nodeClassName={(node) =>
-                    (node as CanvasNode).data.node.kind === "trigger" ? "intel-minimap-start" : ""
-                  }
-                />
-                <Controls />
-              </ReactFlow>
+                  <MiniMap
+                    pannable
+                    zoomable
+                    nodeClassName={(node) =>
+                      (node as CanvasNode).data.node.kind === "trigger" ? "intel-minimap-start" : ""
+                    }
+                  />
+                  <Controls />
+                </ReactFlow>
+              </InvalidLinks.Provider>
             </section>
             <aside className="flex w-80 shrink-0 flex-col border-l bg-card">
               <TitleRowScrollArea className="min-h-0 flex-1 overflow-y-auto">
@@ -696,7 +791,7 @@ function FlowsEditor() {
           role="alert"
           className="fixed bottom-5 left-[18rem] z-20 rounded-lg border border-destructive/30 bg-card px-4 py-3 text-sm text-destructive shadow-xl"
         >
-          {i18n.t("flows.operationFailed")}
+          {saveRefusalText(save.error, i18n)}
         </p>
       )}
       {publishing && selectedFlowId && document.data?.flow.currentVersionId ? (
@@ -712,7 +807,9 @@ function FlowsEditor() {
             // graph that just changed.
             await Promise.all([
               queryClient.invalidateQueries({ queryKey: ["flow", selectedFlowId] }),
-              queryClient.invalidateQueries({ queryKey: ["flow-publish-preview", selectedFlowId] }),
+              queryClient.invalidateQueries({
+                queryKey: ["flow-publish-preview", selectedFlowId],
+              }),
               queryClient.invalidateQueries({ queryKey: ["relation-graph"] }),
             ]);
           }}
@@ -1249,11 +1346,13 @@ function FlowNeeds({ flowId }: { flowId: string }) {
     queryKey: ["flow-requirements", flowId],
     queryFn: () => data.getFlowRequirements(flowId),
   });
-  // ⚠️ A flow that touches nothing and a flow whose every reference is hidden are two different
-  // answers, so the counted ones keep the panel from claiming the first when it means the second.
+  // ⚠️ A flow that touches nothing and a flow whose every reference is hidden or dead are three
+  // different answers, so neither the counted nor the broken ones may fall out of this condition —
+  // otherwise the panel claims the first when it means one of the others.
   const empty =
     needs.data !== undefined &&
     needs.data.nodes.length === 0 &&
+    needs.data.invalidNodes.length === 0 &&
     needs.data.hiddenNodes === 0 &&
     needs.data.servers.length === 0;
   return (
@@ -1270,7 +1369,9 @@ function FlowNeeds({ flowId }: { flowId: string }) {
       {empty && <p className="mt-2 text-sm text-muted-foreground">{i18n.t("flows.needsEmpty")}</p>}
       {needs.data && !empty && (
         <>
-          {(needs.data.nodes.length > 0 || needs.data.hiddenNodes > 0) && (
+          {(needs.data.nodes.length > 0 ||
+            needs.data.invalidNodes.length > 0 ||
+            needs.data.hiddenNodes > 0) && (
             <>
               <h3 className="mt-4 text-xs font-medium uppercase tracking-wide text-muted-foreground">
                 {i18n.t("flows.needsNodes")}
@@ -1282,6 +1383,16 @@ function FlowNeeds({ flowId }: { flowId: string }) {
                     <span className="min-w-0 truncate">{reference.title}</span>
                   </li>
                 ))}
+                {/* ⚠️ A dead reference and an unreachable one are two entries, not one (#509).
+                    They used to share the counted line, which said "you cannot see it" about a
+                    document that is gone — a sentence about a permission, in front of something no
+                    permission can fix. This one says what to do instead, because there is exactly
+                    one thing to do: replace the step or take it out. */}
+                {needs.data.invalidNodes.length > 0 && (
+                  <li className="text-destructive">
+                    {i18n.t("flows.needsInvalid", { count: needs.data.invalidNodes.length })}
+                  </li>
+                )}
                 {/* ⚠️ Counted, never named. A title is exactly what someone without access to the
                     document may not learn from a list about it. */}
                 {needs.data.hiddenNodes > 0 && (

package/src/graph-pane/graph-pane.tsx

@@ -1,6 +1,8 @@
 import type { RelationGraph } from "@anchrd/intel-contract/flow";
 import type { UseQueryResult } from "@tanstack/react-query";
 import { lazy, Suspense } from "react";
+import { RefusalNotice } from "@/data/request-refusal/refusal-notice.tsx";
+import { refusalOf } from "@/data/request-refusal/request-refusal.ts";
 import { useI18n } from "@/i18n/i18n-context.tsx";
 
 const RelationGraphView = lazy(async () => ({
@@ -20,6 +22,13 @@ export function GraphPane({
   const i18n = useI18n();
   const loading = <p className="p-6 text-sm text-muted-foreground">{i18n.t("common.loading")}</p>;
   if (query.isPending) return loading;
+  // ⚠️ Read off this pane's OWN error, not handed down from the screen around it (#568). The screen
+  // above answers whether the flow or folder may be opened at all; this answers whether its
+  // relations may be read, and the graph endpoint can refuse on its own — an authorized folder
+  // whose graph is not shared. Two questions, so two places, and the one that is refused says so
+  // where it happened.
+  const refusal = refusalOf(query.error);
+  if (refusal) return <RefusalNotice refusal={refusal} />;
   if (query.isError || !query.data) {
     return (
       <div role="alert" className="grid flex-1 place-items-center p-8 text-center text-sm">

package/src/i18n/de.json

@@ -259,6 +259,7 @@
   "flows.node.condition": "Bedingung",
   "flows.node.subflow": "Flow",
   "flows.node.output": "Ende",
+  "flows.nodeInvalid": "Gibt es nicht mehr — ersetze oder entferne diesen Schritt",
   "flows.instruction": "Anweisung für die KI oder die Person",
   "flows.instructionHint": "Bedingungen, Prüfungen und Verzweigungen lassen sich hier in Worten beschreiben. Für jede kleine Entscheidung braucht es keinen eigenen Schritt.",
   "flows.linkEmpty": "Noch nichts gewählt",
@@ -293,9 +294,13 @@
   "flows.tool": "MCP-Server",
   "flows.selectTool": "Server auswählen",
   "flows.operationFailed": "Der Flow-Vorgang ist fehlgeschlagen. Lade die neueste Fassung und versuche es erneut.",
+  "flows.saveInvalid": "Nicht gespeichert: {detail}",
+  "flows.saveConflict": "Nicht gespeichert: Jemand anderes hat diesen Flow zuerst geändert. Lade die neueste Fassung und versuche es erneut.",
+  "flows.saveFailed": "Der Flow wurde nicht gespeichert. Versuche es erneut.",
   "flows.needs": "Was dieser Flow braucht",
   "flows.needsNodes": "Dokumente",
   "flows.needsTools": "Werkzeuge",
+  "flows.needsInvalid": "{count} weitere, die es nicht mehr gibt — ersetze oder entferne diese Schritte",
   "flows.needsHidden": "{count} weitere, die du nicht sehen kannst",
   "flows.needsEmpty": "Dieser Flow liest keine Dokumente und ruft keine Werkzeuge auf.",
   "flows.needsFailed": "Was dieser Flow braucht, konnte nicht geladen werden.",

package/src/i18n/en.json

@@ -259,6 +259,7 @@
   "flows.node.condition": "Condition",
   "flows.node.subflow": "Flow",
   "flows.node.output": "End",
+  "flows.nodeInvalid": "Gone — replace or remove this step",
   "flows.instruction": "Instruction for the AI or person",
   "flows.instructionHint": "Conditions, checks and branches can be described here in words. You do not need a separate node for every small decision.",
   "flows.linkEmpty": "Nothing chosen yet",
@@ -293,9 +294,13 @@
   "flows.tool": "MCP server",
   "flows.selectTool": "Select a server",
   "flows.operationFailed": "The flow operation failed. Reload the latest version and try again.",
+  "flows.saveInvalid": "Not saved: {detail}",
+  "flows.saveConflict": "Not saved: somebody else changed this flow first. Reload the latest version and try again.",
+  "flows.saveFailed": "The flow was not saved. Try again.",
   "flows.needs": "What this flow needs",
   "flows.needsNodes": "Documents",
   "flows.needsTools": "Tools",
+  "flows.needsInvalid": "{count} more that no longer exist — replace or remove those steps",
   "flows.needsHidden": "{count} more you cannot see",
   "flows.needsEmpty": "This flow reads no documents and calls no tools.",
   "flows.needsFailed": "What this flow needs could not be loaded.",

package/src/i18n/es.json

@@ -259,6 +259,7 @@
   "flows.node.condition": "Condición",
   "flows.node.subflow": "Flujo",
   "flows.node.output": "Fin",
+  "flows.nodeInvalid": "Ya no existe — sustituye o quita este paso",
   "flows.instruction": "Instrucción para la IA o la persona",
   "flows.instructionHint": "Las condiciones, comprobaciones y bifurcaciones se pueden describir aquí con palabras. No hace falta un paso propio para cada decisión pequeña.",
   "flows.linkEmpty": "Todavía no se ha elegido nada",
@@ -293,9 +294,13 @@
   "flows.tool": "Servidor MCP",
   "flows.selectTool": "Elegir un servidor",
   "flows.operationFailed": "La operación del flujo ha fallado. Carga la versión más reciente e inténtalo de nuevo.",
+  "flows.saveInvalid": "No se ha guardado: {detail}",
+  "flows.saveConflict": "No se ha guardado: otra persona ha cambiado este flujo antes. Carga la versión más reciente e inténtalo de nuevo.",
+  "flows.saveFailed": "El flujo no se ha guardado. Inténtalo de nuevo.",
   "flows.needs": "Qué necesita este flujo",
   "flows.needsNodes": "Documentos",
   "flows.needsTools": "Herramientas",
+  "flows.needsInvalid": "{count} más que ya no existen — sustituye o quita esos pasos",
   "flows.needsHidden": "{count} más que no puedes ver",
   "flows.needsEmpty": "Este flujo no lee ningún documento ni llama a ninguna herramienta.",
   "flows.needsFailed": "Lo que necesita este flujo no se ha podido cargar.",

package/src/node-editor/node-editor.tsx

@@ -12,6 +12,7 @@ import { Link2 } from "lucide-react";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { ActionSlot } from "@/app/action-slot/action-slot.tsx";
 import { BlockNoteView, defaultSlashMenuItems } from "@/blocknote-view/blocknote-view.tsx";
+import { IntelRequestError } from "@/data/intel-data-provider/intel-data-provider.ts";
 import type { IntelDataProvider } from "@/data/intel-data-provider/intel-data-provider.types.ts";
 import {
   DocumentLinkProvider,
@@ -57,6 +58,28 @@ function editorSnapshot(blocks: unknown): string {
   return JSON.stringify(blocks);
 }
 
+/**
+ * Which of the two sentences a failed save is told with.
+ *
+ * ⚠️ The refusal's `code`, never the server's prose: `POST /nodes/{id}/versions` words the conflict
+ * as `A newer version already exists`, and an English sentence from the API is not a translation
+ * source. The code is the contract (`ProblemDetails.code`), and `IntelRequestError` is what carries
+ * it this far.
+ *
+ * ⚠️ The two are not a vaguer and a sharper wording of one event. `node.saveError` says "reload and
+ * try again", which is right for a network failure and dangerous for a conflict: reloading without
+ * knowing that a foreign version now stands loses either the reader's own work or, on the second
+ * attempt, the other one. That is why this distinction is worth a branch at all (#451).
+ *
+ * ⚠️ Local rather than through `resourceErrorKey`: that one answers for the resource menu and the
+ * column dialog, and its sentences are the `resource.*` ones. The editor has its own two.
+ */
+function saveErrorKey(error: unknown): string {
+  return error instanceof IntelRequestError && error.code === "version_conflict"
+    ? "node.saveConflict"
+    : "node.saveError";
+}
+
 export function NodeEditor({
   data,
   document,
@@ -173,7 +196,7 @@ export function NodeEditor({
       <UnsavedChangesGuard dirty={dirty} />
       {save.isError && (
         <p role="alert" className="mx-6 mt-4 text-sm text-destructive">
-          {i18n.t("node.saveError")}
+          {i18n.t(saveErrorKey(save.error))}
         </p>
       )}
       <TitleRowScrollArea className="min-h-0 flex-1 overflow-y-auto py-6">

package/src/nodes/nodes.tsx

@@ -3,7 +3,9 @@ import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useNavigate, useRouterState } from "@tanstack/react-router";
 import { Download, Paperclip } from "lucide-react";
 import { lazy, Suspense } from "react";
+import { treeLevelKey } from "@/app/tree-move/tree-move.tsx";
 import { ViewToggle } from "@/app/view-toggle/view-toggle.tsx";
+import { RefusalNotice } from "@/data/request-refusal/refusal-notice.tsx";
 import { refusalOf } from "@/data/request-refusal/request-refusal.ts";
 import { FolderContents } from "@/folder-contents/folder-contents.tsx";
 import { GraphPane } from "@/graph-pane/graph-pane.tsx";
@@ -41,6 +43,27 @@ export function Nodes() {
   // answered "no" (`packages/ui/CLAUDE.md`). While the request is in flight there is no refusal to
   // report, and the loading line below stays.
   const refusal = refusalOf(document.error);
+  /**
+   * The top level of the tree — the same query the sidebar already holds, by the same key and the
+   * same function, so this is a second reader of one cache entry rather than a second request.
+   *
+   * ⚠️ The screen needs a source of its own because the one above cannot answer here: the refusal
+   * branch hangs on `["node", selectedId]`, and without a selection that query is not enabled at
+   * all. The empty state was therefore reached BEFORE anything had been asked — and it invited the
+   * reader to select something, which is exactly what somebody without `intel.nodes.read` cannot
+   * do. The sidebar beside it has said so since #430; two surfaces, two answers (#445).
+   */
+  const rootLevel = useQuery({
+    queryKey: treeLevelKey(null),
+    queryFn: () => data.listTreeChildren(null),
+    enabled: selectedId === null,
+  });
+  // ⚠️ Off the ERROR, and here that is half the ticket rather than a detail. A sentence about a
+  // missing permission, shown while the answer is still travelling, claims a refusal nobody has
+  // spoken yet — the mistake from #350, and `packages/ui/CLAUDE.md` has the rule: a missing answer
+  // is a reason to say less, never to refuse more. So the negative sentence hangs off the refusal;
+  // until one arrives, what stands is the invitation, which claims nothing about permission.
+  const rootRefusal = refusalOf(rootLevel.error);
   // A folder shows its contents as a graph, and so does the root of the tree (#19). A document has
   // nothing to draw — which is why the switch is not offered on one rather than offered and empty.
   const graphable = selectedId === null || selected?.kind === "folder";
@@ -80,26 +103,17 @@ export function Nodes() {
             }
           />
         ) : !selectedId ? (
-          <div className="grid flex-1 place-items-center p-8 text-center text-sm text-muted-foreground">
-            {i18n.t("node.select")}
-          </div>
+          rootRefusal ? (
+            <RefusalNotice refusal={rootRefusal} />
+          ) : (
+            <div className="grid flex-1 place-items-center p-8 text-center text-sm text-muted-foreground">
+              {i18n.t("node.select")}
+            </div>
+          )
         ) : document.isPending ? (
           <p className="p-6 text-sm text-muted-foreground">{i18n.t("common.loading")}</p>
         ) : refusal ? (
-          /* ⚠️ A refusal is not a failure, and the difference is the whole of #430. Somebody whose
-             share was revoked was left in front of "Loading…" — the worst answer of all, because it
-             says the program is still working. They get a sentence and no retry button: the answer
-             was final, and a button that changes nothing is an invitation to keep waiting.
-
-             ⚠️ One sentence for `404`, whichever of its two reasons applies. Intel answers the same
-             status for "no such node" and "not for you" on purpose — `requireVisible` in
-             `packages/api/src/nodes/nodes.ts` — and a screen that told them apart would undo that
-             from the other side. */
-          <div role="status" className="grid flex-1 place-items-center p-8 text-center text-sm">
-            <p className="max-w-sm text-muted-foreground">
-              {i18n.t(refusal === "no-permission" ? "common.noPermission" : "common.noAccess")}
-            </p>
-          </div>
+          <RefusalNotice refusal={refusal} />
         ) : document.isError || !selected ? (
           <div role="alert" className="grid flex-1 place-items-center p-8 text-center text-sm">
             <div className="space-y-3">

package/src/resource-menu/resource-menu.tsx

@@ -411,19 +411,30 @@ export function ResourceMenu({
                   (`flows.problem.<code>` is one string) and repeating it under itself says nothing
                   the reader did not just read. What differs is the detail, and every detail is
                   still here — which is the promise the comment above makes: somebody with two
-                  missing tools should not have to ask twice. */}
+                  missing tools should not have to ask twice.
+
+                  ⚠️ What identifies a detail is its POSITION in `problems`, not its text (#461).
+                  Two details of one code are routinely the same sentence: `collectRunProblems`
+                  files one problem per sub-flow NODE and words it with that node's label
+                  (`packages/api/src/flows/flows.ts`), and calling the same flow twice is the normal
+                  case. Under `key={detail}` those two collided on one key, and React does not
+                  answer that with a console warning alone — it drops one of the siblings on the
+                  next render, so the reader sees ONE entry where there are two causes. */}
               {[
                 ...validation.problems
-                  .reduce((byCode, problem) => {
-                    byCode.set(problem.code, [...(byCode.get(problem.code) ?? []), problem.detail]);
+                  .reduce((byCode, problem, at) => {
+                    byCode.set(problem.code, [
+                      ...(byCode.get(problem.code) ?? []),
+                      { at, detail: problem.detail },
+                    ]);
                     return byCode;
-                  }, new Map<string, string[]>())
+                  }, new Map<string, { at: number; detail: string }[]>())
                   .entries(),
               ].map(([code, details]) => (
                 <li key={code} className="rounded-md border p-3 text-sm">
                   <span className="block font-medium">{i18n.t(`flows.problem.${code}`)}</span>
-                  {details.map((detail) => (
-                    <span key={detail} className="mt-1 block text-xs text-muted-foreground">
+                  {details.map(({ at, detail }) => (
+                    <span key={at} className="mt-1 block text-xs text-muted-foreground">
                       {detail}
                     </span>
                   ))}