@anchrd/intel-api 0.24.0 → 0.25.0

package/README.md

@@ -75,12 +75,29 @@ values it stops with `Error: GATE_URL and GATE_SERVICE_KEY must be set.` before
 It declares five interfaces — `intel`, `nodes`, `flows`, `tools`, `mcp` — with the functions listed
 under *Permission, layer one* below. It is idempotent and safe to repeat after an upgrade.
 
-⚠️ **`bootstrap` declares interfaces and changes no grant.** It creates the permissions an
-administrator can hand out; it hands out none of them. This is step 8, and it is why a fresh
-installation shows an empty screen to everybody including the person who installed it.
+⚠️ **`bootstrap` hands out no grant, and it takes none away as long as the declared list does not
+change.** It creates the permissions an administrator can hand out; it hands out none of them. This
+is step 8, and it is why a fresh installation shows an empty screen to everybody including the
+person who installed it.
 
-⚠️ It also never revokes. An interface an older version declared stays declared in Gate; that is
-harmless, and removing one is an act in Gate, by hand.
+⚠️ **But a function that falls out of a still-declared interface takes its grants with it.**
+Declaring is an upsert that REPLACES an interface's function list, and Gate deletes every grant on a
+function the new list no longer names. So an upgrade that retires a function also retires every role
+assignment on it — against a running installation that is a change to who may do what, not a
+read. `bootstrap` reads the catalog before it writes and names each one as it goes:
+
+```text
+Removed flows:approve from Gate; every grant on it was deleted with it.
+Declared 5 Intel interfaces in Gate.
+```
+
+A run that dropped nothing says so instead: `No declared function was dropped, so Gate deleted no
+grant.` And if the catalog cannot be read, `bootstrap` writes nothing at all rather than delete
+grants it would then be unable to name.
+
+⚠️ It never revokes a whole **interface**. One an older version declared stays declared in Gate:
+`bootstrap` writes only the handles it names, so an interface outside that list keeps its functions
+and its grants. That is harmless, and removing one is an act in Gate, by hand.
 
 ### 4. Copy the migrations out of `node_modules`
 
@@ -135,6 +152,19 @@ FAIL TOOL_SOURCE_ORIGINS is missing
 FAIL INTEL_SESSION_SECRET must contain at least 32 bytes
 ```
 
+It also compares the Gate interfaces **in both directions**. A function or a whole interface Gate
+carries that this version of Intel no longer declares is reported as a `NOTE`, never as a `FAIL`:
+nothing is broken by it, and a check one knows red stops being read. Each note names the surplus,
+why it went, and what to do about it:
+
+```text
+NOTE Gate carries flows:approve, which Intel does not declare — the approval node is gone (#73).
+NOTE Gate carries the interface knowledge (read, write), which Intel does not declare — the whole interface became `nodes` (#152, after #125).
+NOTE The next `intel bootstrap` removes a surplus function and every grant on it (#474). Take the grant away in Gate first if anybody should keep it.
+NOTE `bootstrap` never touches an interface Intel does not declare, so a surplus one stays until somebody removes it in Gate by hand — which takes its grants with it.
+OK Intel packages, configuration, and Gate interfaces are ready.
+```
+
 ⚠️ **`doctor` cannot see the Worker's secrets.** It answers about the shell it runs in, so it says
 nothing about whether the deployed Worker is configured. `GET /health` on the deployed Worker
 answers `{"status":"ok"}`; a Worker missing one of the five required variables answers
@@ -255,10 +285,10 @@ grants them.
 
 | Interface | Functions |
 |---|---|
-| `intel` | `use`, `admin` |
+| `intel` | `admin` |
 | `nodes` | `read`, `create`, `write`, `share` |
 | `flows` | `read`, `create`, `write`, `publish`, `run`, `share` |
-| `tools` | `read`, `test`, `execute`, `admin` |
+| `tools` | `read`, `test`, `execute` |
 | `mcp` | `connect` |
 
 A missing capability answers **`403`**, and the screen says a permission is missing.

package/dist/adapters/db/db-flows.js

@@ -607,6 +607,22 @@ export function createFlowRepository(deps) {
                 .all();
             return (result.results ?? []).map((row) => row.resource_id);
         },
+        // ⚠️ No actor and no `archived_at` condition, both on purpose (#509). The question is whether
+        // the row is still there at all, and archiving keeps it — a reference to something archived is
+        // not broken, it is waiting for a restore. The caller has already asked the visibility door for
+        // every one of these ids and reaches this only for the ones it answered nothing for.
+        //
+        // ⚠️ An empty list short-circuits rather than building `IN ()`, which SQLite refuses to parse.
+        async existingNodes(nodeIds) {
+            const wanted = [...new Set(nodeIds)];
+            if (wanted.length === 0)
+                return [];
+            const result = await deps.db
+                .prepare(`SELECT id FROM nodes WHERE id IN (${wanted.map(() => "?").join(", ")}) ORDER BY id`)
+                .bind(...wanted)
+                .all();
+            return (result.results ?? []).map((row) => row.id);
+        },
         async publishedCallees(flowId) {
             const row = await deps.db
                 .prepare(`SELECT flow.title AS title, version.graph_json AS graph_json

package/dist/auth/auth.js

@@ -218,28 +218,55 @@ export function createBrowserAuth(deps) {
                     ? `/auth/connect?returnTo=${encodeURIComponent(pending.returnTo)}`
                     : withConnectError(pending.returnTo));
             }
-            const tokens = await deps.oauth.exchange({
-                issuer: pending.kind === "connection-pending" ? pending.issuer : gateIssuer,
-                clientId: pending.clientId,
-                callbackUrl: requestUrl,
-                redirectUri,
-                resource: pending.kind === "connection-pending" ? pending.resource : deps.resource,
-                codeVerifier: pending.codeVerifier,
-                state: pending.state,
-            });
-            if (pending.kind === "connection-pending") {
-                await deps.portalTokens.write(pending.userId, {
-                    accessToken: tokens.accessToken,
-                    refreshToken: tokens.refreshToken ?? null,
-                    expiresAt: deps.now().getTime() + Math.max(30, tokens.expiresIn) * 1_000,
-                    issuer: pending.issuer,
+            // ⚠️ Everything below runs with the handoff READ, and that is the whole difference between
+            // this catch and the one on the route (#444): here a failure knows where the person was
+            // going, and for a connection handoff it still holds their parked Intel session. The route
+            // can only send somebody to a decided screen, so whatever can be answered here is answered
+            // here — the token exchange, the portal token write and the sealing of the new session all
+            // used to end as a bare 500 in JSON, in the middle of a sign-in.
+            try {
+                const tokens = await deps.oauth.exchange({
+                    issuer: pending.kind === "connection-pending" ? pending.issuer : gateIssuer,
                     clientId: pending.clientId,
-                    resource: pending.resource,
+                    callbackUrl: requestUrl,
+                    redirectUri,
+                    resource: pending.kind === "connection-pending" ? pending.resource : deps.resource,
+                    codeVerifier: pending.codeVerifier,
+                    state: pending.state,
                 });
-                return await restore(pending.user, pending.returnTo, pending.returnTo);
+                if (pending.kind === "connection-pending") {
+                    await deps.portalTokens.write(pending.userId, {
+                        accessToken: tokens.accessToken,
+                        refreshToken: tokens.refreshToken ?? null,
+                        expiresAt: deps.now().getTime() + Math.max(30, tokens.expiresIn) * 1_000,
+                        issuer: pending.issuer,
+                        clientId: pending.clientId,
+                        resource: pending.resource,
+                    });
+                    return await restore(pending.user, pending.returnTo, pending.returnTo);
+                }
+                const session = await userSession(pending.clientId, tokens);
+                return redirect(pending.returnTo, sessionCookie(await deps.sessions.seal(session), secure, (session.expiresAt - deps.now().getTime()) / 1_000));
+            }
+            catch (error) {
+                // The exception is the only thing that still holds the reason: what the reader gets is a
+                // fixed marker, and a marker names a KIND of failure, never its cause (#93).
+                reportUnexpectedError(error);
+                // `portal_sign_in_failed` is the marker `/auth/connect` already writes for exactly this
+                // situation, so nothing new is invented here and no screen has to learn a word. The Tools
+                // screen reads it as "the sign-in is broken", which is true of both handoffs — a Gate login
+                // that could not be exchanged is no more the reader's doing than a portal one.
+                if (pending.kind === "connection-pending") {
+                    // Every other way out of the callback puts the parked Intel session back, and so does
+                    // this one: the portal attempt must never cost somebody their Intel login.
+                    return await restore(pending.user, pending.returnTo, withConnectError(pending.returnTo, "portal_sign_in_failed"));
+                }
+                // A Gate login handoff parks nothing, so there is no session to put back — and the cookie
+                // is spent either way: its verifier belongs to an authorization code that has now been
+                // used. Clearing it is what makes the next attempt start a fresh one instead of replaying
+                // this one.
+                return redirect(withConnectError(pending.returnTo, "portal_sign_in_failed"), sessionCookie("", secure, 0));
             }
-            const session = await userSession(pending.clientId, tokens);
-            return redirect(pending.returnTo, sessionCookie(await deps.sessions.seal(session), secure, (session.expiresAt - deps.now().getTime()) / 1_000));
         },
         logout() {
             return redirect("/", sessionCookie("", secure, 0));

package/dist/build/build.js

@@ -13,6 +13,42 @@ const IntelConfig = z.strictObject({
 const Catalog = z.record(z.string(), z.string());
 const defaultTheme = `/* Generated by \`intel build\`. Intel defaults are active. */\n`;
 const defaultLogo = `export const customLogoUrl: string | null = null;\n`;
+// The `_headers` file of Workers Assets, written INTO THE BUILD OUTPUT (#543, sibling of
+// anchrd/gate#329).
+//
+// Without it every asset answers with the platform default `public, max-age=0, must-revalidate`,
+// and `public` lets a browser store an ERROR answer too. A `403` that appears once during setup is
+// then replayed on every navigation WITHOUT a request leaving the browser — invisible in the worker
+// log, in the Cloudflare Access log, in the firewall and in Cloudflare Analytics, while `curl`
+// against the same address keeps answering `200`. The second rule matters more here than in Gate:
+// the UI ships 1.9 MB of fingerprinted assets that are revalidated on every navigation today.
+//
+// ⚠️ `! Cache-Control` is not decoration, and the naive two-rule form from the ticket is WRONG.
+// A request matching several rules inherits ALL their headers, and a header named twice is joined
+// with a comma. Measured against `wrangler dev` 4.112.0 with both spellings side by side:
+//   without the detach   /assets/app.js → `no-store, public, max-age=31536000, immutable`
+//   with the detach      /assets/app.js → `public, max-age=31536000, immutable`
+// The joined value carries `no-store`, so those 1.9 MB would never be cached at all — the exact
+// opposite of the second rule's purpose.
+//
+// ⚠️ It has to be written into the TEMPORARY directory, before `replaceDir`. The next run's
+// `--emptyOutDir` applies to that directory, so a file placed into the live outDir afterwards
+// survives exactly one build. And `packages/ui/public/` is no way either: the `files` field of
+// @anchrd/intel-ui does not list `public`, so the file would look right in the repository and never
+// reach a customer.
+//
+// The three `cache-control` writes in this package do not contradict it: `auth/auth.ts` (redirect),
+// `http/http.ts` (zipResponse, attachment bytes) all answer `no-store` under `/auth/*` and `/api/*`,
+// which the assets layer never sees. Nothing serves an SPA route under `/assets/`, so the
+// `immutable` rule cannot swallow one.
+const headersFile = `# Generated by \`intel build\` — do not edit by hand.
+/*
+  Cache-Control: no-store
+
+/assets/*
+  ! Cache-Control
+  Cache-Control: public, max-age=31536000, immutable
+`;
 // Customer paths from intel.json are written into generated CSS and TypeScript comments. A path
 // containing `*/` or a newline would close the comment early, leaving broken output or — in
 // custom-logo.ts — customer-controlled text outside the comment and inside the UI bundle.
@@ -130,6 +166,9 @@ export function createBuild(deps) {
                     deps.log(`Error: Intel UI build exited with ${exitCode}.`);
                     return 1;
                 }
+                // Into the temporary directory, not into outDir — see `headersFile`. Vite has just emptied
+                // and refilled this directory; anything written here travels with the swap.
+                await deps.writeTextFile(`${temporaryOutDir}/_headers`, headersFile);
                 await deps.replaceDir(temporaryOutDir, location.outDir);
                 deps.log(`Intel UI built at ${location.outDir}.`);
                 return 0;

package/dist/bundle/bundle.js

@@ -336,6 +336,15 @@ export function createBundle(deps) {
     }
     async function tableCsv(nodeId) {
         const keys = await deps.repository.listVersionContentKeys(nodeId);
+        // ⚠️ `some` on an empty list is false, so no segments at all used to walk past the guard below
+        // and return `[].join("")` — the empty string, written into the zip as a file of zero bytes
+        // (#534). A table that has never been defined no longer reaches this function at all: it has no
+        // current version, and `plannedNode` marks it absent instead. An empty list HERE therefore means
+        // something else — a current version whose segments are gone — which is the loss the guard below
+        // already names, and it deserves the same answer rather than a silently empty file.
+        if (keys.length === 0) {
+            throw new IntelError(500, "content_missing", "Version content is missing");
+        }
         const segments = await Promise.all(keys.map(async (key) => await deps.content.get(key)));
         if (segments.some((segment) => segment === null)) {
             throw new IntelError(500, "content_missing", "Version content is missing");
@@ -351,6 +360,27 @@ export function createBundle(deps) {
             return body;
         };
     }
+    /**
+     * The bytes of an attachment version, or the same refusal the text path has always given (#560).
+     *
+     * ⚠️ A `contentKey` in the row and nothing behind it in R2 is data LOSS, and the attachment path
+     * was the one path that answered it with silence: `getStream` returned `null`, the zip got a file
+     * of zero bytes, and the export reported success. Whoever filed that zip away as a backup learns
+     * what it holds when they restore it — the one moment nothing can be done about it any more.
+     *
+     * This is deliberately NOT the `absence` answer. "Never uploaded" is a state of the node and
+     * travels in the manifest; "the object is gone" is a broken installation, and a bundle must not
+     * be able to describe it as if it were fine. Same distinction as `textLoader` and `tableCsv`.
+     */
+    function streamLoader(contentKey) {
+        return async () => {
+            const stream = await deps.content.getStream(contentKey);
+            if (stream === null) {
+                throw new IntelError(500, "content_missing", "Version content is missing");
+            }
+            return stream;
+        };
+    }
     function plannedNode(row, directory, used) {
         const { node, version } = row;
         const base = sanitizeName(node.title);
@@ -371,6 +401,30 @@ export function createBundle(deps) {
         }
         if (node.kind === "table") {
             const path = `${directory}${uniqueName(used, base, ".csv")}`;
+            // ⚠️ A table with no current version has never been given a header, and for a table the
+            // canonical content IS the CSV: there is nothing to write. It used to travel as a file of zero
+            // bytes, which the holder of the zip cannot tell apart from a table whose content was lost on
+            // the way — the very case `tableCsv` refuses as `content_missing`. One file, two meanings, no
+            // way to read which (#534).
+            //
+            // ⚠️ The entry STAYS in the manifest, and that is the half that matters: dropping it would
+            // take the node's title, its description and its place in the tree out of the backup too, and
+            // the import would recreate a subtree with a node missing from it without anybody noticing.
+            // What travels instead is the node without bytes, plus the word for what is not there.
+            if (version === null) {
+                return {
+                    manifest: {
+                        id: node.id,
+                        kind: "table",
+                        title: node.title,
+                        description: node.description,
+                        mediaType: TableMediaType,
+                        path,
+                        absence: "no-content",
+                    },
+                    content: { type: "absent" },
+                };
+            }
             return {
                 manifest: {
                     id: node.id,
@@ -387,19 +441,38 @@ export function createBundle(deps) {
             // Original bytes under the original name: an attachment's title IS its file name, so no
             // extension is imposed on it.
             const path = `${directory}${uniqueName(used, base, "")}`;
+            // ⚠️ An attachment with no current version was created and never uploaded to, and for an
+            // attachment the canonical content IS the bytes: there is nothing to write. It used to travel
+            // as a file of zero bytes — the same one file with two meanings the table branch above
+            // refuses, and here the second meaning is a lost R2 object (#560).
+            //
+            // ⚠️ The entry STAYS in the manifest for the same reason it does for a table: dropping it
+            // would take the node's title, its description and its place in the tree out of the backup,
+            // and the import would rebuild a subtree with a node missing from it and say nothing.
+            if (version === null) {
+                return {
+                    manifest: {
+                        id: node.id,
+                        kind: "attachment",
+                        title: node.title,
+                        description: node.description,
+                        mediaType: "application/octet-stream",
+                        path,
+                        absence: "no-content",
+                    },
+                    content: { type: "absent" },
+                };
+            }
             return {
                 manifest: {
                     id: node.id,
                     kind: "attachment",
                     title: node.title,
                     description: node.description,
-                    mediaType: version?.mediaType ?? "application/octet-stream",
+                    mediaType: version.mediaType ?? "application/octet-stream",
                     path,
                 },
-                content: {
-                    type: "stream",
-                    load: async () => version === null ? null : await deps.content.getStream(version.contentKey),
-                },
+                content: { type: "stream", load: streamLoader(version.contentKey) },
             };
         }
         // ⚠️ A row of a kind this build no longer makes — an `agent` or a `board` written before #390
@@ -574,18 +647,25 @@ export function createBundle(deps) {
                     await writer.ready;
                     continue;
                 }
+                // Nothing is written for it — not even an empty file, which is the whole point (#534). The
+                // manifest carries the node and says why its path is unoccupied.
+                if (entry.content.type === "absent")
+                    continue;
                 if (entry.content.type === "text") {
                     await pushText(entry.manifest.path, await entry.content.load());
                     continue;
                 }
+                // ⚠️ No `null` branch here any more, and its removal is the repair (#560): it wrote a file
+                // of zero bytes for "the loader has nothing", which was true both for an attachment nobody
+                // ever uploaded to and for one whose object had left R2. The first is now `absent` above
+                // and never reaches this loop; the second throws out of `load()` and aborts the whole zip,
+                // which is what a backup that cannot be written is supposed to do.
+                //
+                // The loader runs BEFORE the entry is added, so a refusal leaves no half-opened file
+                // behind in the zip that nothing will ever terminate.
+                const stream = await entry.content.load();
                 const file = new ZipPassThrough(entry.manifest.path);
                 zip.add(file);
-                const stream = await entry.content.load();
-                if (stream === null) {
-                    file.push(new Uint8Array(0), true);
-                    await writer.ready;
-                    continue;
-                }
                 const reader = stream.getReader();
                 for (;;) {
                     const { done, value } = await reader.read();
@@ -648,7 +728,11 @@ export function createBundle(deps) {
             if (isFolder)
                 folderIdByPath.set(entry.path.endsWith("/") ? entry.path : `${entry.path}/`, newId);
             let body = null;
-            if (!isFolder) {
+            // ⚠️ An entry that declares an `absence` names a path with nothing at it ON PURPOSE, so the
+            // zip is complete rather than broken (#534). Without this the export written by this very
+            // build would refuse its own import — and the node it describes arrives the way it left: a
+            // table with a title, a place in the tree and no content.
+            if (!isFolder && entry.absence === undefined) {
                 const found = files.get(entry.path);
                 if (found === undefined) {
                     throw new IntelError(400, "import_bundle_incomplete", `The manifest names a file the zip does not carry: ${entry.path}`);
@@ -933,9 +1017,14 @@ export function createBundle(deps) {
                      */
                     throw new IntelError(400, "import_kind_parked", `Bundle entry “${entry.path}” is a ${entry.kind}, and ${entry.kind}s are not part of this installation any more (anchrd/intel#385). The bundle was exported from a version that still had them; the code is on the branch parked/agents-and-board. Remove the entry from the bundle to import the rest.`);
                 }
-                else if (entry.kind === "attachment") {
-                    const bytes = entry.body ?? new Uint8Array(0);
-                    version = versionRowFor(entry, bytes, entry.mediaType ?? "application/octet-stream", await deps.hash(bytes), null);
+                else if (entry.kind === "attachment" && entry.body !== null) {
+                    // ⚠️ `entry.body === null` reaches here only for a manifest entry that declared an
+                    // absence — a naked folder always has the bytes of the file it names. It used to be read
+                    // as `new Uint8Array(0)` and given a version of zero bytes, which is a DIFFERENT node
+                    // from the one that was exported: the export said "never uploaded to", and the import
+                    // would answer with an upload of nothing. No version is what came out of that
+                    // installation and no version is what goes back in (#560).
+                    version = versionRowFor(entry, entry.body, entry.mediaType ?? "application/octet-stream", await deps.hash(entry.body), null);
                 }
                 if (version !== null)
                     versions.push(version);

package/dist/cli/cli.js

@@ -1,38 +1,81 @@
 import { createBuild } from "../build/build.js";
 import { createPrepare } from "../prepare/prepare.js";
 const interfaces = [
-    { handle: "intel", functions: ["use", "admin"] },
+    // ⚠️ No `use`. Nothing asked it (#475): every door in Intel asks a concrete capability —
+    // `nodes:read`, `flows:run`, `mcp:connect` — and a coarse "may use Intel at all" beside them is a
+    // permission an operator sets and nothing consults. Worse than useless: somebody granted only
+    // `intel:use` gets the empty screen the README warns about and reads it as a defect.
+    // `admin` stays and is the opposite case — it is the one way into a tree that carries no grant
+    // yet (ADR-0004 §6), read in ten places.
+    { handle: "intel", functions: ["admin"] },
     // ⚠️ `nodes`, not `knowledge` — and the rename cost something, which is why it needed its own
     // ticket (#152) five months after #125 renamed everything else. This handle is only half Intel's:
-    // `bootstrap` DECLARES it in Gate and deliberately changes no grant, so to Gate a renamed handle
-    // is a NEW one. Every grant on the old name keeps pointing at the old name, and everybody loses
-    // access at once, silently, until an operator hands the permissions out again.
+    // `bootstrap` DECLARES it in Gate and touches no grant on an interface it does not name, so to
+    // Gate a renamed handle is a NEW one. Every grant on the old name keeps pointing at the old name,
+    // and everybody loses access at once, silently, until an operator hands the permissions out again.
     //
     // It was done in the one window where that is free: the installation on anchrd.sh was being
     // rebuilt anyway (#385, anchrd/core#93) and there is no other. Doing it later would mean doing it
     // to somebody.
     //
-    // ⚠️ The old `knowledge` interface stays declared in Gate — bootstrap declares, it never revokes.
-    // It is a harmless leftover on installations that have it, and nothing in Intel asks about it any
-    // more; removing it is an act in Gate, by hand, when somebody is sure nothing else uses it.
+    // ⚠️ The old `knowledge` interface stays declared in Gate — bootstrap declares only the handles in
+    // this list and never revokes a whole INTERFACE. It is a harmless leftover on installations that
+    // have it, and nothing in Intel asks about it any more; removing it is an act in Gate, by hand,
+    // when somebody is sure nothing else uses it.
     { handle: "nodes", functions: ["read", "create", "write", "share"] },
     // ⚠️ No `approve`. The approval node is gone (#73), and this list is what Intel declares to Gate:
-    // a function nobody asks about is a permission an operator has to decide on for no reason. An
-    // installation that already granted it keeps a harmless leftover — bootstrap declares, it does
-    // not revoke.
+    // a function nobody asks about is a permission an operator has to decide on for no reason.
+    //
+    // ⚠️ Dropping a FUNCTION from a still-declared interface is not the harmless leftover the two
+    // blocks around this one describe (#474). `gate.set` is `PUT /api/v1/service/interfaces/:handle`,
+    // an upsert that REPLACES the function list, and in the same batch Gate runs `obsoleteGrants` —
+    // `DELETE FROM grants WHERE interface_id = ? AND function NOT IN (…)`. Gate holds that down with
+    // a test of its own (`service-interfaces.int.ts`, "scoped set/remove per App-Key und entfernt
+    // Grants gestrichener Funktionen"), and it is right to: catalog and grants are one change against
+    // Gate's own reasoning above `obsoleteGrants`. So an installation that granted `approve` does
+    // NOT keep it — the next bootstrap deletes every role assignment on it. That is why bootstrap
+    // reads the current list before it writes and names what it takes away.
     {
         handle: "flows",
         functions: ["read", "create", "write", "publish", "run", "share"],
     },
-    { handle: "tools", functions: ["read", "test", "execute", "admin"] },
-    // ⚠️ `agents:run` is deliberately NOT here any more (#390). `bootstrap` declares, it never
-    // revokes, so an installation that has the interface keeps it as a harmless leftover — but a new
-    // one is not asked to decide about a permission nothing reads.
+    // ⚠️ No `admin`. Nothing asked it either (#475), and here the reason is architectural rather than
+    // an oversight: the Cloudflare MCP Portal owns which servers exist and who may reach each one, and
+    // Intel stores no tool permissions at all — the catalog is a live `tools/list` with the asking
+    // person's token. There is no administration of tools inside Intel for the function to guard, so
+    // it cannot grow a reader later without that boundary moving first.
+    { handle: "tools", functions: ["read", "test", "execute"] },
+    // ⚠️ `agents:run` is deliberately NOT here any more (#390). The whole `agents` handle left the
+    // list, and bootstrap writes only the handles it names, so an installation that has that
+    // interface keeps it and its grants as a harmless leftover — but a new one is not asked to decide
+    // about a permission nothing reads. ⚠️ This holds because a whole INTERFACE went; a single
+    // function taken out of a handle that is still listed here is deleted along with its grants, see
+    // the block above (#474).
     // `mcp:connect` means the same thing at every MCP service of this installation. A separate name
     // for the same thing forces the operator to check, service by service, which permission carries
     // portal access.
     { handle: "mcp", functions: ["connect"] },
 ];
+// What Intel used to declare and no longer does, keyed by handle for a whole interface and by
+// `handle:function` for a single function.
+//
+// ⚠️ It exists because "surplus: approve" is not actionable on its own (#466). An operator who reads
+// only the name has to decide whether somebody meant it, and the cheapest way out of that decision
+// is to leave it standing — which is how `approve` outlived #73 by months. The reason is the half
+// that turns the note into a decision instead of a puzzle, so a new retirement belongs in here in
+// the same pull request that takes its entry out of `interfaces` above.
+const retired = {
+    knowledge: "the whole interface became `nodes` (#152, after #125).",
+    agents: "the whole interface went when Agents left the surface (#390, #388).",
+    "flows:approve": "the approval node is gone (#73).",
+    "intel:use": "no door ever asked it; every one of them asks a concrete capability (#475).",
+    "tools:admin": "the portal owns tool administration, so Intel never had anything to guard (#475).",
+};
+// An unlisted surplus gets a sentence too. "no reason recorded" is an answer an operator can act on;
+// an empty dash reads as an omission and sends them looking for the missing half.
+function reason(key) {
+    return retired[key] ?? "no reason is recorded here, so read the history before removing it.";
+}
 const usage = `Usage: intel <prepare|bootstrap|build|doctor|reindex>
   intel prepare    Copy versioned D1 migrations to .intel/migrations
   intel bootstrap  Idempotently declare Intel interfaces in Gate
@@ -67,13 +110,41 @@ export function createCli(deps) {
             return fail("GATE_URL and GATE_SERVICE_KEY must be set.");
         }
         const gate = deps.createGateInterfaces(gateUrl, serviceKey);
-        for (const entry of interfaces)
+        // ⚠️ Read before writing, and refuse if the read fails. The current list is the only place the
+        // functions Gate is about to lose are named; `set` replaces it, and afterwards nothing can say
+        // which grants went with them (#474). A run that writes anyway takes permissions away and has
+        // nothing left to report — the old "No grants were changed." in exactly the shape that made it
+        // wrong. Bootstrap is idempotent, so refusing costs a second run.
+        let current;
+        try {
+            current = await within(gate.list());
+        }
+        catch {
+            return fail("Gate interfaces could not be read, so bootstrap cannot say which grants it would delete.");
+        }
+        let removed = 0;
+        for (const entry of interfaces) {
+            const declared = entry.functions;
+            const dropped = (current.find((row) => row.handle === entry.handle)?.functions ?? []).filter((fn) => !declared.includes(fn));
             await gate.set(entry.handle, [...entry.functions]);
-        deps.log(`Declared ${interfaces.length} Intel interfaces in Gate. No grants were changed.`);
+            // Logged per interface, right after its own write returned, so a run that fails halfway still
+            // named every deletion it actually caused.
+            if (dropped.length) {
+                removed += dropped.length;
+                const names = dropped.map((fn) => `${entry.handle}:${fn}`).join(", ");
+                deps.log(`Removed ${names} from Gate; every grant on ${dropped.length === 1 ? "it" : "them"} was deleted with it.`);
+            }
+        }
+        deps.log(`Declared ${interfaces.length} Intel interfaces in Gate.`);
+        if (!removed)
+            deps.log("No declared function was dropped, so Gate deleted no grant.");
         return 0;
     }
     async function doctor() {
         const failures = [];
+        // A surplus hinders nothing, so it is never a `FAIL`: a doctor one knows red is a doctor nobody
+        // reads, and then the next real failure goes with it (#466).
+        const notes = [];
         const gateUrl = envValue("GATE_URL");
         const intelUrl = envValue("INTEL_URL");
         const serviceKey = envValue("GATE_SERVICE_KEY") ?? envValue("GATE_KEY");
@@ -106,17 +177,44 @@ export function createCli(deps) {
         if (gateUrl && serviceKey) {
             try {
                 const current = await within(deps.createGateInterfaces(gateUrl, serviceKey).list());
+                let surplusFunction = false;
                 for (const expected of interfaces) {
                     const actual = current.find((entry) => entry.handle === expected.handle);
                     const missing = expected.functions.filter((fn) => !actual?.functions.includes(fn));
                     if (missing.length)
                         failures.push(`Gate interface ${expected.handle} misses ${missing}`);
+                    const declared = expected.functions;
+                    for (const fn of actual?.functions ?? []) {
+                        if (declared.includes(fn))
+                            continue;
+                        surplusFunction = true;
+                        notes.push(`Gate carries ${expected.handle}:${fn}, which Intel does not declare — ${reason(`${expected.handle}:${fn}`)}`);
+                    }
+                }
+                // ⚠️ The other direction, and it is the half a loop over `interfaces` can never reach: a
+                // handle Intel stopped declaring appears in no expectation, so it is never looked up. The
+                // comparison runs both ways or it does not run (#466).
+                const declaredHandles = interfaces.map((entry) => entry.handle);
+                const surplusHandles = current.filter((row) => !declaredHandles.includes(row.handle));
+                for (const row of surplusHandles) {
+                    notes.push(`Gate carries the interface ${row.handle} (${row.functions.join(", ")}), which Intel does not declare — ${reason(row.handle)}`);
+                }
+                // What to do about it, once per kind — because the two kinds need opposite acts. A surplus
+                // FUNCTION on a still-declared handle disappears by itself on the next `bootstrap`, grants
+                // and all (#474); a surplus HANDLE is never written and therefore never goes away on its own.
+                if (surplusFunction) {
+                    notes.push("The next `intel bootstrap` removes a surplus function and every grant on it (#474). Take the grant away in Gate first if anybody should keep it.");
+                }
+                if (surplusHandles.length) {
+                    notes.push("`bootstrap` never touches an interface Intel does not declare, so a surplus one stays until somebody removes it in Gate by hand — which takes its grants with it.");
                 }
             }
             catch {
                 failures.push("Gate interface check failed");
             }
         }
+        for (const note of notes)
+            deps.log(`NOTE ${note}`);
         if (failures.length) {
             for (const failure of failures)
                 deps.log(`FAIL ${failure}`);

package/dist/flows/flows.js

@@ -1,4 +1,5 @@
 import { flowNodeLayer } from "@anchrd/intel-contract/flow";
+import { requireFutureExpiry } from "../shared/grant-expiry/grant-expiry.js";
 import { IntelError } from "../shared/intel-error/intel-error.js";
 import { plainTitle } from "../shared/plain-title/plain-title.js";
 function invalid(detail) {
@@ -112,9 +113,22 @@ function toolStepDetail(missing) {
 }
 export function compileFlow(graph) {
     const nodes = new Map();
+    // ⚠️ A refusal names a node the way the canvas does — by its label — because the id appears
+    // nowhere on screen. `Node n-doc is a link and must be attached to a step` sent an author looking
+    // for a string the editor never draws, and the way to the cause led through the contract schema
+    // instead of through the sentence (#508). The id stays beside it: a graph arrives over MCP as
+    // readily as from the canvas, and there the id is what the caller holds.
+    //
+    // ⚠️ It stands ABOVE the loop that fills the map on purpose, so the duplicate-id refusal reaches
+    // it too — that one names the node the map already holds, which is the FIRST of the two. An id
+    // nothing knows falls back to the bare id, which is what the dangling-edge case wants anyway.
+    const named = (id) => {
+        const node = nodes.get(id);
+        return node ? `"${node.label}" (${id})` : id;
+    };
     for (const node of graph.nodes) {
         if (nodes.has(node.id))
-            invalid(`Duplicate node ID: ${node.id}`);
+            invalid(`Duplicate node ID: ${named(node.id)}`);
         nodes.set(node.id, node);
     }
     // ⚠️ Every arity rule below counts flow edges only. A context edge says "this belongs to that
@@ -137,7 +151,7 @@ export function compileFlow(graph) {
             // One holder per attached node: two steps claiming the same material would make "what does
             // this step work with" answerable two ways, and the second answer would never be shown.
             if (attachedTo.has(edge.target))
-                invalid(`Node ${edge.target} is already attached to ${attachedTo.get(edge.target)}`);
+                invalid(`Node ${named(edge.target)} is already attached to ${named(attachedTo.get(edge.target) ?? "")}`);
             attachedTo.set(edge.target, edge.source);
             attachments.set(edge.source, [...(attachments.get(edge.source) ?? []), edge]);
             continue;
@@ -168,44 +182,44 @@ export function compileFlow(graph) {
         // Before this, a link could stand in the chain — which is how a start with an attachment once
         // began its run at the attachment (#37).
         if (layer === "link" && holderId === undefined) {
-            invalid(`Node ${node.id} is a link and must be attached to a step`);
+            invalid(`Node ${named(node.id)} is a link and must be attached to a step`);
         }
         if (layer !== "link" && holderId !== undefined) {
-            invalid(`Node ${node.id} is not a link and cannot be attached to another node`);
+            invalid(`Node ${named(node.id)} is not a link and cannot be attached to another node`);
         }
         if (holderId !== undefined) {
             if (parents !== 0 || children.length !== 0) {
-                invalid(`Node ${node.id} is attached as context and cannot also be a step`);
+                invalid(`Node ${named(node.id)} is attached as context and cannot also be a step`);
             }
             const holder = nodes.get(holderId);
             // Only a step holds material. A marker carries nothing at all, and a `subflow` is a call: the
             // flow it names brings its own links, and lending it one from here would be steering another
             // flow from outside.
             if (holder && (flowNodeLayer[holder.kind] !== "step" || holder.kind === "subflow")) {
-                invalid(`Node ${node.id} can only be attached to an instruction or a condition`);
+                invalid(`Node ${named(node.id)} can only be attached to an instruction or a condition`);
             }
             continue;
         }
         if (node.kind === "trigger" && parents !== 0)
             invalid("The trigger cannot have an incoming edge");
         if (node.kind !== "trigger" && parents !== 1) {
-            invalid(`Node ${node.id} requires exactly one incoming edge`);
+            invalid(`Node ${named(node.id)} requires exactly one incoming edge`);
         }
         if (node.kind === "output" && children.length !== 0)
-            invalid(`Output ${node.id} must be terminal`);
+            invalid(`Output ${named(node.id)} must be terminal`);
         if (node.kind === "condition") {
             if (children.length < 2)
-                invalid(`Node ${node.id} requires at least two branches`);
+                invalid(`Node ${named(node.id)} requires at least two branches`);
             const handles = new Set(children.map((edge) => edge.sourceHandle));
             if (handles.has(null) || handles.size !== children.length) {
-                invalid(`Node ${node.id} requires unique branch handles`);
+                invalid(`Node ${named(node.id)} requires unique branch handles`);
             }
         }
         else if (node.kind !== "output") {
             if (children.length !== 1)
-                invalid(`Node ${node.id} requires exactly one outgoing edge`);
+                invalid(`Node ${named(node.id)} requires exactly one outgoing edge`);
             if (children[0]?.sourceHandle !== null)
-                invalid(`Node ${node.id} cannot define a branch handle`);
+                invalid(`Node ${named(node.id)} cannot define a branch handle`);
         }
     }
     const visited = new Set();
@@ -1187,6 +1201,7 @@ export function createFlows(deps) {
                     flowId: flow.id,
                     versionId: null,
                     nodes: [],
+                    invalidNodes: [],
                     hiddenNodes: 0,
                     servers: [],
                 };
@@ -1194,16 +1209,31 @@ export function createFlows(deps) {
             const version = await requireVersion(versionId, flow.id);
             const referenced = graphReferences(version.graph);
             // ⚠️ The same lookup a tree link passes through, not a second rule written for a list.
-            // What it hands back is named; the difference between what was asked for and what came back
-            // is a number, because a title is exactly what someone without access may not learn (#17,
-            // #19). Tool names are not filtered: they come from a graph this actor may already read, and
-            // whether the portal offers them is a question only their own token can answer.
+            // What it hands back is named; a title is exactly what someone without access may not learn
+            // (#17, #19). Tool names are not filtered: they come from a graph this actor may already
+            // read, and whether the portal offers them is a question only their own token can answer.
             const reachable = await reachableNodes(actor, referenced.nodes);
+            const named = new Set(reachable.map((reference) => reference.id));
+            const unreachable = referenced.nodes.filter((resourceId) => !named.has(resourceId));
+            // ⚠️ What is left over used to be ONE number, and the panel read it out as "you cannot see
+            // it" — a sentence about a permission, in front of a link that names nothing at all (#509).
+            // The two suggest opposite actions and only one of them helps: with a permission one asks for
+            // access, with a dead reference the step has to be replaced before the flow can run.
+            //
+            // ⚠️ The second question is asked ONLY about what the visibility door already refused, and it
+            // is asked without an actor because its answer does not depend on one. That is the narrowest
+            // shape this distinction can have — the alternative, a lookup that is kinder than the door it
+            // describes, is what #17 and #19 were sent back for. It is still a disclosure and it is a
+            // deliberate one (#492): for an id the caller wrote into this graph themselves, they learn
+            // whether the tree still holds a row for it.
+            const alive = new Set(await deps.repository.existingNodes(unreachable));
+            const invalidNodes = unreachable.filter((resourceId) => !alive.has(resourceId));
             return {
                 flowId: flow.id,
                 versionId: version.id,
                 nodes: reachable,
-                hiddenNodes: referenced.nodes.length - reachable.length,
+                invalidNodes,
+                hiddenNodes: unreachable.length - invalidNodes.length,
                 servers: referenced.servers,
             };
         },
@@ -1233,6 +1263,11 @@ export function createFlows(deps) {
                 if (replayed)
                     return await withShareWarnings(actor, flow, replayed, replayed.principal);
             }
+            // ⚠️ The same rule as on a node grant, in the same place and for the same two reasons (#442):
+            // in front of `setFlowGrant` so nothing that could never work is written, behind the replay so
+            // a retry with the same key still answers with the grant its first attempt made. The long
+            // form of the argument stands at the node grant in `nodes.ts`.
+            requireFutureExpiry(input.expiresAt, deps.now());
             const timestamp = deps.now().toISOString();
             const grant = await deps.repository.setFlowGrant({
                 grant: {

package/dist/flows/flows.types.d.ts

@@ -82,6 +82,21 @@ export interface FlowRepository {
         hidden: number;
     }>;
     nodeReferences(actor: FlowPrincipal, folderId: string): Promise<string[]>;
+    /**
+     * Which of these ids still have a row in the tree at all — archived or not, for anybody (#509).
+     *
+     * ⚠️ It takes NO actor, and that is the honest shape rather than an oversight: the answer does
+     * not depend on who is asking, so an `actor` parameter would suggest a narrowing that is not
+     * there. Its one caller has already asked `visibleNodes` and only reaches this for the ids that
+     * came back empty, so what it adds is a single bit about ids the caller sent us out of a graph
+     * they may already read.
+     *
+     * ⚠️ An ARCHIVED node counts as existing. Archiving is reversible — the row is still there and a
+     * restore brings the reference back — so calling it invalid would tell an author to replace a
+     * step that is about to work again. Only a purge takes the row (`DELETE FROM nodes`, #457), and
+     * only that is what "there is nothing here any more" means.
+     */
+    existingNodes(nodeIds: string[]): Promise<string[]>;
     publishedCallees(flowId: string): Promise<{
         title: string;
         calleeIds: string[];
@@ -228,6 +243,12 @@ export interface FlowDeps {
      * requirements list names it; and every tree link of every run is authorized by it, nested
      * calls included (ADR-0004 §4). A second lookup beside it is how a drawing or a message ends up
      * kinder than the door it describes — which is what #17 and #19 were sent back for.
+     *
+     * ⚠️ `existingNodes` on the repository is the ONE thing asked beside it, and it is the exception
+     * that shows the rule rather than a hole in it: it runs only on ids this door already refused, it
+     * takes no actor, and it can only ever make the answer HARSHER — "this names nothing" instead of
+     * "you cannot see it". Nothing about a node it does hold reaches the caller, so no drawing and no
+     * message becomes kinder. Adding a third would need the same three properties (#492, #509).
      */
     visibleNodes(actor: FlowActor, nodeId: string): Promise<Node | null>;
     toolSurfaceFingerprint(actor: FlowActor, server: string, allow: string[] | null): Promise<string | null>;

package/dist/intel/intel.js

@@ -97,7 +97,35 @@ export function createIntel(deps) {
                 return context.redirect("/tools?connectError=portal_sign_in_failed");
             }
         });
-        app.get("/auth/callback", async (context) => await browserAuth.callback(new URL(context.req.url), context.req.raw.headers));
+        // The other end of the same walk: `/auth/connect` starts it, `/auth/callback` finishes it, and
+        // a reader who lands in a white JSON page does not distinguish which of the two put them there
+        // (#444). Everything that reaches this catch has already lost its handoff — `callback` answers
+        // the paths that still know where the person wanted to go — so the destination here is a
+        // DECIDED one rather than a remembered one.
+        //
+        // ⚠️ `/tools` and not `/`: it is the only screen that reads `connectError` and turns it into a
+        // sentence (`portalAnswerOf`), and every code but the two about access lands on "the sign-in is
+        // broken" there — which is what happened. The root would take the reader somewhere that says
+        // nothing at all about the attempt they just made. Somebody who has no Intel session either is
+        // sent on to the login by the interface's own 401 handling, once, bounded by the sign-in loop
+        // guard (#118).
+        app.get("/auth/callback", async (context) => {
+            try {
+                return await browserAuth.callback(new URL(context.req.url), context.req.raw.headers);
+            }
+            catch (error) {
+                // ⚠️ The IntelError is logged here although `app.onError` deliberately does not log one:
+                // an expected refusal explains itself through its body, and this route no longer has a
+                // body. `oauth_session_invalid` is raised for two different situations — no readable
+                // handoff at all, and a Gate login handoff that ran out — and a deployment where EVERY
+                // callback fails (a rotated session key, a clock that drifted, a cookie the browser stopped
+                // sending) looks from the outside exactly like one person with a stale tab. Without this
+                // line nothing anywhere tells the two apart.
+                reportUnexpectedError(error);
+                const code = error instanceof IntelError ? error.code : "portal_sign_in_failed";
+                return context.redirect(`/tools?connectError=${encodeURIComponent(code)}`);
+            }
+        });
         app.post("/auth/logout", () => browserAuth.logout());
     }
     app.route("/api/v1", createHttp({

package/dist/nodes/nodes.js

@@ -1,5 +1,6 @@
 import { TableMediaType } from "@anchrd/intel-contract/table";
 import { encodeCsv, parseCsv } from "../shared/csv/csv.js";
+import { requireFutureExpiry } from "../shared/grant-expiry/grant-expiry.js";
 import { IntelError } from "../shared/intel-error/intel-error.js";
 import { plainTitle } from "../shared/plain-title/plain-title.js";
 import { documentLinkTargets } from "./document-links/document-links.js";
@@ -1025,6 +1026,20 @@ export function createNodes(deps) {
                     };
                 }
             }
+            /**
+             * ⚠️ Behind the replay and in front of `setGrant` — both halves matter (#442).
+             *
+             * In front of `setGrant` is the rule itself: nothing that could never work gets written, so
+             * no row, no idempotency key and no audit event. Every path that reaches the write passes
+             * here, including a replay whose grant was revoked in between and falls through.
+             *
+             * Behind the replay because otherwise this refusal would break the promise `IdempotencyKey`
+             * makes. A caller retries with the SAME key and the SAME body; if the retry arrives after the
+             * expiry the first attempt named, the value is no longer in the future — and the second call
+             * would be refused for a grant that is already written. The replay path writes nothing, so
+             * standing behind it costs the rule nothing and keeps the retry answering with what happened.
+             */
+            requireFutureExpiry(input.expiresAt, deps.now());
             const timestamp = deps.now().toISOString();
             const grant = await deps.repository.setGrant({
                 grant: {

package/dist/shared/grant-expiry/grant-expiry.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ⚠️ A grant whose expiry has already passed is refused, never written (#442).
+ *
+ * It would otherwise be created, answered with a `201`, and listed — while reaching nobody. The
+ * sharer reads the row as done; the grantee gets no notification and finds out days later, if at
+ * all. That is the failure mode this repository keeps meeting: something that looks like success,
+ * and the only feedback is the wrong one.
+ *
+ * ⚠️ The check cannot live in the Zod schema. That boundary knows nothing about `deps.now()`, and
+ * the rule is decided by the very clock that evaluates the grant afterwards — so it belongs in the
+ * application layer, where every surface passes through it. The `.describe()` on `expiresAt`
+ * documents the rule; this refuses it.
+ *
+ * ⚠️ Equal to `now` is refused too: a grant that expires this instant is spent before the answer
+ * reaches the caller.
+ *
+ * `null` is untouched and stays what it always meant — a grant that does not expire on its own.
+ */
+export declare function requireFutureExpiry(expiresAt: string | null, now: Date): void;

package/dist/shared/grant-expiry/grant-expiry.js

@@ -0,0 +1,26 @@
+import { IntelError } from "../intel-error/intel-error.js";
+/**
+ * ⚠️ A grant whose expiry has already passed is refused, never written (#442).
+ *
+ * It would otherwise be created, answered with a `201`, and listed — while reaching nobody. The
+ * sharer reads the row as done; the grantee gets no notification and finds out days later, if at
+ * all. That is the failure mode this repository keeps meeting: something that looks like success,
+ * and the only feedback is the wrong one.
+ *
+ * ⚠️ The check cannot live in the Zod schema. That boundary knows nothing about `deps.now()`, and
+ * the rule is decided by the very clock that evaluates the grant afterwards — so it belongs in the
+ * application layer, where every surface passes through it. The `.describe()` on `expiresAt`
+ * documents the rule; this refuses it.
+ *
+ * ⚠️ Equal to `now` is refused too: a grant that expires this instant is spent before the answer
+ * reaches the caller.
+ *
+ * `null` is untouched and stays what it always meant — a grant that does not expire on its own.
+ */
+export function requireFutureExpiry(expiresAt, now) {
+    if (expiresAt === null)
+        return;
+    if (Date.parse(expiresAt) > now.getTime())
+        return;
+    throw new IntelError(400, "grant_already_expired", "A grant's expiry has to lie in the future; pass null for one that does not expire on its own");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -42,8 +42,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@anchrd/gate-sdk": "^0.15.0",
-    "@anchrd/intel-contract": "^0.20.0",
+    "@anchrd/gate-sdk": "^0.19.0",
+    "@anchrd/intel-contract": "^0.21.0",
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "fflate": "^0.8.3",