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

package/dist/shared/rename-no-replace.js

@@ -0,0 +1,323 @@
+/**
+ * A move that CANNOT replace what is at its destination, whatever happens
+ * between the look and the move.
+ *
+ * Looking first and then calling `fs.rename` is not enough on its own:
+ * `rename` replaces an existing file on every platform, so two moves aiming at
+ * the same free name can both be told it is free and the second one silently
+ * eats what the first one landed. The window is small and the loss is total,
+ * which is the worst pair. This module closes it with filesystem calls that
+ * fail-by-design when the name is taken, so the refusal does not depend on
+ * timing at all:
+ *
+ *   - A FILE moves as `link` + `unlink`. `link` is the atomic no-clobber
+ *     primitive POSIX gives us: it fails with `EEXIST` if anything is at the
+ *     new name, and the two names address one inode in between, so nothing is
+ *     ever half-moved. A filesystem without hard links claims the name with
+ *     `open(…, 'wx')` instead and renames onto its own claim — never a plain
+ *     `rename`, which would put the overwrite back exactly where it is hardest
+ *     to notice.
+ *   - A FOLDER claims its name with `mkdir` first, which fails with `EEXIST`
+ *     the same way, and then renames onto the empty folder it just made
+ *     (POSIX lets a directory rename replace an EMPTY directory, and only an
+ *     empty one). Windows will not do that, so there the plain `rename` is
+ *     used — it refuses a taken destination for directories natively.
+ *
+ * The look still happens first, because it is what produces the sentence the
+ * user reads: "A file named Notes.md already exists in Sales." names the kind
+ * of thing in the way, which `EEXIST` alone does not tell us. The atomic call
+ * is the backstop under it, and when the backstop is the one that fires the
+ * destination is re-examined so the same sentence comes out.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { entryExistsMessage } from '@bevel-software/platform-shared';
+import { isAbsence } from './fs.contract.js';
+/**
+ * A move or copy refused because its destination is taken. Carries the kind
+ * so the caller can raise it as whatever its surface answers with — the
+ * workspace service's `EntryExistsError` (409 to the sidebar), a `ToolError`
+ * (409 to the agent) — without re-deriving the sentence.
+ */
+export class DestinationTakenError extends Error {
+    entryKind;
+    destination;
+    status = 409;
+    constructor(entryKind, destination) {
+        super(entryExistsMessage(entryKind, destination));
+        this.entryKind = entryKind;
+        this.destination = destination;
+        this.name = 'DestinationTakenError';
+    }
+}
+/** The entry at `absolutePath` without following a link, or null when nothing is there. */
+export async function lstatOrNull(absolutePath) {
+    try {
+        return await fs.lstat(absolutePath);
+    }
+    catch (err) {
+        if (isAbsence(err))
+            return null;
+        throw err;
+    }
+}
+/** The real disk — what every caller uses. */
+export const diskProbe = {
+    lstat: lstatOrNull,
+    readdir: (folder) => fs.readdir(folder),
+};
+/**
+ * The one reading of "is this destination the source under another name?".
+ *
+ * `lstat`, never `stat`: a link at the destination is an entry in its own
+ * right.
+ */
+export async function inspectDestination(oldAbsolute, newAbsolute, probe = diskProbe) {
+    const destination = await probe.lstat(newAbsolute);
+    if (destination === null)
+        return { state: 'free' };
+    const source = await probe.lstat(oldAbsolute);
+    // A source that is not there is left to the move's own ENOENT — "there is
+    // nothing to move" is the truer answer than "the name is taken".
+    if (source === null)
+        return { state: 'free' };
+    if (await isSelfRename(oldAbsolute, newAbsolute, source, destination, probe))
+        return { state: 'self' };
+    return { state: 'taken', kind: destination.isDirectory() ? 'folder' : 'file' };
+}
+/**
+ * Whether the destination is the SOURCE, seen under a second spelling of the
+ * one name — the thing a case-insensitive filesystem does and the only reason
+ * a move onto an existing entry is ever allowed.
+ *
+ * Identity alone (same device, same inode) does not show it: two hard links
+ * are one inode under two names a user sees separately in the tree, and a
+ * move onto one of them takes that name away. Neither does folded path
+ * equality on its own, for the same reason in the other direction — on a
+ * CASE-SENSITIVE disk `deal.md` and `Deal.md` fold together as strings while
+ * being two real entries, hard-linked or not.
+ *
+ * What actually distinguishes them is the directory: a filesystem that folds
+ * the two spellings has ONE entry to list, and a filesystem that does not has
+ * two. So the parent is read and the two spellings are counted. One entry
+ * means the filesystem handed us the source itself, whatever spelling was
+ * asked for; two means two names, and the move is a clash.
+ *
+ * Paths in different folders are two entries by definition — but "different
+ * folder" is itself a question for the filesystem and not for the strings: the
+ * same volume that folds `notes.md` into `Notes.md` folds `Sales` into
+ * `sales`, so `Sales/notes.md` → `sales/Notes.md` is one folder, one entry and
+ * one rename. The parents are compared by identity for that reason.
+ *
+ * Two cases never reach the listing at all, because there are no two
+ * spellings in them to count: `oldAbsolute === newAbsolute`, and the pair
+ * whose basenames are identical and whose only difference is the parent's
+ * spelling. Both are one entry by construction.
+ *
+ * Everything above happens only on a volume that folds case, so on the Linux
+ * this is built and tested on it is reached by nothing real. That is what
+ * {@link DestinationProbe} is for — read its note before changing any of this,
+ * because the tests that hold these rules up run against a stand-in volume,
+ * not against the disk under them.
+ */
+async function isSelfRename(oldAbsolute, newAbsolute, source, destination, probe) {
+    if (source.dev !== destination.dev || source.ino !== destination.ino)
+        return false;
+    if (oldAbsolute === newAbsolute)
+        return true;
+    if (!foldsTogether(oldAbsolute, newAbsolute))
+        return false;
+    const folder = path.dirname(oldAbsolute);
+    if (!(await sameFolder(folder, path.dirname(newAbsolute), probe)))
+        return false;
+    // One folder and one NAME: only the parent's spelling changed
+    // (`Sales/notes.md` → `sales/notes.md`), so there is nothing for the listing
+    // to count — asking it whether two identical basenames are both present
+    // would answer yes and read the entry as a clash with itself.
+    if (path.basename(oldAbsolute) === path.basename(newAbsolute))
+        return true;
+    let entries;
+    try {
+        entries = await probe.readdir(folder);
+    }
+    catch {
+        // The parent cannot be listed, so nothing here can be shown to be one
+        // entry. Refusing is the safe reading: at worst a case-only rename on an
+        // unreadable folder is turned away, and nothing is ever overwritten.
+        return false;
+    }
+    const listed = new Set(entries);
+    return !(listed.has(path.basename(oldAbsolute)) && listed.has(path.basename(newAbsolute)));
+}
+/**
+ * Whether two directory paths are the one directory. String equality first,
+ * because that is the answer almost every time and costs nothing; otherwise
+ * the filesystem decides, so a volume that folds `Sales` and `sales` is not
+ * read as two folders.
+ */
+async function sameFolder(a, b, probe) {
+    if (a === b)
+        return true;
+    const [statA, statB] = await Promise.all([probe.lstat(a), probe.lstat(b)]);
+    if (statA === null || statB === null)
+        return false;
+    return statA.dev === statB.dev && statA.ino === statB.ino;
+}
+/** The two paths are one name on a case-insensitive filesystem. */
+function foldsTogether(a, b) {
+    return a.toLowerCase() === b.toLowerCase();
+}
+/**
+ * Move `oldAbsolute` to `newAbsolute`, refusing rather than replacing whatever
+ * is already at the new name. `destinationLabel` is the path the refusal names
+ * — workspace-relative, so the user reads the name they typed and the folder
+ * they aimed at, not a path on our disk.
+ *
+ * The caller is expected to have made the destination's parent already; this
+ * only performs the move itself, so a refusal cannot leave folders behind.
+ */
+export async function renameNoReplace(oldAbsolute, newAbsolute, destinationLabel) {
+    const verdict = await inspectDestination(oldAbsolute, newAbsolute);
+    if (verdict.state === 'taken')
+        throw new DestinationTakenError(verdict.kind, destinationLabel);
+    // A case-only rename has the source itself at the destination, so no
+    // no-clobber call can be used — every one of them would see the name taken.
+    // `rename` is right here: it replaces the source with the source.
+    if (verdict.state === 'self') {
+        await fs.rename(oldAbsolute, newAbsolute);
+        return;
+    }
+    const source = await lstatOrNull(oldAbsolute);
+    if (source?.isDirectory() === true) {
+        await landFolder(oldAbsolute, newAbsolute, destinationLabel);
+        return;
+    }
+    await linkThenUnlink(oldAbsolute, newAbsolute, destinationLabel);
+}
+/**
+ * `link` + `unlink`: the destination is created atomically or not at all, and
+ * the source only goes away once it exists under both names, so no reader ever
+ * sees a partial file at the new name.
+ *
+ * Where hard links are unavailable — `EPERM` or `ENOSYS` on some network and
+ * FUSE mounts, FAT — the fallback is `claimThenRename`, NOT a plain rename: a
+ * rename replaces, and falling back to one would hand back exactly the
+ * overwrite this module exists to prevent, on the filesystems least likely to
+ * be tested.
+ */
+async function linkThenUnlink(oldAbsolute, newAbsolute, destinationLabel) {
+    try {
+        await fs.link(oldAbsolute, newAbsolute);
+    }
+    catch (err) {
+        if (codeOf(err) === 'EEXIST')
+            throw await takenError(newAbsolute, destinationLabel);
+        if (codeOf(err) === 'ENOENT')
+            throw err; // No source: the caller's own ENOENT.
+        await claimThenRename(oldAbsolute, newAbsolute, destinationLabel);
+        return;
+    }
+    await fs.unlink(oldAbsolute);
+}
+/**
+ * The no-clobber move for a file on a filesystem with no hard links: `wx`
+ * claims the name — `open` with `O_EXCL`, which every filesystem Node runs on
+ * implements atomically and which fails with `EEXIST` if anything is there —
+ * and the rename then replaces the empty file we own rather than someone
+ * else's. A rename that fails anyway gives the claim back.
+ *
+ * The cost against `link` + `unlink` is that the destination is briefly an
+ * empty file, which is why this is the fallback and not the first choice.
+ *
+ * Exported for the same reason as {@link landFolder}: the path only runs on
+ * filesystems without hard links, so a test has to call it directly to cover
+ * it at all.
+ */
+export async function claimThenRename(oldAbsolute, newAbsolute, destinationLabel) {
+    let claim;
+    try {
+        claim = await fs.open(newAbsolute, 'wx');
+    }
+    catch (err) {
+        if (codeOf(err) === 'EEXIST')
+            throw await takenError(newAbsolute, destinationLabel);
+        throw err;
+    }
+    await claim.close();
+    try {
+        await fs.rename(oldAbsolute, newAbsolute);
+    }
+    catch (err) {
+        await fs.unlink(newAbsolute).catch(() => undefined);
+        throw err;
+    }
+}
+/**
+ * `mkdir` claims the name — atomically, failing with `EEXIST` if anything at
+ * all is there — and the rename then replaces the empty folder we own. Should
+ * the rename fail anyway (someone wrote INTO our empty folder in between, and
+ * `rename` answers `ENOTEMPTY`), the claim is given back so a failed move
+ * leaves no folder behind.
+ *
+ * Windows cannot rename onto an existing directory even when it is empty, so
+ * the claim would make every folder move fail. It does not need one: its
+ * `rename` refuses a taken destination for directories by itself.
+ *
+ * Exported without the look `renameNoReplace` does first, so the claim and its
+ * rollback — the half that only runs when a name is taken in the moment
+ * between the two — can be driven directly by a test instead of by a race.
+ */
+export async function landFolder(oldAbsolute, newAbsolute, destinationLabel) {
+    if (process.platform === 'win32') {
+        await renameOrTaken(oldAbsolute, newAbsolute, destinationLabel);
+        return;
+    }
+    try {
+        await fs.mkdir(newAbsolute);
+    }
+    catch (err) {
+        if (codeOf(err) === 'EEXIST')
+            throw await takenError(newAbsolute, destinationLabel);
+        throw err;
+    }
+    try {
+        await fs.rename(oldAbsolute, newAbsolute);
+    }
+    catch (err) {
+        await fs.rmdir(newAbsolute).catch(() => undefined);
+        if (codeOf(err) === 'ENOTEMPTY' || codeOf(err) === 'EEXIST') {
+            throw await takenError(newAbsolute, destinationLabel);
+        }
+        throw err;
+    }
+}
+/**
+ * The plain rename, with the one reading the caller needs of its failures: on
+ * any error, whatever is at the destination now decides. Something there means
+ * the name was taken after all (Windows answers `EPERM`, `EEXIST` or
+ * `EACCES` for that case, depending on the kind); nothing there means the
+ * failure was something else entirely and belongs to the caller.
+ */
+async function renameOrTaken(oldAbsolute, newAbsolute, destinationLabel) {
+    try {
+        await fs.rename(oldAbsolute, newAbsolute);
+    }
+    catch (err) {
+        const occupant = await lstatOrNull(newAbsolute);
+        if (occupant !== null)
+            throw new DestinationTakenError(kindOf(occupant), destinationLabel);
+        throw err;
+    }
+}
+/** The refusal, with the kind read off whatever is actually in the way. */
+export async function takenError(newAbsolute, destinationLabel) {
+    const occupant = await lstatOrNull(newAbsolute);
+    return new DestinationTakenError(occupant === null ? 'file' : kindOf(occupant), destinationLabel);
+}
+function kindOf(entry) {
+    return entry.isDirectory() ? 'folder' : 'file';
+}
+function codeOf(err) {
+    return err?.code;
+}
+//# sourceMappingURL=rename-no-replace.js.map

package/dist/shared/rename-no-replace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rename-no-replace.js","sourceRoot":"","sources":["../../src/shared/rename-no-replace.ts"],"names":[],"mappings":"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"}

package/dist/shared/ssrf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ssrf.d.ts","sourceRoot":"","sources":["../../src/shared/ssrf.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CA6BvD;AAgBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACpD,GAAG,CAeL"}
+{"version":3,"file":"ssrf.d.ts","sourceRoot":"","sources":["../../src/shared/ssrf.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAiCvD;AAwCD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACpD,GAAG,CAeL"}

package/dist/shared/ssrf.js

@@ -16,31 +16,62 @@ export function isBlockedHost(hostname) {
     // IPv6 literals only: they contain a colon, whereas a plain hostname never does
     // — so domains like `fc.example.org` / `fd.example.com` are not matched.
     if (host.includes(':')) {
-        // IPv4-mapped IPv6 connects to the embedded v4 — validate it. The textual
-        // form may be dotted (`::ffff:169.254.169.254`) OR two hex hextets
-        // (`::ffff:a9fe:a9fe`) — WHATWG `new URL` canonicalizes the mapped address
-        // to the HEX form, so the dotted regex alone would miss a normalized
-        // hostname. Handle both.
-        const mappedDotted = /:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(host);
-        if (mappedDotted && isBlockedV4(mappedDotted[1]))
+        const hextets = parseIPv6(host);
+        // Not an address `new URL` would accept either — nothing to connect to.
+        if (!hextets)
             return true;
-        const mappedHex = /:ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(host);
-        if (mappedHex) {
-            const hi = parseInt(mappedHex[1], 16);
-            const lo = parseInt(mappedHex[2], 16);
-            const v4 = `${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`;
-            if (isBlockedV4(v4))
-                return true;
+        // IPv4-mapped (::ffff:0:0/96) connects to the embedded v4 — judge that.
+        // Decoded from the hextets, so every spelling lands here: dotted
+        // (`::ffff:169.254.169.254`), the hex form WHATWG `new URL` canonicalizes
+        // to (`::ffff:a9fe:a9fe`) and the fully expanded `0:0:0:0:0:ffff:…`.
+        if (hextets.slice(0, 5).every((h) => h === 0) && hextets[5] === 0xffff) {
+            const [hi, lo] = [hextets[6], hextets[7]];
+            return isBlockedV4(`${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`);
         }
-        if (host === '::1' || host === '::')
-            return true; // loopback / unspecified
-        // link-local fe80::/10 (fe80–febf) and unique-local fc00::/7 (fc/fd).
-        if (/^fe[89ab]/.test(host) || host.startsWith('fc') || host.startsWith('fd'))
+        // Everything else must be global unicast (2000::/3). That excludes loopback
+        // and unspecified (`::1`, `::`, `::2`…), link-local fe80::/10, unique-local
+        // fc00::/7 and multicast ff00::/8.
+        if (hextets[0] < 0x2000 || hextets[0] > 0x3fff)
+            return true;
+        // Inside global unicast, the special-purpose blocks: 2001::/23 (Teredo,
+        // ORCHID, the benchmarking range 2001:2::/48, …), documentation
+        // 2001:db8::/32, and the newer documentation block 3fff::/20. None is a
+        // real host to fetch from.
+        if (hextets[0] === 0x2001 && (hextets[1] < 0x0200 || hextets[1] === 0x0db8))
+            return true;
+        if (hextets[0] === 0x3fff && hextets[1] < 0x1000)
             return true;
         return false;
     }
     return isBlockedV4(host);
 }
+/**
+ * The eight hextets of an IPv6 literal (`::` expanded, a dotted IPv4 tail
+ * decoded), or null when it is not one. A zone id (`%eth0`) is ignored.
+ */
+function parseIPv6(literal) {
+    let text = literal.replace(/%.*$/, '');
+    const dotted = /^(.*:)(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(text);
+    if (dotted) {
+        const octets = dotted.slice(2).map(Number);
+        if (octets.some((o) => o > 255))
+            return null;
+        text = `${dotted[1]}${((octets[0] << 8) | octets[1]).toString(16)}:${((octets[2] << 8) | octets[3]).toString(16)}`;
+    }
+    const halves = text.split('::');
+    if (halves.length > 2)
+        return null;
+    const part = (half) => (half === '' ? [] : half.split(':'));
+    const head = part(halves[0]);
+    const tail = halves.length === 2 ? part(halves[1]) : [];
+    const missing = 8 - head.length - tail.length;
+    if (halves.length === 2 ? missing < 1 : missing !== 0)
+        return null;
+    const groups = [...head, ...Array(halves.length === 2 ? missing : 0).fill('0'), ...tail];
+    if (!groups.every((g) => /^[0-9a-f]{1,4}$/.test(g)))
+        return null;
+    return groups.map((g) => parseInt(g, 16));
+}
 /** True for an IPv4 literal in a private / loopback / link-local (incl. cloud IMDS) range. */
 function isBlockedV4(host) {
     const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);

package/dist/shared/ssrf.js.map

@@ -1 +1 @@
-{"version":3,"file":"ssrf.js","sourceRoot":"","sources":["../../src/shared/ssrf.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ssrf.js","sourceRoot":"","sources":["../../src/shared/ssrf.ts"],"names":[],"mappings":"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"}

package/dist/shared/ttl-cache.d.ts

@@ -8,9 +8,36 @@ export declare class TtlCache<T> {
     private readonly ttlMs;
     private readonly now;
     private entry;
+    /**
+     * Bumped by every `invalidate()`. A fetch carries the value this had when it
+     * started, and `set` refuses a value whose fetch straddled a drop — see there.
+     */
+    private generation;
     constructor(ttlMs: number, now?: () => number);
     get(): T | null;
-    set(value: T): void;
+    /**
+     * Take a token BEFORE starting the fetch whose result you will `set`.
+     *
+     * Every caller of this cache reads the disk across an `await`, and the whole
+     * point of `invalidate()` is that it fires during exactly that window: the
+     * merge pulls the new tree in while a catalog read that started on the old
+     * one is still in flight. Without a token that late `set` wins, and the cache
+     * holds the PRE-invalidation scan for a fresh full TTL — the drop silently
+     * undone, and the staleness it existed to prevent restored.
+     */
+    begin(): number;
+    /**
+     * Store a value fetched under `token`. Required, not optional: a caller that
+     * could forget it is a caller that reintroduces the race above, and there are
+     * few enough call sites to make the token cheap.
+     *
+     * A stale token means an `invalidate()` landed mid-fetch, so this value
+     * describes a tree that is already gone: it is DISCARDED rather than stored.
+     * The fetcher still returns it to its own caller — that read is merely as old
+     * as the moment it started, which is true of any read — but the next caller
+     * re-scans instead of inheriting it.
+     */
+    set(value: T, token: number): void;
     invalidate(): void;
 }
 //# sourceMappingURL=ttl-cache.d.ts.map

package/dist/shared/ttl-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ttl-cache.d.ts","sourceRoot":"","sources":["../../src/shared/ttl-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,QAAQ,CAAC,CAAC;IAInB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAJtB,OAAO,CAAC,KAAK,CAAyC;gBAGnC,KAAK,EAAE,MAAM,EACb,GAAG,GAAE,MAAM,MAAiB;IAG/C,GAAG,IAAI,CAAC,GAAG,IAAI;IAKf,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAInB,UAAU,IAAI,IAAI;CAGnB"}
+{"version":3,"file":"ttl-cache.d.ts","sourceRoot":"","sources":["../../src/shared/ttl-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,QAAQ,CAAC,CAAC;IASnB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IATtB,OAAO,CAAC,KAAK,CAAyC;IACtD;;;OAGG;IACH,OAAO,CAAC,UAAU,CAAK;gBAGJ,KAAK,EAAE,MAAM,EACb,GAAG,GAAE,MAAM,MAAiB;IAG/C,GAAG,IAAI,CAAC,GAAG,IAAI;IAKf;;;;;;;;;OASG;IACH,KAAK,IAAI,MAAM;IAIf;;;;;;;;;;OAUG;IACH,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAKlC,UAAU,IAAI,IAAI;CAInB"}

package/dist/shared/ttl-cache.js

@@ -8,6 +8,11 @@ export class TtlCache {
     ttlMs;
     now;
     entry = null;
+    /**
+     * Bumped by every `invalidate()`. A fetch carries the value this had when it
+     * started, and `set` refuses a value whose fetch straddled a drop — see there.
+     */
+    generation = 0;
     constructor(ttlMs, now = Date.now) {
         this.ttlMs = ttlMs;
         this.now = now;
@@ -17,11 +22,38 @@ export class TtlCache {
             return this.entry.value;
         return null;
     }
-    set(value) {
+    /**
+     * Take a token BEFORE starting the fetch whose result you will `set`.
+     *
+     * Every caller of this cache reads the disk across an `await`, and the whole
+     * point of `invalidate()` is that it fires during exactly that window: the
+     * merge pulls the new tree in while a catalog read that started on the old
+     * one is still in flight. Without a token that late `set` wins, and the cache
+     * holds the PRE-invalidation scan for a fresh full TTL — the drop silently
+     * undone, and the staleness it existed to prevent restored.
+     */
+    begin() {
+        return this.generation;
+    }
+    /**
+     * Store a value fetched under `token`. Required, not optional: a caller that
+     * could forget it is a caller that reintroduces the race above, and there are
+     * few enough call sites to make the token cheap.
+     *
+     * A stale token means an `invalidate()` landed mid-fetch, so this value
+     * describes a tree that is already gone: it is DISCARDED rather than stored.
+     * The fetcher still returns it to its own caller — that read is merely as old
+     * as the moment it started, which is true of any read — but the next caller
+     * re-scans instead of inheriting it.
+     */
+    set(value, token) {
+        if (token !== this.generation)
+            return;
         this.entry = { at: this.now(), value };
     }
     invalidate() {
         this.entry = null;
+        this.generation++;
     }
 }
 //# sourceMappingURL=ttl-cache.js.map

package/dist/shared/ttl-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"ttl-cache.js","sourceRoot":"","sources":["../../src/shared/ttl-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,QAAQ;IAIA;IACA;IAJX,KAAK,GAAoC,IAAI,CAAC;IAEtD,YACmB,KAAa,EACb,MAAoB,IAAI,CAAC,GAAG;QAD5B,UAAK,GAAL,KAAK,CAAQ;QACb,QAAG,GAAH,GAAG,CAAyB;IAC5C,CAAC;IAEJ,GAAG;QACD,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;QACnF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,GAAG,CAAC,KAAQ;QACV,IAAI,CAAC,KAAK,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC;IACzC,CAAC;IAED,UAAU;QACR,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;CACF"}
+{"version":3,"file":"ttl-cache.js","sourceRoot":"","sources":["../../src/shared/ttl-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,QAAQ;IASA;IACA;IATX,KAAK,GAAoC,IAAI,CAAC;IACtD;;;OAGG;IACK,UAAU,GAAG,CAAC,CAAC;IAEvB,YACmB,KAAa,EACb,MAAoB,IAAI,CAAC,GAAG;QAD5B,UAAK,GAAL,KAAK,CAAQ;QACb,QAAG,GAAH,GAAG,CAAyB;IAC5C,CAAC;IAEJ,GAAG;QACD,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;QACnF,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK;QACH,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED;;;;;;;;;;OAUG;IACH,GAAG,CAAC,KAAQ,EAAE,KAAa;QACzB,IAAI,KAAK,KAAK,IAAI,CAAC,UAAU;YAAE,OAAO;QACtC,IAAI,CAAC,KAAK,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC;IACzC,CAAC;IAED,UAAU;QACR,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,UAAU,EAAE,CAAC;IACpB,CAAC;CACF"}

package/dist/version.d.ts

@@ -4,12 +4,16 @@
  * rollout by sha *before* smoke-testing it.
  *
  * Sources, in priority order:
- *  - `GIT_SHA` — baked at image build time via the Dockerfile `ARG`/`ENV`
- *    (set from `git rev-parse HEAD` by CI or `docker compose build`).
- *  - `SOURCE_COMMIT` — Coolify injects this for git-based deploys, so the
- *    sha is correct on hosted deploys even when no explicit build arg was
- *    passed. `.git` is in `.dockerignore`, so the sha can't be derived
- *    inside the build — it has to be passed in.
+ *  - `GIT_SHA` — baked into the image by the Dockerfile from its ONE build
+ *    arg, `SOURCE_COMMIT` (CI, Coolify and a manual build all pass that
+ *    name). Baked under a different name deliberately: a runtime variable
+ *    overrides an image ENV of the same name, and `SOURCE_COMMIT` is what
+ *    a hosted deployment UI writes at runtime — once as an empty literal
+ *    that blanked the real value. Nothing at runtime sets `GIT_SHA`.
+ *  - `SOURCE_COMMIT` — the runtime value Coolify injects for git-based
+ *    deploys, so a build that was not given the arg still reports a sha.
+ *    `.git` is in `.dockerignore`, so the sha can't be derived inside the
+ *    build — it has to be passed in.
  *  - `'unknown'` — local `tsx` runs and any build that wired neither.
  */
 export declare function resolveGitSha(env?: NodeJS.ProcessEnv): string;

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAE1E;AAED,eAAO,MAAM,OAAO,QAAkB,CAAC;AAEvC;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAW1C"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAE1E;AAED,eAAO,MAAM,OAAO,QAAkB,CAAC;AAEvC;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAW1C"}

package/dist/version.js

@@ -5,12 +5,16 @@ import { readFileSync } from 'node:fs';
  * rollout by sha *before* smoke-testing it.
  *
  * Sources, in priority order:
- *  - `GIT_SHA` — baked at image build time via the Dockerfile `ARG`/`ENV`
- *    (set from `git rev-parse HEAD` by CI or `docker compose build`).
- *  - `SOURCE_COMMIT` — Coolify injects this for git-based deploys, so the
- *    sha is correct on hosted deploys even when no explicit build arg was
- *    passed. `.git` is in `.dockerignore`, so the sha can't be derived
- *    inside the build — it has to be passed in.
+ *  - `GIT_SHA` — baked into the image by the Dockerfile from its ONE build
+ *    arg, `SOURCE_COMMIT` (CI, Coolify and a manual build all pass that
+ *    name). Baked under a different name deliberately: a runtime variable
+ *    overrides an image ENV of the same name, and `SOURCE_COMMIT` is what
+ *    a hosted deployment UI writes at runtime — once as an empty literal
+ *    that blanked the real value. Nothing at runtime sets `GIT_SHA`.
+ *  - `SOURCE_COMMIT` — the runtime value Coolify injects for git-based
+ *    deploys, so a build that was not given the arg still reports a sha.
+ *    `.git` is in `.dockerignore`, so the sha can't be derived inside the
+ *    build — it has to be passed in.
  *  - `'unknown'` — local `tsx` runs and any build that wired neither.
  */
 export function resolveGitSha(env = process.env) {

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAAC,MAAyB,OAAO,CAAC,GAAG;IAChE,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC;AACtE,CAAC;AAED,MAAM,CAAC,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;AAEvC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB;IAC/B,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CACzB,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CACzC,CAAC;QAC3B,OAAO,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ,IAAI,QAAQ,CAAC,OAAO;YAC7D,CAAC,CAAC,QAAQ,CAAC,OAAO;YAClB,CAAC,CAAC,SAAS,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,aAAa,CAAC,MAAyB,OAAO,CAAC,GAAG;IAChE,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC;AACtE,CAAC;AAED,MAAM,CAAC,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;AAEvC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB;IAC/B,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CACzB,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CACzC,CAAC;QAC3B,OAAO,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ,IAAI,QAAQ,CAAC,OAAO;YAC7D,CAAC,CAAC,QAAQ,CAAC,OAAO;YAClB,CAAC,CAAC,SAAS,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/kb-template/.bevelignore

@@ -11,7 +11,10 @@
 # Repo hygiene files that clutter the tree without being node content.
 .gitignore
 .gitattributes
-AGENTS.md
+# The platform's agent guide.
+{{agentsFile}}
+# The deployment preamble is edited from External agent access, not as a KB page.
+/mcp-description.md
 # The pre-rename name. Listed so a knowledge base carrying both files hides
 # both — top-up adds AGENTS.md but never deletes the CLAUDE.md beside it.
 CLAUDE.md
@@ -21,5 +24,3 @@ CLAUDE.md
 
 **/access.md
 roles.yaml
-
-Plugins/