@bevel-software/platform-core-backend 0.33.0 → 0.35.0

package/src/modules/workspace/ripgrep-version.ts

@@ -0,0 +1,35 @@
+/**
+ * ripgrep is what the agents' `grep` tool searches with (`ripgrep-search.ts`),
+ * and there is no other search to fall back on. So its absence is found at
+ * boot, the way a git too old is (`git-version.ts`): by the deploy that
+ * produced the broken image, never by the first agent that searches.
+ *
+ * The Hexis Dockerfile installs it from Debian (`ripgrep`); a server run from
+ * source needs `rg` on its PATH.
+ */
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('grep');
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Run `rg --version`, log what answered, and throw a worded error naming the
+ * binary when it cannot be run. Call once during startup.
+ */
+export async function assertRipgrep(): Promise<void> {
+  let stdout: string;
+  try {
+    ({ stdout } = await execFileAsync('rg', ['--version']));
+  } catch (err) {
+    throw new Error(
+      `ripgrep (\`rg\`) is required on the server's PATH but could not be run: ${String(err)}. ` +
+        'The grep tool searches with it. The Hexis Dockerfile installs it (Debian package `ripgrep`); ' +
+        'a server run from source needs ripgrep installed.',
+    );
+  }
+  log.info(`search engine: ${stdout.split('\n')[0]!.trim()}`);
+}

package/src/modules/workspace/startup/__tests__/beside-checkout.test.ts

@@ -61,6 +61,17 @@ describe('noteBesideCheckout', () => {
     expect(notes).toEqual([]);
   });
 
+  it("says nothing about the platform's own tmp folder, and names a file or a link squatting its name", async () => {
+    await workspace('main', { dirs: ['tmp/u/chat-uploads'] });
+    await scan();
+    expect(notes).toEqual([]);
+    const dir = await workspace('bob%2Fdraft', { files: ['tmp'] });
+    await scan();
+    expect(notes).toHaveLength(1);
+    expect(notes[0]).toContain(`${BESIDE_CHECKOUT_NOTE} "tmp"`);
+    await expect(fs.stat(path.join(dir, 'tmp'))).resolves.toBeTruthy();
+  });
+
   it('marks the folders with a trailing slash so one line says which is which', async () => {
     await workspace('main', { dirs: ['Reports'], files: ['Reports.md'] });
     await scan();

package/src/modules/workspace/startup/beside-checkout.ts

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { logger } from '../../../shared/logging.js';
 import { isAbsence } from '../../../shared/fs.contract.js';
 import { printable } from '../../../shared/printable.js';
+import { WORKSPACE_TMP_DIR } from '../workspace-tmp.js';
 
 const log = logger('kb-startup');
 
@@ -26,11 +27,14 @@ export const BESIDE_CHECKOUT_NOTE = 'Beside the checkout, not in the repository:
  * clone, and a boot that quietly removed it would be a data loss nobody asked
  * for. The operator cleans up, and the note stops on the next start.
  *
- * EVERYTHING other than the checkout folder is named, the platform's own
- * transient `tmp/` scratch included on the rare start that finds one (a run
- * clears it when it finishes). That is deliberate: the note's claim is about
- * what is not in the repository, and a note that quietly kept exceptions would
- * be a note an operator could not trust.
+ * EVERYTHING other than the checkout folder and the platform's own `tmp/`
+ * folder is named. `tmp/` is the one exception, stated here: it is the
+ * platform's (what the chat and the readers stage lives there, reached
+ * through the `__tmp__/` ref — see `workspace-tmp.ts`), it has a sweep of its
+ * own, and a note that told an operator to remove it by hand would be asking
+ * them to delete people's staged files. Everything else is a stray: the note's
+ * claim is about what is not in the repository, and a note that quietly kept
+ * further exceptions would be a note an operator could not trust.
  *
  * NOT a `OnServerStart` step, and deliberately outside the KB startup phase.
  * That phase is gated — it does nothing until the branch model and the
@@ -65,6 +69,10 @@ export async function noteBesideCheckout(
       // the service judges it: a clone mounted elsewhere is the operator's
       // business, here as it is there.
       if (entry.name === kbDirName && (await isDirectory(path.join(workspaceDir, entry.name)))) continue;
+      // The platform's own tmp folder, swept on its own (see the note above).
+      // Judged by `lstat`, as the sweep judges it: a `tmp` that is a link, or
+      // a file, is not that folder, and is named like any other stray.
+      if (entry.name === WORKSPACE_TMP_DIR && entry.isDirectory()) continue;
       // A trailing slash marks the folders, so one line says which is which
       // without the operator having to go and look. Then `printable`, because
       // every name here is disk-controlled text on its way into an operator's

package/src/modules/workspace/worker-pool.ts

@@ -2,10 +2,9 @@ import type { Worker } from 'node:worker_threads';
 
 /**
  * The pooled worker threads that keep CPU-bound work off the request thread:
- * the mechanics every worker kind shares, whatever its worker runs. Two kinds
- * use it today, each with a pool of its own — the regex matcher `grep` runs a
- * caller's pattern in (`bounded-matcher.ts`) and the document extractor every
- * office, PDF and email extraction runs in (`file-readers/extract-in-worker.ts`).
+ * the mechanics every worker kind shares, whatever its worker runs. One kind
+ * uses it today, with a pool of its own — the document extractor every office,
+ * PDF and email extraction runs in (`file-readers/extract-in-worker.ts`).
  *
  * What a kind brings is how to start its worker; what the pool owns is the
  * rest: at most `poolMax` workers, a capped queue of jobs waiting for one,

package/src/modules/workspace/workspace-tmp.ts

@@ -0,0 +1,457 @@
+import { promises as fs, type Stats } from 'node:fs';
+import path from 'node:path';
+import { PathNotFoundError, WorkflowDomainError, WorkflowValidationError } from '../../shared/domain-errors.js';
+import { assertWithinDirectory } from '../../shared/path-containment.js';
+import { sanitizedPath } from '../../shared/printable.js';
+import { hasControlCharacter, TMP_REF_PREFIX } from '../kb-fs/index.js';
+import { isAbsence, type ITreeWalker } from '../../shared/fs.contract.js';
+import { logger } from '../../shared/logging.js';
+import { lstatOrNull } from '../../shared/rename-no-replace.js';
+
+const log = logger('workspace-tmp');
+
+/**
+ * A workspace's `tmp/` folder, reached through a reserved ref.
+ *
+ * Every workspace directory holds its checkout and, beside it, a `tmp/`
+ * folder: the chat stages attachments there, the SharePoint reader stages
+ * documents there, and nothing in it is ever committed. The file tools place
+ * every path under the checkout (see `kb-fs/repo-path.ts`), so the folder is
+ * named by a REF instead — `__tmp__/<path>` — which `read_file`, `file_stat`,
+ * `grep` and `copy_file` (as its source) accept beside a repository path, and
+ * every other tool refuses (`kb-fs/tmp-ref.ts`, the one admission gate every
+ * tool's path inputs pass). A plain `tmp/…` path is not that ref and never
+ * will be: `tmp` is a legal folder name inside a repository, and the
+ * normaliser's rule is what keeps every other path in it.
+ *
+ * The ref is scoped twice. To the WORKSPACE: it is resolved against the
+ * workspace of the branch the call names, exactly like a repository path. And
+ * to the CALLER: what a person stages lands under their own folder,
+ * `tmp/<owner id>/` ({@link stageTmpRef}, the one way in), and a ref resolves
+ * inside the caller's own folder and nowhere else ({@link resolveTmpRef}). A
+ * file somebody else staged is therefore not there — the plain not-found,
+ * the same answer as for a file that never existed — rather than something an
+ * access rule has to refuse: the folder is outside the repository, where no
+ * `access.md` governs anything, and the only person a staged attachment is
+ * for is the one who attached it. The ref names ONE file — no folder, no
+ * listing — and nothing outside the caller's folder is reachable through it,
+ * links included. Every resolution goes through {@link resolveTmpRef}; there
+ * is no second reader of the folder.
+ *
+ * Entries live for {@link TMP_MAX_AGE_MS} after their last modification, then
+ * the platform's periodic sweep removes them ({@link sweepTmpFolder},
+ * scheduled by {@link TmpSweeper}) — or sooner, when a distribution clears a
+ * workspace's whole `tmp/` after a run of its own (`clearTmp`): "up to seven
+ * days" is the promise, not "seven days".
+ */
+
+/** The folder the ref reaches, beside the checkout in every workspace directory. */
+export const WORKSPACE_TMP_DIR = 'tmp';
+
+/** How long an entry of a `tmp/` folder lives after its last modification: seven days. */
+export const TMP_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** How often the platform sweeps every workspace's `tmp/` folder: hourly. */
+export const TMP_SWEEP_INTERVAL_MS = 60 * 60 * 1000;
+
+/** A ref that breaks one of the rules, with the rule named. */
+function invalidRef(ref: string, rule: string): WorkflowValidationError {
+  const shown = sanitizedPath(ref);
+  return new WorkflowValidationError(`"${shown}" is not a valid tmp ref: ${rule}`, { kind: 'tmp-ref-invalid', path: shown });
+}
+
+/**
+ * The folder of one owner inside a workspace's `tmp/`: `tmp/<owner id>/`.
+ * The id is an account id, which the platform mints and which is one path
+ * segment by construction; one that is not — empty, a separator in it, a
+ * `.`/`..`, a control character — is a programming error, never a file to
+ * look for, and is refused as one.
+ */
+function ownerFolder(workspaceDir: string, ownerId: string): string {
+  if (
+    ownerId === '' ||
+    ownerId === '.' ||
+    ownerId === '..' ||
+    ownerId.includes('/') ||
+    ownerId.includes('\\') ||
+    hasControlCharacter(ownerId) ||
+    ownerId.length > 255
+  ) {
+    throw new Error(`Invalid tmp owner id "${sanitizedPath(ownerId)}": an owner's tmp folder is one path segment.`);
+  }
+  return path.join(workspaceDir, WORKSPACE_TMP_DIR, ownerId);
+}
+
+/**
+ * What a failed look at the folder answers, naming the REF and never the path
+ * on disk — the raw error (which carries that path) is the server log's, not
+ * the caller's: nothing there is the ordinary not-found; a loop of links is
+ * refused by the link rule; anything else (a permission, an I/O error) is a
+ * 500 that says the ref could not be read.
+ */
+function tmpRefFailure(ref: string, err: unknown): Error {
+  if (isAbsence(err)) return new PathNotFoundError(ref);
+  const shown = sanitizedPath(ref);
+  const code = (err as { code?: unknown } | null)?.code;
+  if (code === 'ELOOP') {
+    return invalidRef(ref, 'it goes through a link that cannot be followed (a link that leads back to itself).');
+  }
+  log.warn('could not read a tmp ref:', { err, ref: shown });
+  return new WorkflowDomainError(`"${shown}" could not be read from the workspace's tmp folder.`, 500, {
+    kind: 'tmp-ref-unreadable',
+    path: shown,
+  });
+}
+
+/**
+ * The ref's path inside the `tmp/` folder, as segments — or the refusal that
+ * names the rule it breaks. Lexical only: the folder and link rules need the
+ * disk and are {@link resolveTmpRef}'s.
+ */
+function tmpRefSegments(ref: string): string[] {
+  const rest = ref.startsWith(TMP_REF_PREFIX) ? ref.slice(TMP_REF_PREFIX.length) : '';
+  // First, because the refusal below would otherwise quote the character
+  // that forges a second line — and a line break is a separator to git and
+  // to every line-oriented log this ref may reach.
+  if (hasControlCharacter(ref)) {
+    throw invalidRef(ref, 'it contains a control character (a line break, a NUL or another invisible byte), which is part of no file name.');
+  }
+  if (rest === '') {
+    throw invalidRef(ref, `it names the tmp folder itself. A tmp ref names one file: \`${TMP_REF_PREFIX}<path to the file>\`.`);
+  }
+  if (rest.startsWith('/') || /^[A-Za-z]:/.test(rest)) {
+    throw invalidRef(ref, 'the path after the prefix is absolute. It is a path inside the workspace\'s tmp folder, written without a leading slash.');
+  }
+  if (rest.includes('\\')) {
+    throw invalidRef(ref, 'it contains a backslash. Separate folders with `/`.');
+  }
+  if (rest.endsWith('/')) {
+    throw invalidRef(ref, 'it ends with `/`, which names a folder. A tmp ref names one file; the tmp folder is not listed.');
+  }
+  const segments = rest.split('/');
+  if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+    throw invalidRef(ref, 'it contains a `.` or `..` segment (or an empty one). A tmp ref names one file inside the workspace\'s tmp folder and cannot climb out of it.');
+  }
+  return segments;
+}
+
+/**
+ * `folder` is absent, or a real directory — never a link, never a file. The
+ * `tmp/` folder and an owner's folder are judged by this before anything
+ * resolves or lands under them: a link standing in either place would carry
+ * the whole folder somewhere else, and a real-path containment check judged
+ * against the link's target would not notice.
+ */
+async function assertOwnFolder(folder: string, ref: string, failed: (err: unknown) => never): Promise<void> {
+  const stat = await lstatOrNull(folder).catch(failed);
+  if (stat !== null && !stat.isDirectory()) {
+    throw invalidRef(ref, "its tmp folder is not a folder of this workspace's own (a link or a file stands where it should be).");
+  }
+}
+
+/**
+ * THE resolution of a ref, against one owner's folder in one workspace
+ * directory: the file's absolute path and its stat, or a refusal. Every read
+ * of the folder starts here.
+ *
+ * - The lexical rules first ({@link tmpRefSegments}), before the disk is
+ *   asked anything.
+ * - Nothing there — the owner's folder included, which a person who has
+ *   staged nothing does not have — is a {@link PathNotFoundError} naming the
+ *   REF, never the path on disk: the answer every file tool turns into its
+ *   ordinary 404. What another person staged is "nothing there" too. Every
+ *   other failure names the ref alone as well ({@link tmpRefFailure}).
+ * - The file's REAL path must lie inside the owner's folder's real path, so a
+ *   link — anywhere along the ref — that leads out of it (into another
+ *   owner's folder included) is refused rather than followed. A link that
+ *   stays inside is the file it points at.
+ * - A folder is refused by the rule, never listed.
+ */
+export async function resolveTmpRef(
+  workspaceDir: string,
+  ownerId: string,
+  ref: string,
+): Promise<{ absolutePath: string; stat: Stats }> {
+  const segments = tmpRefSegments(ref);
+  const ownerDir = ownerFolder(workspaceDir, ownerId);
+  const absent = (err: unknown): never => {
+    throw tmpRefFailure(ref, err);
+  };
+  // `tmp/` and the owner's folder must BE folders of this workspace, not
+  // links to ones somewhere else: the containment below is judged against
+  // the owner's folder's real path, which a link would move along with it.
+  await assertOwnFolder(path.join(workspaceDir, WORKSPACE_TMP_DIR), ref, absent);
+  await assertOwnFolder(ownerDir, ref, absent);
+  if ((await lstatOrNull(ownerDir).catch(absent)) === null) throw new PathNotFoundError(ref);
+  const realOwnerDir = await fs.realpath(ownerDir).catch(absent);
+  const real = await fs.realpath(path.join(ownerDir, ...segments)).catch(absent);
+  // THE containment check (shared/path-containment.ts), on the real paths;
+  // its refusal is answered as the link rule, naming the ref. The folder
+  // itself passes it, and is refused below as a folder.
+  try {
+    assertWithinDirectory(real, realOwnerDir);
+  } catch {
+    throw invalidRef(ref, 'it goes through a link that leads out of your tmp folder, and links out of it are never followed.');
+  }
+  const stat = await fs.stat(real).catch(absent);
+  if (stat.isDirectory()) {
+    throw invalidRef(ref, 'it names a folder. A tmp ref names one file; the tmp folder is not listed.');
+  }
+  if (!stat.isFile()) {
+    throw invalidRef(ref, 'it names something that is not a file.');
+  }
+  return { absolutePath: real, stat };
+}
+
+/** The bytes of the one file a ref names in `ownerId`'s folder of `workspaceDir`'s tmp (see {@link resolveTmpRef}). */
+export async function readTmpRef(workspaceDir: string, ownerId: string, ref: string): Promise<Buffer> {
+  const { absolutePath } = await resolveTmpRef(workspaceDir, ownerId, ref);
+  return fs.readFile(absolutePath).catch((err: unknown) => {
+    // Swept or replaced between the resolve and the read: the same answer a
+    // moment later would give, still naming the ref.
+    throw tmpRefFailure(ref, err);
+  });
+}
+
+/** What `file_stat` reports about a staged file: the fields a repository file's stat carries. */
+export interface TmpFileStat {
+  /** The file's own name, the last segment of the ref. */
+  name: string;
+  size: number;
+  createdAt: Date;
+  modifiedAt: Date;
+}
+
+/** The stat of the one file a ref names (see {@link resolveTmpRef}). */
+export async function statTmpRef(workspaceDir: string, ownerId: string, ref: string): Promise<TmpFileStat> {
+  const { stat } = await resolveTmpRef(workspaceDir, ownerId, ref);
+  return { name: ref.slice(ref.lastIndexOf('/') + 1), size: stat.size, createdAt: stat.birthtime, modifiedAt: stat.mtime };
+}
+
+/**
+ * Stage `bytes` at `relativePath` in `ownerId`'s folder of `workspaceDir`'s
+ * tmp, and answer the ref the owner reads it back with: the ONE way a file
+ * gets into the folder the ref reaches, so the convention — one folder per
+ * owner, the file's path inside it — is this function's and no stager's.
+ * `relativePath` obeys a ref's own rules (one file, no `..`, no absolute
+ * path, no backslash, no control character); the refusal names the rule.
+ * Replaces the FILE at the path: a staged file is the stager's own scratch,
+ * and the chat names uploads by their content. Never writes through a link:
+ * not one standing where `tmp/` or the owner's folder should be, not one on
+ * the way, and not one at the file's own name (judged by `lstat`, which is
+ * what every platform has; the check and the write are two steps, as they
+ * are everywhere else in this file).
+ */
+export async function stageTmpRef(workspaceDir: string, ownerId: string, relativePath: string, bytes: Uint8Array): Promise<string> {
+  const ref = TMP_REF_PREFIX + relativePath;
+  const segments = tmpRefSegments(ref);
+  const ownerDir = ownerFolder(workspaceDir, ownerId);
+  const rethrow = (err: unknown): never => {
+    throw err;
+  };
+  await assertOwnFolder(path.join(workspaceDir, WORKSPACE_TMP_DIR), ref, rethrow);
+  await assertOwnFolder(ownerDir, ref, rethrow);
+  // The workspace directory itself may not exist yet: a staged file belongs
+  // beside the checkout whether or not the branch is cloned, and the
+  // directory's path is the root's own (`workspaceDirWithinRoot`), nothing
+  // the ref names — so it is simply made.
+  await fs.mkdir(workspaceDir, { recursive: true });
+  // The folders on the way — `tmp/` and the owner's folder included, when a
+  // first staging has yet to make them — made one at a time and each judged
+  // before the next is entered: never through a link, which a recursive
+  // mkdir would follow, creating folders wherever the link leads before
+  // anything could refuse it. The one rule for the whole path, the folders
+  // already there included.
+  await makeFoldersWithin(workspaceDir, [WORKSPACE_TMP_DIR, ownerId, ...segments.slice(0, -1)], ref);
+  const target = path.join(ownerDir, ...segments);
+  // The name itself: a file to replace, nothing yet, or something that is
+  // neither — a link (which a write would follow) or a folder — refused.
+  const standing = await lstatOrNull(target);
+  if (standing !== null && !standing.isFile()) {
+    throw invalidRef(ref, 'it names something that is not a file.');
+  }
+  await fs.writeFile(target, bytes);
+  return ref;
+}
+
+/**
+ * The folders of `segments` under `base`, each one entered only once it is
+ * known to be a real directory of the owner's folder: a missing one is made
+ * (and judged again, since another stage may have made it meanwhile), and a
+ * link or a file standing in its place is refused as the link rule — before
+ * any folder is made beyond it, so a link on the way creates nothing where it
+ * leads. `lstat`, as everywhere in this file, so a link is seen as a link.
+ */
+async function makeFoldersWithin(base: string, segments: readonly string[], ref: string): Promise<void> {
+  let at = base;
+  for (const segment of segments) {
+    at = path.join(at, segment);
+    let standing = await lstatOrNull(at);
+    if (standing === null) {
+      await fs.mkdir(at).catch((err: unknown) => {
+        if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err;
+      });
+      standing = await lstatOrNull(at);
+    }
+    if (standing === null || !standing.isDirectory()) {
+      throw invalidRef(ref, 'it goes through a link that leads out of your tmp folder, and links out of it are never followed.');
+    }
+  }
+}
+
+/**
+ * Remove every file of one `tmp/` folder, at any depth, whose last
+ * modification is older than `maxAgeMs`, and every folder in it that the
+ * sweep leaves empty and that was itself older than that before the sweep
+ * touched it. Judged per FILE, because the stagers keep a long-lived folder
+ * each (`chat-uploads/`, …) whose own mtime moves with every new upload: a
+ * folder judged as a whole would keep an old file for as long as anyone kept
+ * uploading beside it. Everything is judged by its own `lstat`, and a link is
+ * removed as the link, never followed. The `tmp/` folder itself stays. A
+ * folder that is not there is nothing to sweep. Returns the paths removed,
+ * relative to `tmp/`.
+ *
+ * The tree is read by THE walk (`walker`, see `shared/fs.contract.ts`), not a
+ * loop of its own: its files, its other entries (a link, a socket — never
+ * entered) and its folders are collected, each folder's age read as it is
+ * listed, so before anything in it goes. A folder that cannot be listed is
+ * the walk's hole: logged, and walked around. The removals follow the walk —
+ * the entries first, then the folders deepest first, so a folder emptied by
+ * the sweep is judged after its contents.
+ *
+ * `signal` ends the sweep early: once it is aborted the walk stops listing
+ * and nothing more is removed — it is asked again right before each removal,
+ * after every awaited look — and what is already gone is returned.
+ */
+export async function sweepTmpFolder(
+  walker: ITreeWalker,
+  workspaceDir: string,
+  maxAgeMs: number,
+  now: number,
+  signal?: AbortSignal,
+): Promise<string[]> {
+  const tmpDir = path.join(workspaceDir, WORKSPACE_TMP_DIR);
+  // `lstat` the folder itself: a `tmp` that is a link is not a folder of
+  // this workspace's to sweep (the walk would follow it). Not there is
+  // nothing to sweep.
+  if ((await lstatOrNull(tmpDir))?.isDirectory() !== true) return [];
+  const join = (dir: string, name: string): string => (dir === '' ? name : `${dir}/${name}`);
+  const entries: string[] = [];
+  const oldDirs: string[] = [];
+  const stopped = (): boolean => signal?.aborted === true;
+  // The entry's own `lstat` (shared/rename-no-replace.ts), or null when it is
+  // gone; any other failure spoils that one entry: logged, and left alone.
+  const entryStat = async (rel: string): Promise<Stats | null> => {
+    try {
+      return await lstatOrNull(path.join(tmpDir, rel));
+    } catch (err) {
+      log.warn('could not stat a tmp entry:', { err, entry: sanitizedPath(rel) });
+      return null;
+    }
+  };
+  await walker.walk(tmpDir, { until: stopped }, [
+    {
+      async onDir(rel) {
+        if (rel === '') return;
+        // Its age is read BEFORE its contents go: removing them moves it.
+        const stat = await entryStat(rel);
+        if (stat && now - stat.mtimeMs > maxAgeMs) oldDirs.push(rel);
+      },
+      onFile(dir, name) {
+        entries.push(join(dir, name));
+      },
+      onOther(dir, entry) {
+        entries.push(join(dir, entry.name));
+      },
+      onHole(rel, err) {
+        log.warn('could not list a tmp folder:', { err, folder: sanitizedPath(rel) });
+      },
+    },
+  ]);
+  const removed: string[] = [];
+  const attempt = async (rel: string, remove: (abs: string) => Promise<void>): Promise<void> => {
+    try {
+      await remove(path.join(tmpDir, rel));
+      removed.push(rel);
+    } catch (err) {
+      // Gone mid-sweep is what the sweep wanted, and a folder something is
+      // still in stays; anything else spoils one entry, not the sweep.
+      const code = (err as { code?: unknown } | null)?.code;
+      if (!isAbsence(err) && code !== 'ENOTEMPTY' && code !== 'EEXIST') {
+        log.warn('could not sweep a tmp entry:', { err, entry: sanitizedPath(rel) });
+      }
+    }
+  };
+  for (const rel of entries) {
+    if (stopped()) return removed;
+    const stat = await entryStat(rel);
+    if (!stat || now - stat.mtimeMs <= maxAgeMs) continue;
+    // Asked again AFTER the awaited look: a stop that came while it ran
+    // removes nothing more, this entry included.
+    if (stopped()) return removed;
+    // A file, or a link removed as the link.
+    await attempt(rel, (abs) => fs.unlink(abs));
+  }
+  // Walk order lists a folder before what is in it, so the reverse is deepest first.
+  for (const rel of oldDirs.reverse()) {
+    if (stopped()) return removed;
+    await attempt(rel, (abs) => fs.rmdir(abs));
+  }
+  return removed;
+}
+
+/**
+ * The periodic sweep of every workspace's `tmp/` folder, on a timer.
+ *
+ * Started with the graph (`startCore`) and stopped with it (`stopCore`):
+ * stopping clears the timer and CANCELS the sweep in flight — its signal is
+ * aborted, so it removes nothing more and ends at the next entry it would
+ * have looked at — and `drainSweep` waits for it to end. `stopCore` bounds
+ * that wait by its own deadline, like every other drain there: a sweep stuck
+ * inside one filesystem call (a hung mount) can outlive the wait, but it
+ * removes nothing once that call returns. The first sweep runs at start, not
+ * one interval later, so what a previous process left past its age goes
+ * without waiting. The timer is `unref`'d: nothing here is worth keeping a
+ * process alive for.
+ */
+export class TmpSweeper {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private sweeping: Promise<void> | null = null;
+  private stop: AbortController | null = null;
+
+  constructor(private readonly sweep: (signal: AbortSignal) => Promise<unknown>) {}
+
+  /** Sweep now, and every `intervalMs` after. Idempotent. */
+  startSweeping(intervalMs: number = TMP_SWEEP_INTERVAL_MS): void {
+    if (this.timer) return;
+    this.stop = new AbortController();
+    this.tick();
+    this.timer = setInterval(() => this.tick(), intervalMs);
+    this.timer.unref?.();
+  }
+
+  /** Clear the timer and cancel the sweep in flight; {@link drainSweep} waits for it to end. */
+  stopSweeping(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    this.stop?.abort();
+    this.stop = null;
+  }
+
+  /** Wait for the sweep in flight, if any, to end. */
+  async drainSweep(): Promise<void> {
+    await this.sweeping;
+  }
+
+  /** One sweep, unless one is still running; its failure is logged. */
+  private tick(): void {
+    if (this.sweeping || !this.stop) return;
+    const running = this.sweep(this.stop.signal)
+      .then(() => undefined)
+      .catch((err: unknown) => log.warn('could not sweep the workspaces\' tmp folders:', { err }))
+      .finally(() => {
+        if (this.sweeping === running) this.sweeping = null;
+      });
+    this.sweeping = running;
+  }
+}

package/src/modules/workspace/workspace.routes.ts

@@ -3,7 +3,7 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('workspace.routes');
 import path from 'node:path';
-import { IGNORE_FILENAME, isAbsence, type ITreeWalker } from '../../shared/fs.contract.js';
+import { isAbsence, type ITreeWalker } from '../../shared/fs.contract.js';
 import { printable } from '../../shared/printable.js';
 import type { IAdminAccessService } from '../admin/index.js';
 import express from 'express';
@@ -652,7 +652,7 @@ export function createWorkspaceRoutes(
    */
   function buildTreeReadFilter(workspaceId: string, userEmail: string): ReadTreeFilter {
     return async (wsRelPaths) => {
-      const verdict: Map<string, boolean | 'unlisted'> = await resolveReadableMap(
+      const verdict: Map<string, boolean> = await resolveReadableMap(
         (w, e, rels) => accessControl.canReadBatch(w, e, rels),
         workspaceId,
         userEmail,
@@ -673,31 +673,10 @@ export function createWorkspaceRoutes(
         const rel = toKbRelative(wp, kbDirName);
         if (rel !== null && structuralRoots.has(rel)) verdict.set(wp, true);
       }
-
-      // `.bevelignore` is ADMIN-ONLY. It is the file that decides what the file
-      // tree and the agent view show at all, so it is deployment configuration
-      // rather than knowledge — and it sits alone in being visible: its
-      // siblings (`.gitignore`, `roles.yaml`, `access.md`, the agent guide) are
-      // already hidden from every reader by the shipped ignore rules. Somebody
-      // who cannot act on it gains a puzzle; somebody who can needs to reach it.
-      //
-      // Read permission is deliberately NOT the lever. Everyone can read it —
-      // it has to be readable to be applied — so hiding it is a listing
-      // decision, made here, rather than an ACL fiction maintained in a file.
-      //
-      // Resolved through `AdminAccessService` rather than by asking whether
-      // this caller can write `roles.yaml` in THIS workspace: admin is settled
-      // on the default branch precisely so that editing `roles.yaml` on your
-      // own branch cannot promote you, and the same reasoning applies to
-      // anything gated on being an admin.
-      //
-      // `'unlisted'`, not `false`: hiding it withholds no content, so a
-      // non-admin in an empty knowledge base (every one ships this file) is
-      // told it is empty, not that something is being kept from them.
-      const ignoreFiles = wsRelPaths.filter((wp) => path.basename(wp) === IGNORE_FILENAME);
-      if (ignoreFiles.length > 0 && !(await adminAccess.isAdmin(userEmail))) {
-        for (const wp of ignoreFiles) verdict.set(wp, 'unlisted');
-      }
+      // `.bevelignore` is listed like any other file: whoever may read it sees
+      // it. It used to be admins only (a listing decision, since everyone can
+      // read it) — Razvan reversed that on 2026-10-23: a reader who can open
+      // the file may find it in the tree.
       return verdict;
     };
   }