@anchrd/intel-api 0.24.0 → 0.26.0

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,6 @@
 import { flowNodeLayer } from "@anchrd/intel-contract/flow";
+import { callersPhrase, namedOrCounted } from "../shared/callers/callers.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";
 function invalid(detail) {
@@ -110,11 +112,32 @@ function toolStepDetail(missing) {
         ? `You do not reach this tool server in the portal: ${missing.join(", ")}`
         : `You do not reach these tool servers in the portal: ${missing.join(", ")}`;
 }
+/**
+ * ⚠️ How every refusal on this file names a node: by the label the canvas draws, 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.
+ *
+ * ⚠️ One function rather than one spelling per call site (#551): the publish-time refusals name a
+ * node too, and two places building the same string by hand is how the two halves of one sentence
+ * drift while both keep looking right.
+ */
+function nodeName(node) {
+    return `"${node.label}" (${node.id})`;
+}
 export function compileFlow(graph) {
     const nodes = new Map();
+    // ⚠️ 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 ? nodeName(node) : 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 +160,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 +191,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();
@@ -300,14 +323,14 @@ function decodeCursor(cursor) {
     return { createdAt, id };
 }
 // ⚠️ Named where the reader may see it, counted where they may not — the same rule the folder's
-// refusal follows (`callersDetail` in nodes.ts): a refusal must not become a way of learning that a
-// flow one cannot see exists (ADR-0004 §3).
+// refusal follows, out of the same place (`callersPhrase`): a refusal must not become a way of
+// learning that a flow one cannot see exists (ADR-0004 §3).
+//
+// ⚠️ The SENTENCE stays its own, and that is deliberate (#593): the folder's says a grant cannot be
+// narrowed yet, this one says a flow cannot be deleted for good. Same facts, different consequence
+// — a single parameterised sentence would save a string and cost each refusal its reason.
 function callersDetail(callers) {
-    const named = callers.visible.map((title) => `“${title}”`).join(", ");
-    const rest = callers.hidden === 0
-        ? ""
-        : `${named ? " and " : ""}${callers.hidden} more flow${callers.hidden === 1 ? "" : "s"} you cannot see`;
-    return `Published flows still call this one: ${named}${rest}. Change or unpublish them first.`;
+    return `Published flows still call this one: ${callersPhrase(callers)}. Change or unpublish them first.`;
 }
 export function createFlows(deps) {
     async function requireFlow(actor, flowId) {
@@ -1187,6 +1210,7 @@ export function createFlows(deps) {
                     flowId: flow.id,
                     versionId: null,
                     nodes: [],
+                    invalidNodes: [],
                     hiddenNodes: 0,
                     servers: [],
                 };
@@ -1194,16 +1218,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 +1272,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: {
@@ -1337,9 +1381,13 @@ export function createFlows(deps) {
                 throw new IntelError(409, "flow_not_archived", "Only an archived flow can be deleted for good. Archive it first.");
             }
             // A published caller would break at RUN TIME, in front of somebody who did not order this.
+            // ⚠️ The callers travel as DATA beside the sentence (#593, the second half of #448): the
+            // archive shows this refusal, and a German or Spanish screen could otherwise do nothing but
+            // print the English one. The sentence stays for a model over MCP, which has nothing to
+            // formulate with.
             const callers = await deps.repository.flowCallers(actor, current.id);
             if (callers.visible.length || callers.hidden) {
-                throw new IntelError(409, "flow_in_use_by_flow", callersDetail(callers));
+                throw new IntelError(409, "flow_in_use_by_flow", callersDetail(callers), namedOrCounted(callers));
             }
             // ⚠️ The one thing a flow has that a node does not: its runs can be the PARENT of runs
             // belonging to other flows. Deleting them would take the record of who started those runs
@@ -1483,9 +1531,18 @@ export function createFlows(deps) {
             compileFlow(version.graph);
             const wanted = [...new Set(treeLinkNodes(version.graph).map(resourceIdOf))];
             const reachable = new Set((await reachableNodes(actor, wanted)).map((reference) => reference.id));
-            for (const resourceId of wanted) {
-                if (!reachable.has(resourceId)) {
-                    throw new IntelError(409, "flow_node_unavailable", `Node reference is unavailable: ${resourceId}`);
+            // ⚠️ Asked over the deduplicated resource ids and REFUSED over the nodes (#551). The resource
+            // id is what the ACL answers about, and it is also the one thing the author cannot look up:
+            // it stands in no place the editor draws, so `Node reference is unavailable: n-01H…` named
+            // the failure after the only participant nobody can find. The link node beside it carries the
+            // label on the canvas, so the refusal names that instead.
+            //
+            // ⚠️ Naming the label reveals nothing the ACL is keeping: it is the author's own text in
+            // their own graph, already on their screen — unlike the run-time refusal, which counts the
+            // documents rather than naming them because there the READER may not see them (#17, #19).
+            for (const node of treeLinkNodes(version.graph)) {
+                if (!reachable.has(resourceIdOf(node))) {
+                    throw new IntelError(409, "flow_node_unavailable", `Node ${nodeName(node)} names a document you cannot reach`);
                 }
             }
             for (const node of version.graph.nodes) {

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/http/http.js

@@ -8,7 +8,7 @@ import { Hono } from "hono";
 import { z } from "zod";
 import { authorizeBearer, bearer, permits, } from "../shared/gate-authorization/gate-authorization.js";
 import { IntelError } from "../shared/intel-error/intel-error.js";
-import { problemDetails as problem } from "../shared/problem-details/problem-details.js";
+import { intelProblem, problemDetails as problem, } from "../shared/problem-details/problem-details.js";
 import { reportUnexpectedError } from "../shared/report-unexpected-error/report-unexpected-error.js";
 // A query string is a door to the outside like a body is, so what arrives through it is closed
 // rather than tolerated: `z.strictObject` refuses an unknown field, and this is that refusal for the
@@ -94,7 +94,7 @@ export function createHttp(deps) {
     }
     app.onError((error, context) => {
         if (error instanceof IntelError) {
-            return context.json(problem(error.status, error.code, error.message), error.status);
+            return context.json(intelProblem(error), error.status);
         }
         if (error instanceof z.ZodError) {
             return context.json(problem(400, "invalid_request", "Request validation failed", z.prettifyError(error)), 400);
@@ -440,8 +440,28 @@ export function createHttp(deps) {
         const input = GetFlowInput.parse({ flowId: context.req.param("flowId") });
         return context.json(await deps.flows.get(asFlowActor(auth), input.flowId));
     });
-    // A single flow as the same bundle shape a node export makes: one entry plus the manifest
-    // (#136). `flows/read` like every other read of the graph.
+    /**
+     * A single flow as the same bundle shape a node export makes: one entry plus the manifest
+     * (#136). `flows/read` like every other read of the graph.
+     *
+     * ⚠️ Deliberately no `flow_export` tool beside it, and the reason is NOT the one `node_export`
+     * carries (#436). There the memory argument decides — a subtree's zip would have to fit in Worker
+     * memory twice — and a flow bundle is one entry plus the manifest, so that argument does not
+     * reach here.
+     *
+     * What decides here is that the manifest of ONE entry answers nothing MCP does not already
+     * answer. `node_export` is worth a tool because its manifest is the PLAN of a subtree: every
+     * readable entry with its path, kind and media type, which is the map for fetching each one. For
+     * a single flow that map has one row, whose id the caller already holds — and the substance, the
+     * graph, is `flow_version_get` and `flow_graph`, with the record itself in `flow_get`. A tool
+     * whose whole answer is two other tools' answers costs bytes in every `tools/list` and makes the
+     * other names less reliable as a guide, which `packages/api/CLAUDE.md` treats as the cost it is.
+     *
+     * ⚠️ This is not the case `.claude/rules/destructive.md` warns about — "a way only the surface
+     * has is a way an agent works around". Nothing about a flow is unreachable over MCP; only the zip
+     * CONTAINER is HTTP-only, exactly as it is for nodes. `mcp.e2e.ts` pins that this exception is
+     * named rather than merely absent.
+     */
     app.get("/flows/:flowId/export", async (context) => {
         const auth = requireCapability(context, "flows", "read");
         const input = GetFlowInput.parse({ flowId: context.req.param("flowId") });

package/dist/intel/intel.js

@@ -3,7 +3,7 @@ import { createHttp } from "../http/http.js";
 import { handleMcp } from "../mcp/mcp.js";
 import { authorize, authorizeBearer, bearer, } from "../shared/gate-authorization/gate-authorization.js";
 import { IntelError } from "../shared/intel-error/intel-error.js";
-import { problemDetails } from "../shared/problem-details/problem-details.js";
+import { intelProblem, problemDetails } from "../shared/problem-details/problem-details.js";
 import { reportUnexpectedError } from "../shared/report-unexpected-error/report-unexpected-error.js";
 export function createIntel(deps) {
     const baseUrl = deps.baseUrl.replace(/\/+$/, "");
@@ -16,7 +16,7 @@ export function createIntel(deps) {
     const app = new Hono();
     app.onError((error, context) => {
         if (error instanceof IntelError) {
-            return context.json(problemDetails(error.status, error.code, error.message), error.status);
+            return context.json(intelProblem(error), error.status);
         }
         // An IntelError is an expected refusal and explains itself; the unknown exception must leave a
         // trace, or the 500 is undiagnosable — the worker answered, so the platform records no
@@ -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({