@anchrd/intel-ui 0.20.0 → 0.22.0

package/README.md

@@ -43,6 +43,39 @@ Point `intel.json` at your files:
 Missing assets, non-SVG branding and incomplete language catalogs fail the build rather than
 silently producing a half-branded application.
 
+## What an empty screen means
+
+Most "the UI is broken" reports are one of four situations, and the application distinguishes them
+rather than showing one blank page for all of them. The full explanation of the two permission
+layers is in the
+[`@anchrd/intel-api` README](https://www.npmjs.com/package/@anchrd/intel-api); what follows is what
+each one looks like here.
+
+| On screen | What it is |
+|---|---|
+| "You do not have permission to see this." | The Gate capability is missing — `nodes.read` and friends |
+| An empty tree, no error | Nothing has been shared with this person yet |
+| "This is not available to you. It may not exist, or it may no longer be shared with you." | A node that was reachable and is not any more, or never existed — Intel deliberately does not say which |
+| Skeletons that never resolve | Should no longer happen: a refusal ends the loading state on the first answer, and no button offers a retry that cannot change anything |
+
+A node somebody shares appears in the recipient's sidebar on its own, at the top level, without
+naming the folders above it. Nobody needs to be sent a link.
+
+The sharing dialog grants to an email address or to the whole organization. It never shows a raw
+user id: where Intel cannot name an account it says so. ⚠️ Choosing **execute for the whole
+organization** on a folder makes that folder a library that flows from anywhere may call into, and
+withdrawing it is refused while a caller remains — the dialog says so before the click.
+
+The Tools screen tells four situations apart — refused, expired, broken, and started-but-never-
+answered — and offers a second attempt everywhere a second attempt could change the answer.
+
+The editor answers "Nothing to save" rather than "Saved" when the write produced no new version.
+The two are different outcomes and only one of them means the text is safe to walk away from.
+
+⚠️ The editor opens **empty** on content it cannot parse. Documents written over HTTP or MCP have to
+carry the BlockNote media type to be editable in the browser; see the
+[`@anchrd/intel-contract` README](https://www.npmjs.com/package/@anchrd/intel-contract).
+
 ## What is inside
 
 Vite, React, TanStack Router and Query, with shadcn components. The node editor uses BlockNote

package/package.json

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

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

@@ -35,6 +35,7 @@ import {
 } from "@/components/ui/sidebar";
 import { flowEntry } from "@/data/intel-data-provider/intel-data-provider.ts";
 import type { TreeEntry } from "@/data/intel-data-provider/intel-data-provider.types.ts";
+import { refusalOf } from "@/data/request-refusal/request-refusal.ts";
 import { useI18n } from "@/i18n/i18n-context.tsx";
 import { type ImportKind, useBundleImport } from "@/import-bundle/import-bundle.tsx";
 import { kindIcons } from "@/kind-icon.ts";
@@ -337,6 +338,19 @@ export function AppTree() {
         </SidebarMenu>
       );
     }
+    // ⚠️ A refusal, not a failure (#430). While this branch did not exist, a reader whose share had
+    // been revoked — or who holds no `intel.nodes.read` at all — watched the three skeleton bars
+    // above for as long as the retries lasted, and the retries are paused whenever the tab is not
+    // in front. Neither of those two cases is worth trying again, so what stands here is a sentence
+    // and no button.
+    const refusal = refusalOf(level.error);
+    if (refusal) {
+      return (
+        <p role="status" className="px-2 py-1.5 text-sm text-muted-foreground">
+          {i18n.t(refusal === "no-permission" ? "common.noPermission" : "common.noAccess")}
+        </p>
+      );
+    }
     if (level.isError) {
       return (
         <div role="alert" className="space-y-2 px-2 py-1.5 text-sm">
@@ -376,15 +390,16 @@ export function AppTree() {
     }
     return (
       <SidebarMenu aria-label={label}>
-        {entries.map((entry) => renderRow(entry, ancestors, parent.type === "flow"))}
+        {entries.map((entry) => renderRow(entry, parent, ancestors))}
       </SidebarMenu>
     );
   }
 
-  // ⚠️ `derived` is the level under a flow: its rows are that flow's calls, read out of its graph
+  // ⚠️ A level under a FLOW is derived: its rows are that flow's calls, read out of its graph
   // (ADR-0004 §3, `levelKey`). Nothing there has a `parent_id` to rewrite, so those rows are neither
   // dragged nor dropped on — a move made there would silently be a move of the shared flow itself.
-  function renderRow(entry: TreeEntry, ancestors: ReadonlySet<string>, derived: boolean) {
+  function renderRow(entry: TreeEntry, parent: Level, ancestors: ReadonlySet<string>) {
+    const derived = parent.type === "flow";
     const isFolder = entry.kind === "folder";
     // ⚠️ A flow expands too, and what appears under it is what it calls — read from its graph, not
     // from `parent_id`. A flow reused by three callers therefore shows up under all three, which is
@@ -400,7 +415,23 @@ export function AppTree() {
     const area = entry.type === "flow" ? "/flows" : "/nodes";
     const isActive = location.select === entry.id && location.pathname === area;
     // A row's plus files into that row's place: inside a folder, beside anything else.
-    const target = isFolder ? entry.id : parentOf(entry);
+    //
+    // ⚠️ "Beside it" is the level this row is shown IN, not the parent its own record names. Since
+    // #429 the root level also carries rows whose `parentId` points at a folder this reader may not
+    // see — a shared document is filed inside the sharer's folder, and only the share reaches down
+    // to it. Filing beside such a row through that id would try to write into a folder the reader
+    // cannot even open, and the refusal would arrive as a bare "could not be created".
+    //
+    // ⚠️ A derived level is the exception, because it has no folder to be filed in: what a flow
+    // calls is read from its graph, so the record's own parent is the only answer available there.
+    //
+    // ⚠️ It is the only one, not a safe one. A called flow may be a LIBRARY flow — `execute` without
+    // `read`, which ADR-0004 §2/§3 allows on purpose — and its folder is then one this reader may
+    // not open at all. The plus there can still be refused, exactly as the plus on any read-only
+    // folder row elsewhere in the tree has always been able to be. That is the older question of
+    // what a plus should do where writing is not allowed, and it is not this ticket's: what #429
+    // changed is a plus pointing at a folder that is not even the level being shown.
+    const target = isFolder ? entry.id : derived ? parentOf(entry) : parent.id;
     // Only a folder takes a drop, and only on a level that owns its rows. Everything else keeps the
     // default cursor while a drag is in progress, which is the answer "not here" without a word.
     const drop =

package/src/data/query-client.ts

@@ -0,0 +1,18 @@
+import { QueryClient } from "@tanstack/react-query";
+import { retryRequest } from "@/data/request-refusal/request-refusal.ts";
+
+/**
+ * The one query client the application runs on.
+ *
+ * ⚠️ It exists as a function rather than as the literal `new QueryClient()` that stood in `main.tsx`
+ * so the policy in it can be exercised by a test (#430). A default nothing renders under is a
+ * default nothing checks, and this one decides how long a screen stays on "Loading…".
+ *
+ * ⚠️ Flat, and without a `.unit.ts` of its own on purpose: the only thing to assert here is that the
+ * returned client carries `retryRequest`, and what that predicate DOES is already covered next door
+ * in `request-refusal.unit.ts` — twice over, because two screen tests render against this very
+ * client. A test that restated the wiring would be the "pure wiring" the repository rules exclude.
+ */
+export function createIntelQueryClient(): QueryClient {
+  return new QueryClient({ defaultOptions: { queries: { retry: retryRequest } } });
+}

package/src/data/request-refusal/request-refusal.ts

@@ -0,0 +1,51 @@
+import { IntelRequestError } from "@/data/intel-data-provider/intel-data-provider.ts";
+
+/**
+ * What a failed request already settles, as opposed to what it might answer differently next time.
+ *
+ * - `not-available` is Intel's `404`. It is deliberately the same answer for "there is no such node"
+ *   and "you may not reach this node" — `requireVisible` in `packages/api/src/nodes/nodes.ts`, held
+ *   in place by "answers 404 for a foreign version and for an unreadable node" in `nodes.int.ts`.
+ *   A screen must therefore not guess between them either: one sentence covers both, and that is why
+ *   `no-permission` is a separate value rather than prose that could be shown for a `404` by mistake.
+ * - `no-permission` is a `403`. The server said the word itself, so repeating it reveals nothing.
+ * - `null` is everything else: a timeout, a `502`, a network that came back. Those are worth trying
+ *   again, and the screen keeps its retry button for them.
+ */
+export type Refusal = "not-available" | "no-permission";
+
+/** The HTTP status the data provider recorded, or `null` where the failure carried none. */
+export function statusOf(error: unknown): number | null {
+  return error instanceof IntelRequestError ? error.status : null;
+}
+
+export function refusalOf(error: unknown): Refusal | null {
+  switch (statusOf(error)) {
+    case 403:
+      return "no-permission";
+    case 404:
+      return "not-available";
+    default:
+      return null;
+  }
+}
+
+/**
+ * The retry policy every query in Intel runs under.
+ *
+ * ⚠️ A refusal is deterministic, and repeating it is what left the screen on "Loading…" after a
+ * share was revoked (#430). React Query's default is three retries with a growing delay, so a `404`
+ * kept the reader in front of a moving loading state for seconds — and a retry is **paused while
+ * the tab is unfocused** (`packages/ui/CLAUDE.md`, #212), so "seconds" has no upper bound whenever
+ * the person looked somewhere else. The answer was there the whole time.
+ *
+ * ⚠️ `408` and `429` are the two `4xx` that DO change on their own — a timeout and a rate limit both
+ * say "not now" rather than "not you" — so they keep the retries. Everything else in the range is
+ * about this request as it was made, and making it again cannot alter that.
+ */
+export function retryRequest(failureCount: number, error: unknown): boolean {
+  const status = statusOf(error);
+  const deterministic =
+    status !== null && status >= 400 && status < 500 && status !== 408 && status !== 429;
+  return !deterministic && failureCount < 3;
+}

package/src/flows/flows.tsx

@@ -759,7 +759,14 @@ function FlowTitle({
           <TooltipContent>{publishLabel}</TooltipContent>
         </Tooltip>
       </TooltipProvider>
-      <SaveButton dirty={dirty && canMutate} saving={saving} onSave={onSave} />
+      {/* A draft that was never saved has no version, and the button says so rather than claiming
+          one (#432) — the same distinction the publish button next to it already draws. */}
+      <SaveButton
+        dirty={dirty && canMutate}
+        saving={saving}
+        stored={flow.currentVersionId !== null}
+        onSave={onSave}
+      />
     </TitleRow>
   );
 }

package/src/i18n/de.json

@@ -112,6 +112,14 @@
   "node.share": "Freigeben",
   "node.shareAction": "Zugriff geben",
   "node.email": "E-Mail-Adresse",
+  "node.emailHint": "Intel kann nicht prüfen, ob hinter dieser Adresse ein Konto steht. Die Freigabe greift, sobald sich jemand damit anmeldet — auch nach einer späteren Registrierung.",
+  "node.shareWith": "Wer Zugriff bekommt",
+  "node.shareWithEmail": "Eine E-Mail-Adresse",
+  "node.shareWithOrganization": "Alle in der Organisation",
+  "node.shareOrganizationHint": "Jedes angemeldete Mitglied der Organisation bekommt diesen Zugriff, auch wer später dazukommt.",
+  "node.shareLibraryWarning": "Ausführen für die ganze Organisation macht diesen Ordner zu einer Bibliothek: Flows von überall im Baum dürfen dann hineinrufen. Das Zurücknehmen wird abgelehnt, solange einer davon es noch tut.",
+  "node.revokeInUse": "Dieser Zugriff lässt sich noch nicht zurücknehmen, weil Flows außerhalb dieses Ordners noch hineinrufen.",
+  "node.someUser": "Ein Benutzerkonto",
   "node.verbs": "Was diese Freigabe erlaubt",
   "node.verb.read": "Lesen",
   "node.verb.write": "Schreiben",
@@ -158,7 +166,7 @@
   "node.saveError": "Dieses Dokument konnte nicht gespeichert werden. Lade neu und versuche es erneut.",
   "tools.signingIn": "Du wirst am Firmenportal angemeldet …",
   "tools.noAccess": "Kein Zugriff auf das Firmenportal",
-  "tools.noAccessHelp": "Dein Intel-Konto erreicht das MCP-Portal der Firma nicht, deshalb gibt es hier nichts zu zeigen. Wer welchen Server nutzen darf, entscheidet eine Administration im Portal; bitte darum, aufgenommen zu werden.",
+  "tools.noAccessHelp": "Dein Konto darf das MCP-Portal der Firma nicht erreichen, deshalb gibt es hier nichts zu zeigen. Diese Erlaubnis wird nicht in Intel vergeben — bitte die Stelle darum, die in deiner Organisation die Konten verwaltet.",
   "tools.empty": "Keine Werkzeuge für dich verfügbar",
   "tools.emptyHelp": "Das Portal hat geantwortet, und es bietet deinem Konto keine Werkzeuge an. Welche Server es gibt und wer sie erreicht, entscheidet eine Administration im Portal.",
   "tools.unreachable": "Portal nicht erreichbar",
@@ -167,7 +175,9 @@
   "tools.connectExpiredHelp": "Die Verbindung zum MCP-Portal der Firma muss innerhalb weniger Minuten abgeschlossen sein, und diese lief ab, während die Freigabe-Seite offen stand. Es ist nichts schiefgegangen und nichts wurde verweigert — starte erneut und bestätige die Server, wenn die Seite erscheint.",
   "tools.connectRetry": "Erneut starten",
   "tools.connectFailed": "Anmeldung am Portal fehlgeschlagen",
-  "tools.connectFailedHelp": "Die Anmeldung am MCP-Portal der Firma brach ab, bevor sie beantwortet werden konnte. Das ist ein technischer Fehler, keine Entscheidung über deinen Zugriff — lade neu für einen weiteren Versuch, und sag der Administration Bescheid, wenn es bleibt.",
+  "tools.connectFailedHelp": "Die Anmeldung am MCP-Portal der Firma brach ab, bevor sie beantwortet werden konnte. Das ist ein technischer Fehler, keine Entscheidung über deinen Zugriff — starte sie erneut, und sag der Administration Bescheid, wenn es bleibt.",
+  "tools.connectUnknown": "Intel weiß nicht, ob du das Portal erreichst",
+  "tools.connectUnknownHelp": "In dieser Browsersitzung wurde eine Anmeldung am MCP-Portal der Firma gestartet, die nie mit einer Antwort zurückkam. Deshalb steht hier weder, dass du zugelassen wurdest, noch, dass du abgelehnt wurdest. Starte sie erneut; wenn es dabei bleibt, sag der Administration Bescheid.",
   "tools.origin": "Herkunft",
   "tools.originUnlisted": "Nicht von einem gelisteten Server",
   "tools.originUnlistedHelp": "Die Serverliste des Portals nennt für diese keinen Server. Seine eigenen Verwaltungswerkzeuge liegen hier — das Portal listet sich nicht selbst — und ebenso alles von einem Server, den die Liste nicht erwähnt hat.",
@@ -302,6 +312,7 @@
   "common.save": "Speichern",
   "common.saving": "Wird gespeichert …",
   "common.saved": "Gespeichert",
+  "common.saveNothing": "Nichts zu speichern",
   "common.saveDirty": "Ungespeicherte Änderungen speichern",
   "common.unsavedTitle": "Ungespeicherte Änderungen",
   "common.unsavedBody": "Hier gibt es Änderungen, die nicht gespeichert wurden. Wer jetzt geht, verwirft sie.",
@@ -310,5 +321,7 @@
   "common.loading": "Wird geladen …",
   "common.retry": "Erneut versuchen",
   "common.close": "Schließen",
-  "common.unavailable": "Intel ist derzeit nicht verfügbar."
+  "common.unavailable": "Intel ist derzeit nicht verfügbar.",
+  "common.noAccess": "Das ist für dich nicht verfügbar. Es existiert nicht, oder es ist nicht mehr für dich freigegeben.",
+  "common.noPermission": "Dir fehlt die Berechtigung, das zu sehen."
 }

package/src/i18n/en.json

@@ -112,6 +112,14 @@
   "node.share": "Share",
   "node.shareAction": "Grant access",
   "node.email": "Email address",
+  "node.emailHint": "Intel cannot check whether an account exists behind this address. The grant takes effect as soon as somebody signs in with it — including after they register.",
+  "node.shareWith": "Who gets access",
+  "node.shareWithEmail": "One email address",
+  "node.shareWithOrganization": "Everyone in the organization",
+  "node.shareOrganizationHint": "Every signed-in member of the organization gets this access, including people who join later.",
+  "node.shareLibraryWarning": "Run for the whole organization makes this folder a library: flows anywhere in the tree may then call into it. Taking it back is refused while any of them still does.",
+  "node.revokeInUse": "This access cannot be withdrawn yet, because flows outside this folder still call into it.",
+  "node.someUser": "A user account",
   "node.verbs": "What this grant allows",
   "node.verb.read": "Read",
   "node.verb.write": "Write",
@@ -158,7 +166,7 @@
   "node.saveError": "This document could not be saved. Reload and try again.",
   "tools.signingIn": "Signing you in to the company portal…",
   "tools.noAccess": "No access to the company portal",
-  "tools.noAccessHelp": "Your Intel account does not reach the company MCP portal, so there is nothing to show here. An administrator decides in the portal who may use which server; ask them to include you.",
+  "tools.noAccessHelp": "Your account is not permitted to reach the company MCP portal, so there is nothing to show here. That permission is not given in Intel — ask whoever administers the accounts of your organisation to grant it.",
   "tools.empty": "No tools available to you",
   "tools.emptyHelp": "The portal answered, and it offers your account no tools. An administrator decides in the portal which servers exist and who may reach them.",
   "tools.unreachable": "Portal not reachable",
@@ -167,7 +175,9 @@
   "tools.connectExpiredHelp": "The connection to the company MCP portal has to be completed within a few minutes, and this one ran out while the authorization screen was open. Nothing went wrong and nothing was refused — start it again and confirm the servers when the screen appears.",
   "tools.connectRetry": "Start again",
   "tools.connectFailed": "Portal sign-in failed",
-  "tools.connectFailedHelp": "The sign-in to the company MCP portal broke before it could be answered. This is a technical fault, not a decision about your access — reload to try again, and tell an administrator if it stays.",
+  "tools.connectFailedHelp": "The sign-in to the company MCP portal broke before it could be answered. This is a technical fault, not a decision about your access — start it again, and tell an administrator if it stays.",
+  "tools.connectUnknown": "Intel does not know whether you reach the portal",
+  "tools.connectUnknownHelp": "A sign-in to the company MCP portal was started in this browser session and never came back with an answer, so nothing here says you were allowed or refused. Start it again; if it keeps ending here, tell an administrator.",
   "tools.origin": "Origin",
   "tools.originUnlisted": "Not from a listed server",
   "tools.originUnlistedHelp": "The portal's server list names no server for these. Its own management tools sit here — the portal does not list itself — and so does anything from a server the list did not mention.",
@@ -302,6 +312,7 @@
   "common.save": "Save",
   "common.saving": "Saving…",
   "common.saved": "Saved",
+  "common.saveNothing": "Nothing to save",
   "common.saveDirty": "Save unsaved changes",
   "common.unsavedTitle": "Unsaved changes",
   "common.unsavedBody": "This has changes that have not been saved. Leaving now discards them.",
@@ -310,5 +321,7 @@
   "common.loading": "Loading…",
   "common.retry": "Try again",
   "common.close": "Close",
-  "common.unavailable": "Intel is currently unavailable."
+  "common.unavailable": "Intel is currently unavailable.",
+  "common.noAccess": "This is not available to you. It may not exist, or it may no longer be shared with you.",
+  "common.noPermission": "You do not have permission to see this."
 }

package/src/i18n/es.json

@@ -112,6 +112,14 @@
   "node.share": "Compartir",
   "node.shareAction": "Conceder acceso",
   "node.email": "Dirección de correo",
+  "node.emailHint": "Intel no puede comprobar si existe una cuenta detrás de esta dirección. El permiso surte efecto en cuanto alguien inicie sesión con ella, incluso si se registra más tarde.",
+  "node.shareWith": "Quién obtiene acceso",
+  "node.shareWithEmail": "Una dirección de correo",
+  "node.shareWithOrganization": "Todos en la organización",
+  "node.shareOrganizationHint": "Todos los miembros de la organización que hayan iniciado sesión obtienen este acceso, incluidos quienes se incorporen más tarde.",
+  "node.shareLibraryWarning": "Ejecutar para toda la organización convierte esta carpeta en una biblioteca: los flujos de cualquier parte del árbol podrán invocarla. Retirarlo se rechaza mientras alguno siga haciéndolo.",
+  "node.revokeInUse": "Este acceso todavía no se puede retirar, porque hay flujos fuera de esta carpeta que siguen invocándola.",
+  "node.someUser": "Una cuenta de usuario",
   "node.verbs": "Qué permite este acceso",
   "node.verb.read": "Leer",
   "node.verb.write": "Escribir",
@@ -158,7 +166,7 @@
   "node.saveError": "Este documento no se ha podido guardar. Recarga e inténtalo de nuevo.",
   "tools.signingIn": "Iniciando tu sesión en el portal de la empresa…",
   "tools.noAccess": "Sin acceso al portal de la empresa",
-  "tools.noAccessHelp": "Tu cuenta de Intel no llega al portal MCP de la empresa, así que aquí no hay nada que mostrar. Quién puede usar qué servidor lo decide la administración en el portal; pídeles que te incluyan.",
+  "tools.noAccessHelp": "Tu cuenta no tiene permiso para llegar al portal MCP de la empresa, así que aquí no hay nada que mostrar. Ese permiso no se concede en Intel — pídeselo a quien administre las cuentas de tu organización.",
   "tools.empty": "No tienes herramientas disponibles",
   "tools.emptyHelp": "El portal ha respondido, y no ofrece ninguna herramienta a tu cuenta. Qué servidores existen y quién llega a ellos lo decide la administración en el portal.",
   "tools.unreachable": "Portal no accesible",
@@ -167,7 +175,9 @@
   "tools.connectExpiredHelp": "La conexión con el portal MCP de la empresa tiene que completarse en unos minutos, y esta se ha agotado mientras la pantalla de autorización estaba abierta. No ha fallado nada ni se ha denegado nada — vuelve a empezar y confirma los servidores cuando aparezca la pantalla.",
   "tools.connectRetry": "Empezar de nuevo",
   "tools.connectFailed": "El inicio de sesión en el portal ha fallado",
-  "tools.connectFailedHelp": "El inicio de sesión en el portal MCP de la empresa se ha interrumpido antes de poder responderse. Es un fallo técnico, no una decisión sobre tu acceso — recarga para intentarlo otra vez y avisa a la administración si persiste.",
+  "tools.connectFailedHelp": "El inicio de sesión en el portal MCP de la empresa se ha interrumpido antes de poder responderse. Es un fallo técnico, no una decisión sobre tu acceso — vuelve a empezar y avisa a la administración si persiste.",
+  "tools.connectUnknown": "Intel no sabe si llegas al portal",
+  "tools.connectUnknownHelp": "En esta sesión del navegador se inició un acceso al portal MCP de la empresa que nunca volvió con una respuesta, así que aquí no dice ni que se te haya permitido ni que se te haya denegado. Vuelve a empezar; si sigue acabando aquí, avisa a la administración.",
   "tools.origin": "Origen",
   "tools.originUnlisted": "No procede de un servidor listado",
   "tools.originUnlistedHelp": "La lista de servidores del portal no nombra ningún servidor para estas. Aquí están sus propias herramientas de gestión — el portal no se lista a sí mismo — y también todo lo que venga de un servidor que la lista no mencionó.",
@@ -302,6 +312,7 @@
   "common.save": "Guardar",
   "common.saving": "Guardando…",
   "common.saved": "Guardado",
+  "common.saveNothing": "Nada que guardar",
   "common.saveDirty": "Guardar los cambios sin guardar",
   "common.unsavedTitle": "Cambios sin guardar",
   "common.unsavedBody": "Esto tiene cambios que no se han guardado. Si sales ahora, se descartan.",
@@ -310,5 +321,7 @@
   "common.loading": "Cargando…",
   "common.retry": "Intentarlo de nuevo",
   "common.close": "Cerrar",
-  "common.unavailable": "Intel no está disponible en este momento."
+  "common.unavailable": "Intel no está disponible en este momento.",
+  "common.noAccess": "Esto no está disponible para ti. Puede que no exista o que ya no esté compartido contigo.",
+  "common.noPermission": "No tienes permiso para ver esto."
 }

package/src/main.tsx

@@ -1,4 +1,4 @@
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { QueryClientProvider } from "@tanstack/react-query";
 import { RouterProvider } from "@tanstack/react-router";
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
@@ -6,6 +6,7 @@ import {
   createIntelDataProvider,
   loginPath,
 } from "@/data/intel-data-provider/intel-data-provider.ts";
+import { createIntelQueryClient } from "@/data/query-client.ts";
 import { createBrowserSignIn, createSignInGuard } from "@/data/sign-in/sign-in.ts";
 import { I18nProvider } from "@/i18n/i18n-context.tsx";
 import { createLanguages } from "@/i18n/i18n-languages/i18n-languages.ts";
@@ -32,7 +33,7 @@ if (!root) throw new Error("Missing #root element");
 const languages = createLanguages({ store: window.localStorage });
 const signIn = createBrowserSignIn(loginPath);
 const mounted = createRoot(root);
-const queryClient = new QueryClient();
+const queryClient = createIntelQueryClient();
 
 // The shell is painted from a function because a refused sign-in has to replace it, and that
 // refusal arrives from inside a fetch rather than from React.

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

@@ -120,6 +120,11 @@ export function NodeEditor({
         mediaType: BlockNoteMediaType,
         idempotencyKey: crypto.randomUUID(),
       });
+      // ⚠️ An answer that carries no version did not save anything (#432). Letting it through would
+      // move `savedSnapshot` forward, drop the unsaved warning and leave the reader free to close
+      // the tab — over a document the server still reports as empty. It belongs on the error path,
+      // which is the one place the screen already says that the writing failed.
+      if (!node.version) throw new Error("save_without_version");
       // ⚠️ The snapshot of what was SENT, not of what stands in the editor when the answer comes
       // back. Saving crosses the network, and typing during it is normal — taking the state at
       // arrival would call that typing saved and lose it at the next navigation.
@@ -162,7 +167,15 @@ export function NodeEditor({
           because this is where `dirty` lives — moving the state up to the screen would mean the
           screen tracking every keystroke in an editor it does not own. */}
       <ActionSlot name="title-actions">
-        <SaveButton dirty={dirty} saving={save.isPending} onSave={() => save.mutate()} />
+        {/* ⚠️ `stored` comes from the document the screen holds, not from a flag this component
+            sets on success: it turns true when the answer that carried a version has reached the
+            query cache, and never a moment earlier (#432). */}
+        <SaveButton
+          dirty={dirty}
+          saving={save.isPending}
+          stored={document.version !== null}
+          onSave={() => save.mutate()}
+        />
       </ActionSlot>
       <UnsavedChangesGuard dirty={dirty} />
       {save.isError && (

package/src/nodes/nodes.tsx

@@ -6,6 +6,7 @@ import { lazy, Suspense, useState } from "react";
 import { ActionSlot } from "@/app/action-slot/action-slot.tsx";
 import { ViewToggle } from "@/app/view-toggle/view-toggle.tsx";
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip";
+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";
 import { useI18n } from "@/i18n/i18n-context.tsx";
@@ -39,6 +40,10 @@ export function Nodes() {
     enabled: Boolean(selectedId),
   });
   const selected = document.data?.node ?? null;
+  // ⚠️ Off the ERROR, not off the absence of data: a query that has not answered is not a query that
+  // 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);
   // 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,6 +85,21 @@ export function Nodes() {
           </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>
         ) : 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

@@ -1,6 +1,6 @@
 import type { Flow, FlowValidation } from "@anchrd/intel-contract/flow";
 import type { Node } from "@anchrd/intel-contract/node";
-import type { ResourceVerb, UnreadableNodes } from "@anchrd/intel-contract/share";
+import type { ResourceGrant, ResourceVerb, UnreadableNodes } from "@anchrd/intel-contract/share";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useNavigate, useRouterState } from "@tanstack/react-router";
 import {
@@ -29,13 +29,14 @@ import {
   DropdownMenuSubTrigger,
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
-import { flowEntry } from "@/data/intel-data-provider/intel-data-provider.ts";
+import { flowEntry, IntelRequestError } from "@/data/intel-data-provider/intel-data-provider.ts";
 import type { TreeEntry } from "@/data/intel-data-provider/intel-data-provider.types.ts";
 import { useI18n } from "@/i18n/i18n-context.tsx";
 import { useBundleImport } from "@/import-bundle/import-bundle.tsx";
 import { Modal } from "@/modal/modal.tsx";
 import { useIntelRouterContext } from "@/router/router-context.ts";
 import { selectedFrom } from "@/router/selection-search.ts";
+import { useUserName } from "@/user-name/user-name.ts";
 
 /**
  * What a resource's own actions are, at the place the resource stands (#24).
@@ -576,10 +577,76 @@ function NodeLinksPanel({ node, close }: { node: Node; close(): void }) {
 // flows, which is where a permission decision belongs (ADR-0004 §2). Which verbs it offers is the
 // server's answer, not this component's: `execute` never appears on a document, because a document
 // has nothing to run.
+/**
+ * One row of the grant list.
+ *
+ * ⚠️ It is a component rather than a line inside the `map` because of `useUserName`, and that hook
+ * is the point: until #431 a `user` grant printed its raw id — `2C9lEhT82upO82abPjHFAvs24a7Vdd3J`
+ * beside the word "Read" — which tells the reader nothing about who they let in and puts an
+ * identifier on a screen that has no reason to carry one. `user-name.ts` already had the rule
+ * ("never fall back to the id, show nothing instead", #258); this row was the last place breaking it.
+ *
+ * ⚠️ Intel can resolve exactly ONE id today: the signed-in person's. A foreign one is not "a name we
+ * could probably guess" but genuinely unanswerable — Intel has no user directory (#261) — so what
+ * stands there is what is true: an account, unnamed. The day #261 lands, `useUserName` starts
+ * answering and this row needs no change.
+ */
+function GrantRow({ grant, onRevoke }: { grant: ResourceGrant; onRevoke(grantId: string): void }) {
+  const i18n = useI18n();
+  const userName = useUserName(grant.principal.type === "user" ? grant.principal.id : null);
+  // ⚠️ An `email` grant keeps showing the ADDRESS, even where a name is known, and that is a
+  // decision rather than an oversight (#431, review finding). The grant is bound to the address —
+  // `db-grants.ts` matches `lower(principal_id)` against whoever signs in — not to an account.
+  // Putting a name there would claim a binding that does not exist, and it would be wrong the moment
+  // somebody else verifies that address.
+  const who =
+    grant.principal.type === "email"
+      ? grant.principal.email
+      : grant.principal.type === "user"
+        ? (userName ?? i18n.t("node.someUser"))
+        : i18n.t("node.organization");
+  return (
+    <li className="flex items-center justify-between gap-3 rounded-md border p-3 text-sm">
+      <span className="min-w-0 truncate">
+        {who}
+        <span className="ml-2 text-xs text-muted-foreground">
+          {i18n.t(`node.verb.${grant.verb}`)}
+        </span>
+      </span>
+      <button
+        type="button"
+        onClick={() => onRevoke(grant.id)}
+        aria-label={i18n.t("node.revokeShare")}
+        className="rounded-md p-2 text-destructive outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring"
+      >
+        <Trash2 aria-hidden="true" className="size-4" />
+      </button>
+    </li>
+  );
+}
+
+/**
+ * Which of the three principals the dialog can SET (#431).
+ *
+ * ⚠️ `user` is deliberately absent, and it is a decision rather than an omission. Setting one means
+ * naming a Gate user id, and Intel has no way to turn a person into an id or an id into a person
+ * (#261) — so the only offer this dialog could make is a field for a raw ULID, which is worse than
+ * the address it would replace: unverifiable when typed and unreadable afterwards. It stays reachable
+ * over the API and over MCP, where the caller already holds the id. The day #261 lands it becomes a
+ * picker, not a text field.
+ *
+ * ⚠️ `organization` IS here, and the reason is the asymmetry it removes: the dialog could already
+ * DRAW an organization grant ("Everyone in the organization") and not make one, and MCP could make
+ * one all along — a person had strictly less reach than a model on the same tree. It needs nothing
+ * Intel does not have, because there is nothing to name.
+ */
+type SharePrincipalKind = "email" | "organization";
+
 function SharePanel({ node, close }: { node: Node; close(): void }) {
   const { data } = useIntelRouterContext();
   const i18n = useI18n();
   const queryClient = useQueryClient();
+  const [principalKind, setPrincipalKind] = useState<SharePrincipalKind>("email");
   const [email, setEmail] = useState("");
   const [verbs, setVerbs] = useState<ResourceVerb[]>(["read"]);
   // What the grant just made does not cover. It survives the form being cleared, because it is the
@@ -600,7 +667,10 @@ function SharePanel({ node, close }: { node: Node; close(): void }) {
         last = (
           await data.shareNode({
             resourceId: node.id,
-            principal: { type: "email", email },
+            principal:
+              principalKind === "organization"
+                ? { type: "organization" }
+                : { type: "email", email },
             verb,
             expiresAt: null,
             idempotencyKey: crypto.randomUUID(),
@@ -611,6 +681,10 @@ function SharePanel({ node, close }: { node: Node; close(): void }) {
     },
     onSuccess: (result) => {
       setEmail("");
+      // ⚠️ The choice is cleared with the address, not left standing. It survived a successful grant
+      // until the review of #431 caught it, and "everyone in the organization" is the one setting
+      // that must never be the quiet default for the NEXT grant somebody makes in the same dialog.
+      setPrincipalKind("email");
       setUnreadable(result);
     },
     // ⚠️ `onSettled`, not `onSuccess`. One request per verb means a run can end halfway: three verbs
@@ -633,12 +707,39 @@ function SharePanel({ node, close }: { node: Node; close(): void }) {
     },
   });
 
+  /**
+   * The one refusal in this dialog that names something the reader has to act on.
+   *
+   * ⚠️ Taking back `organization` + `execute` on a folder is refused with `409
+   * folder_execute_in_use` while flows from outside still call into it (`nodes.ts`,
+   * `revokeGrant`) — and the refusal's `detail` is the only place the CALLERS are named. Rendering
+   * it as the generic "access was not changed" threw exactly that away and left the reader with a
+   * dialog that refuses and will not say why, for the one grant that is hardest to undo.
+   *
+   * ⚠️ The server's own words, on purpose. `callersDetail` names the flows this actor may see and
+   * only COUNTS the rest, so it is actionable without becoming a directory of the tree — a
+   * translated stand-in would either lose the names or need them separately, and the wire carries
+   * prose rather than a list (#448). The lead-in sentence above it is translated; this line is the
+   * evidence under it.
+   */
+  const revokeInUse =
+    revoke.error instanceof IntelRequestError && revoke.error.code === "folder_execute_in_use"
+      ? revoke.error.message
+      : null;
+
   return (
     <Modal title={i18n.t("node.share")} close={close}>
-      {(share.isError || revoke.isError || grants.isError) && (
-        <p role="alert" className="mb-4 text-sm text-destructive">
-          {i18n.t("node.shareFailed")}
-        </p>
+      {revokeInUse ? (
+        <div role="alert" className="mb-4 space-y-1 text-sm text-destructive">
+          <p>{i18n.t("node.revokeInUse")}</p>
+          <p className="text-xs">{revokeInUse}</p>
+        </div>
+      ) : (
+        (share.isError || revoke.isError || grants.isError) && (
+          <p role="alert" className="mb-4 text-sm text-destructive">
+            {i18n.t("node.shareFailed")}
+          </p>
+        )
       )}
       {/* ⚠️ `status`, not `alert`, and beside the grant rather than in place of it: the access was
           given. A node reference across the folder edge is a possible failure, not a way around
@@ -660,29 +761,14 @@ function SharePanel({ node, close }: { node: Node; close(): void }) {
       )}
       <ul className="mb-5 max-h-44 space-y-2 overflow-y-auto">
         {grants.data?.items.map((grant) => (
-          <li
+          <GrantRow
             key={grant.id}
-            className="flex items-center justify-between gap-3 rounded-md border p-3 text-sm"
-          >
-            <span className="min-w-0 truncate">
-              {grant.principal.type === "email"
-                ? grant.principal.email
-                : grant.principal.type === "user"
-                  ? grant.principal.id
-                  : i18n.t("node.organization")}
-              <span className="ml-2 text-xs text-muted-foreground">
-                {i18n.t(`node.verb.${grant.verb}`)}
-              </span>
-            </span>
-            <button
-              type="button"
-              onClick={() => revoke.mutate(grant.id)}
-              aria-label={i18n.t("node.revokeShare")}
-              className="rounded-md p-2 text-destructive outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring"
-            >
-              <Trash2 aria-hidden="true" className="size-4" />
-            </button>
-          </li>
+            grant={grant}
+            onRevoke={(grantId) => {
+              share.reset();
+              revoke.mutate(grantId);
+            }}
+          />
         ))}
         {grants.data?.items.length === 0 && (
           <li className="text-sm text-muted-foreground">{i18n.t("node.noGrants")}</li>
@@ -691,20 +777,99 @@ function SharePanel({ node, close }: { node: Node; close(): void }) {
       <form
         onSubmit={(event) => {
           event.preventDefault();
+          // ⚠️ The other mutation's error is cleared before this one starts, in both directions. A
+          // refused withdrawal keeps its `409` until something resets it, and `revokeInUse` takes
+          // precedence over the general sentence — so without this, a share that failed AFTER a
+          // refused withdrawal said nothing at all, and the reader was left reading a sentence
+          // about the wrong action. That is the exact failure mode #430 removed one level up.
+          revoke.reset();
           share.mutate();
         }}
         className="space-y-4 border-t pt-5"
       >
-        <label className="block text-sm font-medium">
-          {i18n.t("node.email")}
-          <input
-            type="email"
-            required
-            value={email}
-            onChange={(event) => setEmail(event.target.value)}
-            className="mt-2 w-full rounded-md border bg-background px-3 py-2 outline-none focus-visible:ring-2 focus-visible:ring-ring"
-          />
-        </label>
+        {/* ⚠️ Two of the three principals, and the missing one is a decision — see
+            `SharePrincipalKind`. Radios rather than a select: there are two, and a reader has to see
+            that granting to the whole organization is a thing this dialog does at all. */}
+        <fieldset className="space-y-2">
+          <legend className="text-sm font-medium">{i18n.t("node.shareWith")}</legend>
+          {(["email", "organization"] as const).map((kind) => (
+            <label key={kind} className="flex items-center gap-2 text-sm">
+              <input
+                type="radio"
+                name="share-principal"
+                checked={principalKind === kind}
+                onChange={() => setPrincipalKind(kind)}
+                aria-describedby={kind === "email" ? "share-email-hint" : "share-organization-hint"}
+                className="size-4 border outline-none focus-visible:ring-2 focus-visible:ring-ring"
+              />
+              <span>
+                {i18n.t(kind === "email" ? "node.shareWithEmail" : "node.shareWithOrganization")}
+              </span>
+            </label>
+          ))}
+        </fieldset>
+        {principalKind === "email" ? (
+          <div>
+            {/* ⚠️ The hint stands OUTSIDE the label and is tied on with `aria-describedby`. Inside
+                it, its words would become part of the field's accessible NAME — a screen reader
+                would announce the whole paragraph as the label of the input, and every query by
+                label would have to spell it out too. */}
+            <label className="block text-sm font-medium">
+              {i18n.t("node.email")}
+              <input
+                type="email"
+                required
+                value={email}
+                onChange={(event) => setEmail(event.target.value)}
+                aria-describedby="share-email-hint"
+                className="mt-2 w-full rounded-md border bg-background px-3 py-2 outline-none focus-visible:ring-2 focus-visible:ring-ring"
+              />
+            </label>
+            {/* ⚠️ What this says is what Intel knows, and no more (#431). It cannot check whether an
+                address belongs to anybody — Gate owns identity and offers Intel no lookup (#261) —
+                and a dialog that stayed silent about that let a typo become a grant that is valid,
+                permanent and completely without effect, with nobody on either side to notice. Naming
+                the uncertainty is the honest half of what the ticket asks for; the other half needs
+                Gate. */}
+            <p id="share-email-hint" className="mt-1 text-xs text-muted-foreground">
+              {i18n.t("node.emailHint")}
+            </p>
+          </div>
+        ) : (
+          /* ⚠️ `aria-live` on the CONTAINER, which is already mounted whenever this branch is on
+              screen — not on the warning inside it. A live region has to exist before its content
+              changes, so putting it on a paragraph that appears at the same moment announces
+              nothing. The gap it closes: `Run` is ticked while the focus sits in the verb fieldset,
+              far from here, and the sentence about what is being made would otherwise arrive in
+              silence. (The other way in is covered already: `aria-describedby` on the radio reads
+              this whole box out when the radio takes focus.) */
+          <div
+            id="share-organization-hint"
+            aria-live="polite"
+            className="space-y-2 rounded-md border bg-muted p-3 text-xs"
+          >
+            <p className="text-muted-foreground">{i18n.t("node.shareOrganizationHint")}</p>
+            {/* ⚠️ `organization` + `execute` on a folder is not one grant among four: it is the
+                definition of a LIBRARY (ADR-0004 §3) — the one grant a flow may call across a folder
+                edge for, so flows from anywhere in the tree may then reach in. Two clicks in this
+                dialog now do what used to take an API call, and the reader has to be told what they
+                are about to make BEFORE they make it.
+
+                ⚠️ The second sentence is the one that matters most, because it is about the way
+                back: `revokeGrant` refuses with `folder_execute_in_use` while callers remain, so
+                this is the single hardest grant in the product to undo. Naming the consequence after
+                the fact would be the "wrong sentence" class anchrd/core#111 collects.
+
+                It is a warning and not a block, deliberately: the library is a documented, wanted
+                shape, MCP has always been able to make one, and refusing it here would put a person
+                back below a model on the same tree — the very asymmetry this ticket removed. */}
+            {verbs.includes("execute") ? (
+              <p role="note" className="font-medium text-destructive">
+                {i18n.t("node.shareLibraryWarning")}
+              </p>
+            ) : null}
+          </div>
+        )}
         <fieldset className="space-y-2">
           <legend className="text-sm font-medium">{i18n.t("node.verbs")}</legend>
           {(grants.data?.applicableVerbs ?? []).map((verb) => (

package/src/save-button/save-button.tsx

@@ -14,18 +14,28 @@ import { Modal } from "@/modal/modal.tsx";
  * ⚠️ The accessible name names the state as well — "Saved" and "Save unsaved changes" are two
  * different pieces of information, and a screen reader gets neither the fill nor the dot. The
  * visible word stays a prefix of it, so speech input still reaches the button by what it reads.
+ *
+ * ⚠️ At rest there are TWO states, not one, and `stored` is what tells them apart (#432). A
+ * document that has never been written has nothing to save either — and calling that "Saved" is the
+ * one sentence an editor must never say untruthfully: whoever reads it closes the tab. The button
+ * was already unclickable in that state, which is exactly why it went unnoticed for so long; the
+ * tooltip and the accessible name kept claiming a version that does not exist. "Nothing to save"
+ * says less and stays true in both readings.
  */
 export function SaveButton({
   dirty,
   saving,
+  stored,
   onSave,
 }: {
   dirty: boolean;
   saving: boolean;
+  /** Whether what is being edited has content on the server at all. */
+  stored: boolean;
   onSave(): void;
 }) {
   const i18n = useI18n();
-  const label = i18n.t(dirty ? "common.saveDirty" : "common.saved");
+  const label = i18n.t(dirty ? "common.saveDirty" : stored ? "common.saved" : "common.saveNothing");
   return (
     <TooltipProvider delayDuration={300}>
       <Tooltip>

package/src/tools/tools.tsx

@@ -1,7 +1,15 @@
 import { serverOf, type ToolCapability, type ToolServer } from "@anchrd/intel-contract/tool";
 import { useQuery } from "@tanstack/react-query";
 import { useRouterState } from "@tanstack/react-router";
-import { AlertTriangle, ChevronRight, PlugZap, ShieldOff, Timer, Wrench } from "lucide-react";
+import {
+  AlertTriangle,
+  ChevronRight,
+  HelpCircle,
+  PlugZap,
+  ShieldOff,
+  Timer,
+  Wrench,
+} from "lucide-react";
 import * as React from "react";
 import { Button } from "@/components/ui/button";
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@/components/ui/collapsible";
@@ -65,8 +73,36 @@ function groupByServer(
 // visit. A second attempt after a refusal would be a redirect loop with an unchanging answer, and
 // the marker in the URL only survives until the next navigation — the browser session remembers it
 // instead (#60).
+//
+// ⚠️ It records that an attempt was STARTED, never that one was answered (#426). A sign-in that
+// crashed on the way leaves exactly the same note as one that came back, so nothing may read it as
+// a verdict about anybody: it only keeps the screen from walking in a circle on its own, and what
+// the reader is told comes from the marker in the URL instead. That is the whole distinction — the
+// note is never cleared to make a second attempt possible; the button is what makes one possible.
 const SignInAttemptKey = "intel.portal-sign-in-attempted";
 
+/**
+ * What came back from the silent walk — and "nothing" is one of the answers (#426).
+ *
+ * The marker in the URL is the only thing that ever says why the walk ended, and it is absent in two
+ * situations that look identical from here: the attempt never ran, or it broke before it could
+ * return. Neither is a decision about access, so neither may borrow the sentence that describes one
+ * — the rule `packages/ui/CLAUDE.md` keeps from #350: **a missing statement is a reason to say less,
+ * never to refuse more.** Saying "no access" for `none` sent a reader hunting through portal
+ * policies while the sign-in had answered 500 (#425).
+ */
+type PortalAnswer = "refused" | "expired" | "failed" | "none";
+
+function portalAnswerOf(connectError: string | null): PortalAnswer {
+  if (connectError === null) return "none";
+  if (connectError === "portal_sign_in_expired") return "expired";
+  // The two codes Intel itself writes when somebody was actually turned away — by the portal, or by
+  // Gate before the portal was ever asked. Every other marker is machinery, not policy.
+  return connectError === "portal_sign_in_refused" || connectError === "permission_required"
+    ? "refused"
+    : "failed";
+}
+
 // Reading `sessionStorage` throws outright in a few privacy modes, so the guard is a try, not a
 // feature check. Losing the note costs one extra redirect, and the marker the refusal leaves in the
 // URL still ends the walk — it must never cost the screen.
@@ -109,10 +145,30 @@ export function Tools() {
     typeof window === "undefined"
       ? null
       : new URLSearchParams(window.location.search).get("connectError");
-  const refused = connectError !== null;
-  const accessDenied =
-    connectError === "portal_sign_in_refused" || connectError === "permission_required";
-  const [signingIn, setSigningIn] = React.useState(false);
+  const answer = portalAnswerOf(connectError);
+  // What the screen DID about that answer, which is a third thing beside the catalog and the marker.
+  //
+  // ⚠️ Only `none` starts undecided. `useEffect` runs after the paint, so a state that always began
+  // at `deciding` would push a "Loading" frame in front of all four notices — and three of them are
+  // already settled at the first render, because their answer stands in the URL. It would flash at
+  // exactly the readers who just arrived out of a redirect. `none` is the one that genuinely has to
+  // wait: its walk starts one tick after the catalog arrives, and "we do not know" in between is a
+  // sentence the screen takes back immediately.
+  const [walk, setWalk] = React.useState<"deciding" | "running" | "stopped">(
+    answer === "none" ? "deciding" : "stopped",
+  );
+
+  const startSignIn = React.useCallback(() => {
+    // ⚠️ `setItem`, and the marker is not cleared anywhere on this path. Pressing the button STARTS
+    // an attempt, which is the only thing the marker ever claims — clearing it would buy the click
+    // nothing (no code in this path reads it) and cost the next visit: an attempt that dies without
+    // ever coming back with a marker would be followed by a silent redirect nobody asked for, on a
+    // screen that has just said it does not understand what is happening. The second attempt this
+    // browser session owes its reader is this button, never a re-armed guard.
+    attemptStore()?.setItem(SignInAttemptKey, "1");
+    setWalk("running");
+    data.startPortalSignIn("/tools");
+  }, [data]);
 
   // ⚠️ Nobody is asked to start this. The portal sign-in is a browser redirect, so the screen
   // begins it itself the moment the catalog says there is no portal session yet — that is the whole
@@ -126,11 +182,14 @@ export function Tools() {
       attempts?.removeItem(SignInAttemptKey);
       return;
     }
-    if (refused || attempts?.getItem(SignInAttemptKey)) return;
+    if (answer !== "none" || attempts?.getItem(SignInAttemptKey)) {
+      setWalk("stopped");
+      return;
+    }
     attempts?.setItem(SignInAttemptKey, "1");
-    setSigningIn(true);
+    setWalk("running");
     data.startPortalSignIn("/tools");
-  }, [catalog.data, data, refused]);
+  }, [catalog.data, data, answer]);
 
   return (
     <div className="min-h-full p-8">
@@ -151,43 +210,12 @@ export function Tools() {
             </Button>
           </Notice>
         ) : !catalog.data.portalConnected ? (
-          signingIn ? (
+          walk === "deciding" ? (
+            <p className="text-sm text-muted-foreground">{i18n.t("common.loading")}</p>
+          ) : walk === "running" ? (
             <p className="text-sm text-muted-foreground">{i18n.t("tools.signingIn")}</p>
-          ) : connectError === "portal_sign_in_expired" ? (
-            // Ran out of time on the consent screen. Nothing is broken and nobody was refused, so
-            // neither of the other two sentences fits — and this one is the only case the reader
-            // can fix alone, by starting over (#95).
-            <Notice
-              icon={<Timer aria-hidden="true" className="mx-auto size-8 text-muted-foreground" />}
-              title={i18n.t("tools.connectExpired")}
-              help={i18n.t("tools.connectExpiredHelp")}
-            >
-              <Button variant="outline" onClick={() => data.startPortalSignIn("/tools")}>
-                {i18n.t("tools.connectRetry")}
-              </Button>
-            </Notice>
-          ) : accessDenied || !refused ? (
-            // The end of the silent walk for somebody no Access policy carries. It is a sentence
-            // about access, not an invitation to connect: there is nothing they could click that
-            // would change the answer, and what the portal replied is not repeated here.
-            <Notice
-              alert
-              icon={
-                <ShieldOff aria-hidden="true" className="mx-auto size-8 text-muted-foreground" />
-              }
-              title={i18n.t("tools.noAccess")}
-              help={i18n.t("tools.noAccessHelp")}
-            />
           ) : (
-            // Every other marker is machinery, not policy: the sign-in broke before anyone could
-            // be allowed or refused. Saying "no access" here sent the last reader hunting through
-            // Access policies while the real fault sat in a failed client registration (#93).
-            <Notice
-              alert
-              icon={<PlugZap aria-hidden="true" className="mx-auto size-8 text-destructive" />}
-              title={i18n.t("tools.connectFailed")}
-              help={i18n.t("tools.connectFailedHelp")}
-            />
+            <PortalNotice answer={answer} i18n={i18n} onRetry={startSignIn} />
           )
         ) : catalog.data.items.length === 0 ? (
           <Notice
@@ -212,6 +240,81 @@ export function Tools() {
   );
 }
 
+/**
+ * The end of the silent walk, in the words of whatever ended it — one sentence per answer, and no
+ * sentence shared between two of them (#426).
+ *
+ * ⚠️ Only `refused` is a statement about ACCESS, and only it is a dead end: there is nothing the
+ * reader could press that would change the answer, so nothing is offered. The other two are the
+ * machinery and the silence, and both are worth another attempt — which is the button the screen
+ * lacked entirely while the marker in `sessionStorage` made the first attempt the only one.
+ */
+function PortalNotice({
+  answer,
+  i18n,
+  onRetry,
+}: {
+  answer: PortalAnswer;
+  i18n: I18n;
+  onRetry: () => void;
+}) {
+  if (answer === "refused") {
+    return (
+      <Notice
+        alert
+        icon={<ShieldOff aria-hidden="true" className="mx-auto size-8 text-muted-foreground" />}
+        title={i18n.t("tools.noAccess")}
+        help={i18n.t("tools.noAccessHelp")}
+      />
+    );
+  }
+  // Ran out of time on the consent screen. Nothing is broken and nobody was refused, so neither of
+  // the other sentences fits (#95).
+  if (answer === "expired") {
+    return (
+      <Notice
+        icon={<Timer aria-hidden="true" className="mx-auto size-8 text-muted-foreground" />}
+        title={i18n.t("tools.connectExpired")}
+        help={i18n.t("tools.connectExpiredHelp")}
+      >
+        <Button variant="outline" onClick={onRetry}>
+          {i18n.t("tools.connectRetry")}
+        </Button>
+      </Notice>
+    );
+  }
+  // A marker that is neither of the two access answers is machinery, not policy: the sign-in broke
+  // before anyone could be allowed or refused. Saying "no access" here sent the last reader hunting
+  // through Access policies while the real fault sat in a failed client registration (#93).
+  if (answer === "failed") {
+    return (
+      <Notice
+        alert
+        icon={<PlugZap aria-hidden="true" className="mx-auto size-8 text-destructive" />}
+        title={i18n.t("tools.connectFailed")}
+        help={i18n.t("tools.connectFailedHelp")}
+      >
+        <Button variant="outline" onClick={onRetry}>
+          {i18n.t("tools.connectRetry")}
+        </Button>
+      </Notice>
+    );
+  }
+  // No marker at all, and an attempt already made in this browser session: it never came back. The
+  // screen says exactly that — not "no access", which is a decision nobody made here.
+  return (
+    <Notice
+      icon={<HelpCircle aria-hidden="true" className="mx-auto size-8 text-muted-foreground" />}
+      title={i18n.t("tools.connectUnknown")}
+      help={i18n.t("tools.connectUnknownHelp")}
+    >
+      <Button variant="outline" onClick={onRetry}>
+        {i18n.t("tools.connectRetry")}
+      </Button>
+    </Notice>
+  );
+}
+
 /**
  * The catalog, under the portal's servers where there are any.
  *