@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/dist/modules/tool-manuals/tool-manuals.service.js

@@ -1,4 +1,7 @@
 import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { logger } from '../../shared/logging.js';
+const log = logger('tool-manuals');
 import fs from 'node:fs/promises';
 import { parse as parseYaml } from 'yaml';
 import '@utcp/http'; // side effect: register the 'http' call-template type (http + inline sub-manuals)
@@ -7,23 +10,18 @@ import '@utcp/mcp'; // side effect: register the 'mcp' call-template type (mcp `
 // executor is removed again, so this process cannot dispatch a shell command.
 import { containsCliCallTemplate } from './utcp-cli-parse-only.js';
 import { UtcpManualSerializer, CallTemplateSerializer, DefaultVariableSubstitutor, } from '@utcp/sdk';
-import { DEFAULT_BRANCH, PLUGINS_DIR, PLUGIN_MANIFEST_FILE, PLUGIN_MCP_FILE, } from '@bevel-software/platform-shared';
+import { DEFAULT_BRANCH, PLUGINS_DIR, } from '@bevel-software/platform-shared';
 import { descriptorsFromMcpJson } from './mcp-json-discovery.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import { assertSafeFetchUrl } from '../../shared/ssrf.js';
+import { redactSecret } from '../../shared/redact-secret.js';
+import { printable } from '../../shared/printable.js';
 import { RESERVED_VARIABLE_NAMES, findReservedVariableRef } from '../../shared/variable-refs.js';
 import { extractFrontmatter, resolveDeclaredId, isValidId, dedupeById } from '../../shared/frontmatter-id.js';
-import { walkFiles } from '../../shared/fs-walk.js';
 import { TtlCache } from '../../shared/ttl-cache.js';
 import { utcpNamespacePrefix, utcpNamespacedKey, MCP_OAUTH_VAR, INTERNAL_MANUAL_NAME, } from '../../shared/utcp-namespace.js';
-import { EXTERNAL_KB_MANUAL_NAME, } from './tool-manuals.contract.js';
+import { EXTERNAL_KB_MANUAL_NAME, MAX_CAPABILITIES, } from './tool-manuals.contract.js';
 const CACHE_TTL_MS = 60_000;
-/**
- * How many embedded tools a manual may advertise on the tool page. A `.tool` is
- * author-written, so its `tools` array is unbounded input; the page renders one
- * bullet per entry, and a thousand of them is a broken page, not a useful one.
- */
-const MAX_CAPABILITIES = 100;
 /**
  * UTCP namespaces a user `.tool` may NOT claim: they belong to built-in manuals
  * whose loopback creds are pre-seeded on the agent's code-mode client (the
@@ -46,15 +44,93 @@ const RESERVED_TOOL_NAMESPACES = [INTERNAL_MANUAL_NAME, EXTERNAL_KB_MANUAL_NAME]
  * reference grammar live in `shared/variable-refs.ts` — one definition for
  * every boundary that classifies references.
  */
-/** Throw if any string in the `.tool` document references a reserved variable. */
-function assertNoReservedVariableRefs(doc, name) {
+/**
+ * Throw if any string in the `.tool` document references a reserved variable.
+ *
+ * `ref` is named because it is OURS — one of `RESERVED_VARIABLE_NAMES`, matched
+ * from a fixed list rather than copied out of the file. That is the line every
+ * refusal here holds: see {@link describeManualFault}.
+ */
+function assertNoReservedVariableRefs(doc) {
     const ref = findReservedVariableRef(doc);
     if (ref !== null) {
-        throw new Error(`\`.tool\` "${name}" references the reserved variable "${ref}" — ` +
+        throw new Error(`this \`.tool\` references the reserved variable "${ref}" — ` +
             'API_URL and CONNECTION_KEY (bare or namespaced, e.g. `<namespace>_CONNECTION_KEY`) ' +
             'are seeded by the platform for its own manuals and may not appear anywhere in a `.tool`.');
     }
 }
+/**
+ * How much of a validation message may reach a listing. Long enough for every
+ * sentence the normalizer writes; short enough that a message which interpolated
+ * a chunk of the file (`unknown \`.tool\` type: <whatever was written there>`)
+ * cannot smuggle a pasted credential out one character at a time.
+ */
+const MAX_REASON_LENGTH = 300;
+/**
+ * Why one `.tool` was refused, in a form safe to hand an agent, a browser and a
+ * log — the `reason` of an {@link InvalidToolManual}.
+ *
+ * This is the LAST of two defences, not the only one. The first is upstream and
+ * structural, and it is the one that carries the guarantee:
+ *
+ *   A REASON REPEATS NOTHING THE FILE SAID.
+ *
+ * Every refusal this module writes locates the fault — a field name we chose
+ * (`` `id` ``, `` `healthCheck.url` ``), an ordinal (`` `variables[2].scope` ``,
+ * `` `headers` entry 3 of 4 ``) — and states the rule. It never interpolates
+ * what was written there, and that includes text which passed a check: a name
+ * matching `[A-Za-z0-9_]+` is a legal identifier, not a string we may repeat,
+ * and a token spelled with underscores matches it. The only author-derived
+ * strings named anywhere are ones matched against a FIXED list of ours (a
+ * reserved variable, a reserved namespace), where saying which one was hit
+ * teaches nothing the platform did not already publish.
+ *
+ * It has to be that way round — no scrub can recognise an arbitrary
+ * author-chosen string as a credential, so a message that interpolates one
+ * cannot be made safe after the fact. What remains for this function is the
+ * text the process does NOT author: the YAML parser's, which quotes the file at
+ * its fault.
+ *
+ * Two things happen here, and both are about NOT echoing the file back.
+ *
+ * 1. A `YAMLParseError`'s `message` ends with a SOURCE SNIPPET: the offending
+ *    lines, verbatim, under a caret. A `.tool` is content an author may have
+ *    pasted a literal token into (`Authorization: Bearer <a real key>`), and
+ *    the line that fails to parse is as likely to be that one as any other.
+ *    So only the message's first line survives — the parser's own prose — and
+ *    the location is re-stated from `linePos`, which is numbers, not text.
+ * 2. Everything is then run through `redactSecret` and capped. The normalizer's
+ *    own messages quote a url on an SSRF refusal, and a url can carry
+ *    `user:pass@host` or a presigned query; that is precisely what the shared
+ *    scrub takes out, and reusing it is what keeps one definition of "this must
+ *    not reach a log" for the whole backend.
+ *
+ * What remains of the parser's prose still interpolates the odd token (`Missing
+ * , between flow map items`, `Unexpected , in flow collection`) — a structural
+ * character or a token type, never a value line. That is the point of the cut:
+ * the fault is described, the file is not quoted.
+ */
+export function describeManualFault(err) {
+    const raw = err instanceof Error ? err.message : String(err);
+    // `linePos` is the `yaml` package's own location, on the error object — the
+    // authority for WHERE, so the snippet never has to be read to find out.
+    const pos = err?.linePos?.[0];
+    // The prose, snippet dropped. `yaml` appends ` at line N, column M:` to it as
+    // the snippet's header; drop that too, since the location is restated below
+    // in a form that does not depend on the parser's phrasing.
+    const prose = raw.split('\n')[0].replace(/ at line \d+, column \d+:?$/, '').trim();
+    const located = pos ? `${prose} (line ${pos.line}, column ${pos.col})` : prose;
+    const scrubbed = redactSecret(located);
+    return scrubbed.length > MAX_REASON_LENGTH ? `${scrubbed.slice(0, MAX_REASON_LENGTH - 1)}…` : scrubbed;
+}
+/**
+ * The empty answer — a workspace that isn't there yet, or a caller who may read
+ * nothing. A FUNCTION, not a shared constant: the arrays in a scan result are
+ * handed to decoration passes and to the cache, and a single frozen-by-
+ * convention instance is one push away from every empty scan in the process
+ * inheriting another's contents.
+ */
+const emptyScan = () => ({ manuals: [], invalid: [] });
 const manualSerializer = new UtcpManualSerializer();
 const callTemplateSerializer = new CallTemplateSerializer();
 // `findRequiredVariables` is a pure walk — one shared instance is fine.
@@ -70,12 +146,40 @@ export class ToolManualService {
     workspaceService;
     accessControl;
     kbDirName;
+    disk;
+    source;
     cache;
     mcpAuthDiscovery;
-    constructor(workspaceService, accessControl, kbDirName, now = Date.now) {
+    /**
+     * The refused set as it was last written to the log, so the warnings are
+     * logged ONCE PER CHANGE rather than once per scan. A broken `.tool` sits
+     * there until someone fixes it, and the catalog is re-scanned every minute on
+     * every surface — repeating the same three lines forever buries the scan that
+     * actually changed something. `null` until the first scan, so the first state
+     * is always reported.
+     */
+    loggedInvalid = null;
+    /**
+     * The scan currently running, shared by everyone who asks while it runs.
+     *
+     * The TTL cache only holds a value once the scan RETURNS, so without this
+     * every caller arriving during the walk starts its own — and a listing that
+     * wants both halves of the catalog is exactly such a pair, as is a page that
+     * fires two requests. Sharing the promise makes one cold listing one disk
+     * walk, one MCP-discovery pass, and ONE snapshot for every reader of it.
+     * Cleared by `invalidate()` as well as on settle, so a caller arriving after
+     * a merge never inherits a scan that started on the tree it replaced — the
+     * same rule `TtlCache`'s generation token enforces for the cached value.
+     */
+    inFlightScan = null;
+    constructor(workspaceService, accessControl, kbDirName, disk, 
+    /** Where plugins (and their MCP servers) come from — the one discovery every catalog shares. */
+    source, now = Date.now) {
         this.workspaceService = workspaceService;
         this.accessControl = accessControl;
         this.kbDirName = kbDirName;
+        this.disk = disk;
+        this.source = source;
         this.cache = new TtlCache(CACHE_TTL_MS, now);
     }
     /**
@@ -89,12 +193,20 @@ export class ToolManualService {
     }
     invalidate() {
         this.cache.invalidate();
+        this.inFlightScan = null;
     }
     async listAccessible(userEmail) {
         return (await this.accessibleManuals(userEmail)).map(toSummary);
     }
+    async listAccessibleCatalog(userEmail) {
+        const { manuals, invalid } = await this.accessibleScan(userEmail);
+        return { tools: manuals.map(toSummary), invalid };
+    }
     async listAllSummaries() {
-        return (await this.scan()).map(toSummary);
+        return (await this.scan()).manuals.map(toSummary);
+    }
+    async catalogFingerprints(userEmail) {
+        return (await this.accessibleManuals(userEmail)).map(manualFingerprint);
     }
     async getDetail(userEmail, slug) {
         // Resolved through `accessibleManuals` rather than `scan()` + a canRead call
@@ -114,13 +226,44 @@ export class ToolManualService {
         const manuals = await this.accessibleManuals(userEmail);
         return manuals.filter((m) => m.remote === false).map((m) => ({ slug: m.slug, name: m.name, path: m.path }));
     }
+    async listDeclaredOnlyOnBranch(userEmail, branch) {
+        if (!branch || branch === DEFAULT_BRANCH)
+            return [];
+        // Only a draft this process already holds a clone of — the one the caller
+        // wrote the declaration on. `scanDisk` would otherwise BOOTSTRAP any branch
+        // name a caller sends, before the read gate below has had a say: a clone
+        // and a fetch per guessed, private or nonexistent branch. A declaration on
+        // a branch nobody has checked out here is nothing this answer can report.
+        if (!(await this.workspaceService.hasBootstrappedWorkspace(workspaceIdForBranch(branch))))
+            return [];
+        // Names and paths only — `scanDisk` never probes a server, so asking about
+        // a draft costs no network and registers no OAuth client for a declaration
+        // that may never be merged.
+        const onBranch = (await this.scanDisk(branch)).manuals;
+        if (onBranch.length === 0)
+            return [];
+        // Compared by NAMESPACE, the catalog's own identity (see the dedupe in
+        // `scanDisk`): a draft entry whose namespace the default branch already
+        // serves is an edit of a live tool, not a tool missing from the catalog.
+        const released = new Set((await this.scan()).manuals.map((m) => utcpNamespacePrefix(m.name)));
+        const pending = onBranch.filter((m) => !released.has(utcpNamespacePrefix(m.name)));
+        if (pending.length === 0)
+            return [];
+        // Read-gated on the BRANCH's workspace, where the declaration lives — the
+        // same default-deny rule as the catalog, so this can't reveal a draft file
+        // the caller could not open with `read_file`.
+        const allowed = await this.accessControl.canReadBatch(workspaceIdForBranch(branch), userEmail, pending.map((m) => m.path));
+        return pending
+            .filter((m) => allowed.get(m.path) === true)
+            .map((m) => ({ name: m.name, path: m.path, type: m.type }));
+    }
     async userScopedKeysForManual(manualName) {
         // The per-user (`user`-scoped) variables a manual declares, keyed the SAME
         // way the vault stores them — the UTCP-namespaced key (underscores in the
         // manual name doubled), so a readiness check reads the exact rows `resolve`
         // would. `oauth` lets the pre-check treat a not-yet-authorized sign-in as
         // still-missing.
-        const manual = (await this.scan()).find((m) => m.name === manualName);
+        const manual = (await this.scan()).manuals.find((m) => m.name === manualName);
         return (manual?.variables ?? [])
             .filter((v) => v.scope === 'user')
             .map((v) => ({
@@ -140,7 +283,7 @@ export class ToolManualService {
         // the LONGEST prefix so a manual `a` can't shadow `a_b` when both exist. (A
         // plain first-underscore split would mis-parse a snake_case manual name.)
         let best = null;
-        for (const m of await this.scan()) {
+        for (const m of (await this.scan()).manuals) {
             const prefix = utcpNamespacePrefix(m.name);
             if (effectiveKey.startsWith(prefix) && (!best || prefix.length > best.len)) {
                 best = { manual: m, varName: effectiveKey.slice(prefix.length), len: prefix.length };
@@ -180,7 +323,7 @@ export class ToolManualService {
                 callTemplate = callTemplateSerializer.validateDict(this.buildCallTemplateDict(m));
             }
             catch (err) {
-                console.warn(`[tool-manuals] no valid call template for "${m.path}": ${err instanceof Error ? err.message : String(err)}`);
+                log.warn(`no valid call template for "${m.path}": ${err instanceof Error ? err.message : String(err)}`);
             }
         }
         return { name: m.name, type: m.type, remote: m.remote, healthCheck: m.healthCheck, callTemplate };
@@ -199,13 +342,13 @@ export class ToolManualService {
             catch (err) {
                 // A `.tool` that produces an invalid call-template is dropped here — at
                 // the producing boundary — so the served list is always valid.
-                console.warn(`[tool-manuals] skipping "${m.path}": ${err instanceof Error ? err.message : String(err)}`);
+                log.warn(`skipping "${m.path}": ${err instanceof Error ? err.message : String(err)}`);
             }
         }
         return out;
     }
     async resolveInlineManual(userEmail, slug) {
-        const found = (await this.scan()).find((m) => m.slug === slug);
+        const found = (await this.scan()).manuals.find((m) => m.slug === slug);
         if (!found || found.type !== 'inline')
             return null;
         const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
@@ -323,27 +466,87 @@ export class ToolManualService {
         };
     }
     async accessibleManuals(userEmail) {
-        const manuals = await this.scan();
-        if (manuals.length === 0)
-            return [];
+        return (await this.accessibleScan(userEmail)).manuals;
+    }
+    /**
+     * The scan cut to what this caller may read — manuals AND refusals, through
+     * ONE `canReadBatch`. Both halves are paths in the same workspace judged by
+     * the same rule, and splitting them into two calls would pay a second
+     * round-trip to ask the same question.
+     */
+    async accessibleScan(userEmail) {
+        const { manuals, invalid } = await this.scan();
+        if (manuals.length === 0 && invalid.length === 0)
+            return emptyScan();
         const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
-        const allowed = await this.accessControl.canReadBatch(wsId, userEmail, manuals.map((m) => m.path));
-        // Fail closed: keep a manual only on an explicit `true` verdict (a missing
+        const allowed = await this.accessControl.canReadBatch(wsId, userEmail, [
+            ...new Set([...manuals.map((m) => m.path), ...invalid.map((i) => i.path)]),
+        ]);
+        // Fail closed: keep an entry only on an explicit `true` verdict (a missing
         // entry is treated as denied, matching the KB's default-deny read model).
-        return manuals.filter((m) => allowed.get(m.path) === true);
+        // A REFUSED file is gated the same way a listed one is: its path is a fact
+        // about the knowledge base, and "there is a broken tool at this path" is
+        // not something to tell someone who may not read that path.
+        return {
+            manuals: manuals.filter((m) => allowed.get(m.path) === true),
+            invalid: invalid.filter((i) => allowed.get(i.path) === true),
+        };
     }
     async scan() {
         const cached = this.cache.get();
         if (cached)
             return cached;
-        const manuals = await this.scanDisk();
+        // See `inFlightScan`: the cache is populated only when the walk finishes,
+        // so between the miss above and that moment, callers share this promise
+        // instead of each starting a walk of their own.
+        if (this.inFlightScan)
+            return this.inFlightScan;
+        const started = this.runScan().finally(() => {
+            // Only if it is still OURS: an `invalidate()` during the scan already
+            // cleared the field (and may have installed a newer scan), and this
+            // settle must not undo that.
+            if (this.inFlightScan === started)
+                this.inFlightScan = null;
+        });
+        this.inFlightScan = started;
+        return started;
+    }
+    async runScan() {
+        // See `TtlCache.begin`: taken before the read so an `invalidate()` that
+        // lands mid-scan discards this result instead of being overwritten by it.
+        const token = this.cache.begin();
+        const { manuals, invalid } = await this.scanDisk();
         await this.decorateMcpOAuth(manuals);
         // AFTER the oauth decoration, so an injected `${MCP_OAUTH}` header ref is
         // already declared and isn't re-surfaced as a bare admin key.
         for (const m of manuals)
             this.surfaceReferencedVariables(m);
-        this.cache.set(manuals);
-        return manuals;
+        const result = { manuals, invalid };
+        this.cache.set(result, token);
+        return result;
+    }
+    /**
+     * Say what the scan refused — once per CHANGE, not once per scan. Every
+     * surface re-scans on its own TTL, so a file that stays broken would
+     * otherwise repeat these lines in the log forever and drown the scan where
+     * something actually moved. A fixed file is worth a line too: the set going
+     * empty is the recovery, said out loud.
+     */
+    logInvalidOnChange(invalid) {
+        const signature = JSON.stringify(invalid);
+        if (signature === this.loggedInvalid)
+            return;
+        const first = this.loggedInvalid === null;
+        this.loggedInvalid = signature;
+        // Both halves are author-written — a KB filename and a parser's words about
+        // a KB file — so both go through `printable`: a newline in either would
+        // otherwise forge a second log line, and an escape sequence would paint the
+        // operator's terminal.
+        // (`printable` quotes what it escapes, so the path keeps its quotes here.)
+        for (const i of invalid)
+            log.warn(`skipping ${printable(i.path)}: ${printable(i.reason)}`);
+        if (invalid.length === 0 && !first)
+            log.info('every `.tool` in the catalog parses again.');
     }
     /**
      * Auto-surface every `${VAR}` a manual actually references, for ANY tool
@@ -481,7 +684,7 @@ export class ToolManualService {
                 }
                 catch (err) {
                     // Discovery must never break the catalog — the tool just stays bare.
-                    console.warn(`[tool-manuals] mcp auth discovery failed for "${m.path}": ${err instanceof Error ? err.message : String(err)}`);
+                    log.warn(`mcp auth discovery failed for "${m.path}": ${err instanceof Error ? err.message : String(err)}`);
                 }
             }),
         ]);
@@ -532,23 +735,36 @@ export class ToolManualService {
         catch (err) {
             // Never break the catalog — the sign-in just isn't ready yet.
             const msg = err instanceof Error ? err.message : String(err);
-            console.warn(`[tool-manuals] sign-in endpoint discovery failed for "${m.path}": ${msg}`);
+            log.warn(`sign-in endpoint discovery failed for "${m.path}": ${msg}`);
             m.setup = { kind: 'oauth-manual', reason: `sign-in endpoint discovery failed: ${msg}` };
         }
     }
-    async scanDisk() {
+    /**
+     * Parse every declaration on `branch`'s workspace — the default branch for
+     * the catalog, a draft for `listDeclaredOnlyOnBranch`. Pure disk: no
+     * discovery, no access filter; callers add what their surface needs.
+     *
+     * ONE FILE'S FAULT IS ONE FILE'S FAULT. Every per-manual step below is
+     * contained — read, parse, validate, and the namespace dedup — so the answer
+     * is always "here is every manual that parses, and here is what the rest got
+     * wrong". There is no path through this loop on which a single bad `.tool`
+     * costs the catalog a manual that is fine, and nothing is remembered between
+     * calls: a refusal lives only in the scan it came from, so a fixed file is a
+     * valid manual on the very next scan.
+     */
+    async scanDisk(branch = DEFAULT_BRANCH) {
         let wsId;
         try {
-            wsId = (await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH)).id;
+            wsId = (await this.workspaceService.getOrCreateForBranch(branch)).id;
         }
         catch {
-            return [];
+            return emptyScan();
         }
         const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
         // A `.tool` sits under `Plugins/`, beside the skills that use it.
         const files = [];
         const root = path.join(kbRoot, PLUGINS_DIR);
-        for (const rel of await walkFiles(root, (n) => n.toLowerCase().endsWith('.tool'))) {
+        for (const rel of await this.disk.walkFiles(root, (n) => n.toLowerCase().endsWith('.tool'))) {
             files.push({ abs: path.join(root, rel), rel: `${PLUGINS_DIR}/${rel}` });
         }
         // MCP servers come from each plugin's mcp.json — the AUTHORITATIVE source
@@ -556,49 +772,65 @@ export class ToolManualService {
         // shape. Listed BEFORE the `.tool` files: on a name collision (a legacy
         // mcp `.tool` the migration has not converted yet), the shared dedup keeps
         // the first occurrence, and the authoritative source must be the one kept.
+        // The plugins (and their mcp.json text) come from the configured source, so
+        // a dialect that expands servers from a registry lands here unchanged.
         const parsed = [];
-        let pluginFolders = [];
-        try {
-            pluginFolders = (await fs.readdir(root, { withFileTypes: true }))
-                .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
-                .map((e) => e.name)
-                .sort();
-        }
-        catch {
-            /* no Plugins/ root — nothing to scan */
-        }
-        for (const folder of pluginFolders) {
-            let mcpJson;
-            try {
-                mcpJson = await fs.readFile(path.join(root, folder, PLUGIN_MCP_FILE), 'utf-8');
-            }
-            catch {
-                continue; // no mcp.json is the common case, not an error
+        const discovered = await this.source.discover(kbRoot);
+        for (const plugin of discovered.plugins) {
+            if (plugin.mcpJsonText === null)
+                continue; // no servers is the common case, not an error
+            // One stamp for every server the file declares: the two texts together
+            // are the whole source of these descriptors, so any edit to either
+            // (a URL, a header, an added or dropped server, a `local: true` flip)
+            // moves every server's digest — which is correct, if slightly generous.
+            const from = sourceDigest(plugin.mcpJsonText + '\u0000' + (plugin.manifestText ?? ''));
+            for (const d of descriptorsFromMcpJson(plugin.relFolder, plugin.mcpJsonText, plugin.manifestText)) {
+                d.sourceRevision = from;
+                parsed.push(d);
             }
-            const pluginJson = await fs
-                .readFile(path.join(root, folder, PLUGIN_MANIFEST_FILE), 'utf-8')
-                .catch(() => null);
-            parsed.push(...descriptorsFromMcpJson(folder, mcpJson, pluginJson));
         }
+        const invalid = [];
         for (const f of files) {
             let content;
             try {
                 content = await fs.readFile(f.abs, 'utf-8');
             }
-            catch {
+            catch (err) {
+                // Not a malformed manual — a file the walk saw and the read could not
+                // open (deleted under us, a permission fault). Reported like one anyway:
+                // to the person looking for their tool, "it isn't here" needs a reason
+                // whichever step lost it.
+                //
+                // The CODE, not the message: an fs error quotes the absolute path it
+                // tried, which is this server's disk layout rather than anything about
+                // the knowledge base, and this string is handed to agents and browsers.
+                const code = err?.code;
+                invalid.push({
+                    path: f.rel,
+                    reason: `the file could not be read${code ? ` (${code})` : ''} — it may have just been moved or deleted.`,
+                });
                 continue;
             }
             let descriptor;
             try {
                 descriptor = normalizeToolManual(baseName(f.rel), f.rel, content);
             }
-            catch {
-                // A malformed `.tool` is skipped rather than breaking the catalog.
+            catch (err) {
+                // A malformed `.tool` is skipped rather than breaking the catalog —
+                // and NAMED, rather than vanishing. Skipping in silence is the same
+                // outage from where the author stands: the tool is gone from every
+                // listing, with nothing anywhere saying which file or why.
+                invalid.push({ path: f.rel, reason: describeManualFault(err) });
                 continue;
             }
             // The route slug IS the id (unique after dedup below, snake_case → URL-safe),
             // so the URL a user sees matches the tool's declared identity.
             descriptor.slug = descriptor.name;
+            // Stamped from the BYTES, here, before `decorateMcpOAuth` and
+            // `surfaceReferencedVariables` mutate the descriptor: those two derive
+            // from the network and from the file respectively, and a digest taken
+            // afterwards would move whenever an OAuth probe happened to fail.
+            descriptor.sourceRevision = sourceDigest(content);
             parsed.push(descriptor);
         }
         // The manual name (= its id) is the UTCP variable namespace secrets bind to, so
@@ -614,12 +846,65 @@ export class ToolManualService {
         // cannot contain a hyphen, but an mcp.json server name can, so the pair is
         // reachable — and the consequence is that two manuals share one set of
         // vault keys, with either able to resolve the other's secrets.
-        return dedupeById(parsed, (m) => utcpNamespacePrefix(m.name), (m, ns) => console.warn(`[tool-manuals] skipping "${m.path}": manual "${m.name}" resolves to the secret-variable ` +
-            `namespace "${ns}", which another manual already uses. Names differing only in \`-\` vs \`_\` ` +
-            'share one namespace — rename one of them.'));
+        const manuals = dedupeById(parsed, (m) => utcpNamespacePrefix(m.name), (m) => 
+        // A collision drops a manual from every surface just as surely as a parse
+        // error does, so it is reported the same way rather than only reaching a
+        // log that nobody browsing the catalog can see.
+        invalid.push({
+            path: m.path,
+            // Neither the manual's name nor the namespace it resolved to is
+            // repeated: both are the author's text put through a transform, and a
+            // reason carries none of it (see `describeManualFault`). `path` says
+            // which file, and the rule says what to look for in it.
+            reason: 'this manual resolves to a secret-variable namespace another manual already uses. ' +
+                'Names differing only in `-` vs `_` share one namespace — rename one of them.',
+        }));
+        // Sorted so the refused set is a stable VALUE: the change-detecting log
+        // below compares one scan against the last, and two orderings of the same
+        // three faults are not a change worth repeating.
+        invalid.sort((a, b) => a.path.localeCompare(b.path));
+        // Only the CATALOG's scan talks. `listDeclaredOnlyOnBranch` re-scans a
+        // draft workspace, and a draft's half-written `.tool` is not news about the
+        // served catalog — it would also flap the log every time an agent saves.
+        if (branch === DEFAULT_BRANCH)
+            this.logInvalidOnChange(invalid);
+        return { manuals, invalid };
     }
 }
 // --- helpers ------------------------------------------------------------------
+/**
+ * A short digest of the text a descriptor was parsed from. Truncated because
+ * this is only ever compared for equality, and 128 bits of it is far past what
+ * a per-workspace catalog could collide in.
+ */
+function sourceDigest(text) {
+    return createHash('sha256').update(text).digest('hex').slice(0, 32);
+}
+/**
+ * One manual's line in the catalog fingerprint: what makes it the tool it is,
+ * plus the digest of the file it came from.
+ *
+ * The named fields rather than the whole descriptor, deliberately: `setup` and
+ * `variables` carry OAuth auto-discovery results, which are re-probed on every
+ * scan and can differ between two scans of an unchanged file — hashing them
+ * would report a catalog change that no commit made. `sourceRevision` is what
+ * covers everything else the file says, so nothing is lost by leaving the
+ * decorated fields out.
+ */
+function manualFingerprint(m) {
+    return [
+        m.slug,
+        m.name,
+        m.path,
+        m.type,
+        m.remote === false ? 'local' : 'remote',
+        m.description ?? '',
+        m.sourceRevision ?? '',
+        // NUL-joined, like the skill lines this sits beside: no field can contain
+        // one, so two different manuals can never render the same line by having
+        // a separator inside one of their own fields.
+    ].join('\u0000');
+}
 /**
  * The one descriptor → summary projection, shared by every list surface
  * (`listAccessible`, `listAllSummaries`, and the summary half of `getDetail`).
@@ -663,7 +948,15 @@ function capabilitiesOf(m) {
     }
     return out;
 }
-function baseName(rel) {
+/**
+ * A `.tool` file's PROVISIONAL slug — its filename without the extension, which
+ * is what `normalizeToolManual` falls back to when the frontmatter names
+ * nothing. It is not the served id: `scanDisk` overwrites `slug` with the
+ * resolved manual `name` just below. Exported for the pending-tool surface,
+ * which parses a `.tool` read at a change request's branch and must feed the
+ * parser the same provisional value — and then resolve the slug the same way.
+ */
+export function baseName(rel) {
     const base = rel.slice(rel.lastIndexOf('/') + 1);
     return base.replace(/\.tool$/i, '');
 }
@@ -719,7 +1012,12 @@ export function normalizeToolManual(provisionalSlug, repoPath, content) {
     let name;
     if (explicitId) {
         if (!isValidId(explicitId)) {
-            throw new Error(`tool id "${explicitId}" must be lowercase snake_case (letters, digits, underscores)`);
+            // The rejected id is NOT quoted back — see `describeManualFault`: this
+            // message becomes an `invalid[].reason` on an agent transcript, a browser
+            // and a log, and `id` is a field an author can paste anything into,
+            // including the token they meant for a header. The field name plus the
+            // rule is what the author needs; the value is in front of them.
+            throw new Error('tool `id` must be lowercase snake_case (letters, digits, underscores)');
         }
         name = explicitId;
     }
@@ -730,12 +1028,13 @@ export function normalizeToolManual(provisionalSlug, repoPath, content) {
     // let it read the loopback creds seeded under that namespace on the agent's
     // code-mode client (internal token, connector creds, KB bearer).
     if (RESERVED_TOOL_NAMESPACES.includes(name.toLowerCase())) {
-        throw new Error(`tool namespace "${name}" is reserved for a built-in manual — choose a different \`id\`/\`name\` ` +
-            "(a `.tool` sharing a built-in namespace could read that manual's seeded credentials).");
+        throw new Error('the tool namespace this file resolves to is reserved for a built-in manual — ' +
+            "choose a different `id`/`name` (a `.tool` sharing a built-in namespace could read " +
+            "that manual's seeded credentials).");
     }
     // Any `.tool` content — url, headers, inline tool templates, notes — may not
     // reference the platform-seeded variables.
-    assertNoReservedVariableRefs(obj, name);
+    assertNoReservedVariableRefs(obj);
     // The non-stdio constituent of the union, by name: `.tool` parsing can
     // never produce a spawn spec, and the stdio side pins `remote: false`,
     // which this builder must stay free to set from the file's own `remote:`.
@@ -766,7 +1065,7 @@ export function normalizeToolManual(provisionalSlug, repoPath, content) {
     // catalog disagreeing with the file about what the platform will do.
     if (containsCliCallTemplate(obj)) {
         if (obj.remote === true) {
-            throw new Error(`\`.tool\` "${name}" declares \`remote: true\` but contains a \`cli\` call template — ` +
+            throw new Error('this `.tool` declares `remote: true` but contains a `cli` call template — ' +
                 'shell tools execute only in a local runtime (drop `remote: true`, or the `cli` template).');
         }
         descriptor.remote = false;
@@ -802,7 +1101,7 @@ export function normalizeToolManual(provisionalSlug, repoPath, content) {
         // Local-only (`remote: false`) `.tool`s are never fetched server-side, so
         // are exempt.
         if (descriptor.remote !== false) {
-            assertSafeManualFetchUrl(url, `\`.tool\` "${name}" url`);
+            assertSafeManualFetchUrl(url, '`url`');
         }
         if (obj.headers && typeof obj.headers === 'object' && !Array.isArray(obj.headers)) {
             descriptor.headers = obj.headers;
@@ -826,7 +1125,7 @@ export function normalizeToolManual(provisionalSlug, repoPath, content) {
     const declaredHeaders = type !== 'inline' && obj.headers && typeof obj.headers === 'object' && !Array.isArray(obj.headers)
         ? obj.headers
         : undefined;
-    const healthCheck = normalizeHealthCheck(obj.healthCheck, name, descriptor.remote, declaredHeaders);
+    const healthCheck = normalizeHealthCheck(obj.healthCheck, descriptor.remote, declaredHeaders);
     if (healthCheck)
         descriptor.healthCheck = healthCheck;
     return descriptor;
@@ -888,7 +1187,7 @@ function assertSafeManualFetchUrl(url, label) {
  * unattended on every save and re-check, so `POST` is refused outright instead
  * of being quietly downgraded.
  */
-function normalizeHealthCheck(raw, manualName, remote, manualHeaders) {
+function normalizeHealthCheck(raw, remote, manualHeaders) {
     if (raw === undefined || raw === null)
         return undefined;
     if (typeof raw !== 'object' || Array.isArray(raw))
@@ -898,7 +1197,7 @@ function normalizeHealthCheck(raw, manualName, remote, manualHeaders) {
     if (!url)
         throw new Error('`healthCheck` must have a `url`');
     if (remote !== false) {
-        assertSafeManualFetchUrl(url, `\`.tool\` "${manualName}" healthCheck.url`);
+        assertSafeManualFetchUrl(url, '`healthCheck.url`');
     }
     const check = { url };
     if (e.method !== undefined) {
@@ -932,9 +1231,16 @@ function normalizeHealthCheck(raw, manualName, remote, manualHeaders) {
  * what it is: a mistake in the `.tool` file.
  */
 function assertStringHeaders(headers, label) {
-    for (const [k, v] of Object.entries(headers)) {
+    // Located by POSITION, not by its key. A header name is text the author
+    // wrote, and a refusal reason carries none of that — see
+    // {@link describeManualFault}. The `.tool` has a handful of headers and the
+    // reader is looking at the file, so an ordinal finds the line as surely as
+    // the name would.
+    const entries = Object.entries(headers);
+    for (const [i, [, v]] of entries.entries()) {
         if (typeof v !== 'string') {
-            throw new Error(`\`${label}.${k}\` must be a string (quote it if it looks like a number)`);
+            throw new Error(`\`${label}\` entry ${i + 1} of ${entries.length} must have a string value ` +
+                '(quote it if it looks like a number)');
         }
     }
     return headers;
@@ -951,32 +1257,40 @@ function normalizeVariables(raw) {
     if (!Array.isArray(raw))
         throw new Error('`variables` must be an array');
     const seen = new Set();
-    return raw.map((entry) => {
+    return raw.map((entry, i) => {
         if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
-            throw new Error('each `variables` entry must be an object');
+            throw new Error(`\`variables[${i}]\` must be an object`);
         }
         const e = entry;
         const name = typeof e.name === 'string' ? e.name.trim() : '';
+        // EVERY refusal in this block is located by `variables[i]`, never by the
+        // name the entry declared — passing `[A-Za-z0-9_]+` makes a string a legal
+        // identifier, not a string this process may repeat. A token spelled with
+        // underscores passes that test, and the field an author mis-pastes a token
+        // into is not one we get to choose. See {@link describeManualFault}.
+        const at = `\`variables[${i}]`;
         if (!/^[A-Za-z0-9_]+$/.test(name)) {
-            throw new Error(`variable name "${name}" must match [A-Za-z0-9_]+`);
+            throw new Error(`${at}.name\` must match [A-Za-z0-9_]+`);
         }
         if (RESERVED_VARIABLE_NAMES.includes(name)) {
-            throw new Error(`variable name "${name}" is reserved for platform seeding and may not be declared by a \`.tool\``);
+            // `name` is one of OURS here — matched against a fixed list — so saying
+            // which reserved name was taken repeats nothing the file taught us.
+            throw new Error(`${at}.name\` is "${name}", which is reserved for platform seeding and may not be declared by a \`.tool\``);
         }
         if (seen.has(name))
-            throw new Error(`duplicate variable "${name}"`);
+            throw new Error(`${at}.name\` duplicates an earlier entry's`);
         seen.add(name);
         const rawScope = typeof e.scope === 'string' ? e.scope.toLowerCase().trim() : '';
         if (rawScope && rawScope !== 'admin' && rawScope !== 'user') {
-            throw new Error(`variable "${name}" has invalid scope "${e.scope}" (expected admin|user)`);
+            throw new Error(`${at}.scope\` is invalid (expected admin|user)`);
         }
         const scope = rawScope === 'user' ? 'user' : 'admin';
         const label = typeof e.label === 'string' && e.label.trim() ? e.label.trim() : undefined;
-        const oauth = normalizeVariableOAuth(name, e.oauth);
+        const oauth = normalizeVariableOAuth(at, e.oauth);
         // OAuth is inherently per-caller — each user signs in for their own token. An
         // admin-shared OAuth token would leak one user's token to all callers.
         if (oauth && scope !== 'user') {
-            throw new Error(`variable "${name}" with oauth must be scope:user`);
+            throw new Error(`${at}\` has \`oauth\`, so its \`scope\` must be \`user\``);
         }
         return {
             name,
@@ -1002,28 +1316,34 @@ function isProbeableMcpServer(m) {
  * `.tool` author can't aim a sign-in/token exchange at an internal host. Both
  * URLs are REQUIRED here: a `.tool` (http/inline) has no server whose OAuth
  * metadata could fill them in — that convenience belongs to mcp.json servers.
+ *
+ * `at` is the entry's position — `` `variables[2] `` with its opening backtick,
+ * each message closing it after the field — rather than the variable's name.
+ * Same rule as everywhere else a refusal is written: the reason locates the
+ * fault in the file without repeating anything the file said. See
+ * {@link describeManualFault}.
  */
-function normalizeVariableOAuth(name, raw) {
+function normalizeVariableOAuth(at, raw) {
     if (raw === undefined || raw === null)
         return undefined;
     if (typeof raw !== 'object' || Array.isArray(raw)) {
-        throw new Error(`variable "${name}" oauth must be an object`);
+        throw new Error(`${at}.oauth\` must be an object`);
     }
     const o = raw;
     // Confidential OAuth material is provisioned only through the protected
     // client-secret route; reject it here so a plaintext `.tool` can't smuggle one in.
     for (const forbidden of ['clientSecret', 'client_secret', 'secret']) {
         if (o[forbidden] !== undefined) {
-            throw new Error(`variable "${name}" oauth.${forbidden} must be set through the protected client-secret route`);
+            throw new Error(`${at}.oauth.${forbidden}\` must be set through the protected client-secret route`);
         }
     }
     const safeUrl = (v, field) => {
         const s = typeof v === 'string' ? v.trim() : '';
         try {
-            assertSafeFetchUrl(s, { requireHttps: true, label: `${name} oauth.${field}` });
+            assertSafeFetchUrl(s, { requireHttps: true, label: `${at}.oauth.${field}\`` });
         }
         catch (err) {
-            throw new Error(err instanceof Error ? err.message : `variable "${name}" oauth.${field} invalid`);
+            throw new Error(err instanceof Error ? err.message : `${at}.oauth.${field}\` is invalid`);
         }
         return s;
     };
@@ -1031,28 +1351,28 @@ function normalizeVariableOAuth(name, raw) {
     const tokenUrl = safeUrl(o.tokenUrl, 'tokenUrl');
     const clientId = typeof o.clientId === 'string' && o.clientId.trim() ? o.clientId.trim() : '';
     if (!clientId)
-        throw new Error(`variable "${name}" oauth.clientId is required`);
+        throw new Error(`${at}.oauth.clientId\` is required`);
     let scopes;
     if (o.scopes !== undefined) {
         if (!Array.isArray(o.scopes) || !o.scopes.every((s) => typeof s === 'string')) {
-            throw new Error(`variable "${name}" oauth.scopes must be string[]`);
+            throw new Error(`${at}.oauth.scopes\` must be string[]`);
         }
         scopes = o.scopes;
     }
     let authParams;
     if (o.authParams !== undefined) {
         if (typeof o.authParams !== 'object' || Array.isArray(o.authParams)) {
-            throw new Error(`variable "${name}" oauth.authParams must be an object of string values`);
+            throw new Error(`${at}.oauth.authParams\` must be an object of string values`);
         }
         const entries = Object.entries(o.authParams);
         if (!entries.every(([, v]) => typeof v === 'string')) {
-            throw new Error(`variable "${name}" oauth.authParams values must be strings`);
+            throw new Error(`${at}.oauth.authParams\` values must be strings`);
         }
         authParams = Object.fromEntries(entries);
     }
     // PKCE is on unless the file says `false`; only the opt-out is ever stored.
     if (o.pkce !== undefined && typeof o.pkce !== 'boolean') {
-        throw new Error(`variable "${name}" oauth.pkce must be a boolean`);
+        throw new Error(`${at}.oauth.pkce\` must be a boolean`);
     }
     // Never fetched (it rides as a request param), but it names the remote
     // server — same https/SSRF bar as the endpoints.
@@ -1086,6 +1406,9 @@ function normalizeType(raw) {
         return 'mcp';
     if (t === 'inline' || t === 'text' || t === '')
         return 'inline';
-    throw new Error(`unknown \`.tool\` type: ${raw}`);
+    // The written value is not echoed (see the `id` refusal above): the accepted
+    // set says more than the rejected value does, and a `type:` line is one
+    // mis-paste away from holding a credential like any other.
+    throw new Error('unknown `.tool` `type` (expected `http`, `mcp`, `inline`, or absent)');
 }
 //# sourceMappingURL=tool-manuals.service.js.map