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

package/migrations/meta/_journal.json

@@ -155,6 +155,20 @@
       "when": 1792491290917,
       "tag": "0021_data_migrations_ledger",
       "breakpoints": true
+    },
+    {
+      "idx": 22,
+      "version": "7",
+      "when": 1792657514328,
+      "tag": "0022_session_version",
+      "breakpoints": true
+    },
+    {
+      "idx": 23,
+      "version": "7",
+      "when": 1793089896833,
+      "tag": "0023_agent_path",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, workflow (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,8 +55,8 @@
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-mcp-core": "0.33.0",
-    "@bevel-software/platform-shared": "0.33.0"
+    "@bevel-software/platform-mcp-core": "0.35.0",
+    "@bevel-software/platform-shared": "0.35.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",
@@ -68,6 +68,7 @@
     "@types/pg": "^8.20.0",
     "@types/qs": "^6.15.1",
     "drizzle-kit": "^0.31.10",
+    "js-tiktoken": "^1.0.21",
     "tsx": "^4.19.0",
     "typescript": "^5.8.0",
     "vitest": "^3.2.6"

package/src/__tests__/hexis-catalog.ts

@@ -0,0 +1,144 @@
+import express from 'express';
+import { codeModeMetaTools } from '@bevel-software/platform-mcp-core';
+import { testKbContext } from './kb-context.js';
+import { EXTERNAL_KB_MANUAL_NAME, registerToolManualsTools } from '../modules/tool-manuals/index.js';
+import { ToolRegistry, guideFirstDescription, type UtcpTool } from '../modules/tool-registry/index.js';
+import type { ToolAuth } from '../modules/tool-auth/index.js';
+import { RipgrepPatternMatcher, ToolDescriptionNotes } from '../modules/workspace/index.js';
+import { registerPluginsTools } from '../modules/plugins/index.js';
+import { registerSkillsTools } from '../modules/skills/index.js';
+import { agentGuideSections, registerAgentGuideTool } from '../modules/agent-guide/index.js';
+import {
+  RoutineWritePolicyService,
+  UuidSessionSink,
+  WorkflowHooks,
+  createToolHandlerFactory,
+  registerChangeRequestReadTools,
+  registerEmbedTools,
+  registerWorkflowTools,
+  registerWorkspaceTools,
+} from './tool-wiring.js';
+
+/**
+ * The tool catalog Hexis itself registers, built on stand-ins for the tests
+ * that read what an agent is TOLD: the description caps, the guide checks and
+ * the guide's budgets. Every registrar Hexis owns is mounted, because the
+ * definitions are the only thing under test: a stand-in that is never called
+ * is honest about that. Tools PROXIED from connected MCP servers are not here:
+ * their text is the other server's.
+ */
+
+/** Dependencies the registrars take but never touch while they are only building defs. */
+export const unused = <T,>(): T => ({}) as T;
+
+/** A `.tool` catalog with nothing in it: the shortest honest answer for a listing. */
+const emptyManuals = {
+  listLocalOnly: async () => [],
+  listAll: async () => [],
+  list: async () => [],
+  listInvalid: async () => [],
+} as unknown as Parameters<typeof registerToolManualsTools>[4];
+
+/** A skill catalog with nothing in it — the per-user skill line is then one fixed sentence. */
+export const emptySkills = { listSkills: async () => [] } as unknown as Parameters<typeof registerSkillsTools>[4];
+
+/**
+ * The meta-tools as the hosted endpoint builds them (`mcp.service.ts`):
+ * examples written against the namespace it registers the knowledge-base tools
+ * under and against the catalog it serves, and the chain without the rules it
+ * states only in the shared places. So the chain description measured here
+ * carries the worked call a client is really sent, which is its longest form.
+ */
+export function servedMetaTools(external: readonly UtcpTool[]) {
+  return codeModeMetaTools(
+    EXTERNAL_KB_MANUAL_NAME,
+    external.map((t) => ({ utcpName: `${EXTERNAL_KB_MANUAL_NAME}.${t.name}`, inputSchema: t.inputs })),
+    { sharedRulesPointer: '' },
+    // As the hosted endpoint serves them: opening with the guide-first
+    // sentence, through the one helper the endpoint itself uses.
+  ).map((t) => ({ ...t, description: guideFirstDescription(t.description) }));
+}
+
+/**
+ * Every tool Hexis itself registers, by surface: what the in-process agent is
+ * handed, what the hosted endpoint lists to an MCP client, and the three
+ * meta-tools it lists beside them.
+ */
+export async function hexisCatalog(
+  skills: Parameters<typeof registerSkillsTools>[4] = emptySkills,
+): Promise<{ internal: UtcpTool[]; external: UtcpTool[]; metaTools: ReturnType<typeof servedMetaTools> }> {
+  const registry = new ToolRegistry();
+  const router = express.Router();
+  const toolAuth = ((_req, _res, next) => next()) as unknown as ToolAuth;
+  const toolHandler = createToolHandlerFactory(unused());
+  const kb = testKbContext();
+  const gate = { recoveryBotEmail: 'bot@x', hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() };
+
+  // The change-request readers come first, as the root mounts them: they
+  // gate their whole payload on the caller's read access and take the access
+  // service and nothing else.
+  registerChangeRequestReadTools(registry, router, toolAuth, toolHandler, unused(), kb);
+  const workspaceTools = registerWorkspaceTools(
+    registry,
+    router,
+    toolAuth,
+    toolHandler,
+    unused(),
+    unused(),
+    unused(),
+    kb,
+    gate,
+    new RoutineWritePolicyService(),
+    new UuidSessionSink(),
+    undefined,
+    undefined,
+    // The two upload tools are mounted only when a store is supplied, and
+    // every real composition supplies one: without it they would be the two
+    // descriptions this suite never measured.
+    unused(),
+    // The guide reader, not needed to build defs; then the download store,
+    // mounted on the same terms as the upload one.
+    undefined,
+    unused(),
+    // Starter packs and the tree walk, not needed; then the grep matcher,
+    // mounted on the same terms (it spawns no worker until a search runs).
+    undefined,
+    undefined,
+    new RipgrepPatternMatcher(),
+  );
+  registerWorkflowTools(registry, router, toolAuth, toolHandler, kb, async () => true, { canRead: async () => true, canReadAtRef: async () => true, canReadBatch: async () => new Map(), canReadBatchAtRef: async () => new Map(), canWrite: async () => true } as never, { recoveryBotEmail: 'recovery@x', hooks: { runAgentRead: async () => undefined }, notes: { onChange: () => undefined } } as never);
+  registerPluginsTools(registry, kb);
+  registerSkillsTools(registry, router, toolAuth, toolHandler, skills);
+  registerToolManualsTools(registry, router, toolAuth, toolHandler, emptyManuals, {
+    accessControl: unused(),
+    variableStatus: unused(),
+    kb,
+  });
+  // `open_page`, on the file tools' router with `read_file`'s own read, as the
+  // root mounts it; its stand-ins answer nothing, since only its def is read.
+  registerEmbedTools(registry, router, toolAuth, toolHandler, {
+    embedService: unused(),
+    kb,
+    readForTool: workspaceTools.readForTool,
+    canBeReached: () => true,
+    appUrlFor: () => '',
+    notes: gate.notes,
+  });
+  // The guide's own tool, with the platform's sections: the one description
+  // that lists the sections is measured with the list it really carries.
+  registerAgentGuideTool(registry, router, toolAuth, toolHandler, () => agentGuideSections(kb.layout));
+
+  // The meta-tools as a client is served them (`mcp.service.ts` opens each
+  // with the guide-first sentence at the mount), so the catalog measured here
+  // is the catalog that goes out rather than the bare constant.
+  const external = (await registry.listExternal()) as UtcpTool[];
+  return { internal: (await registry.listInternal()) as UtcpTool[], external, metaTools: servedMetaTools(external) };
+}
+
+/** Every tool Hexis itself registers, on both surfaces, deduplicated by name. */
+export async function hexisTools(skills: Parameters<typeof registerSkillsTools>[4] = emptySkills): Promise<UtcpTool[]> {
+  const { internal, external, metaTools } = await hexisCatalog(skills);
+  const byName = new Map<string, UtcpTool>();
+  for (const tool of [...internal, ...external, ...metaTools]) byName.set(tool.name, tool as UtcpTool);
+  return [...byName.values()];
+}

package/src/__tests__/pg-scratch.test.ts

@@ -0,0 +1,69 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+/**
+ * `openMigratedScratchDb` owns the pool it opens until it hands the handle
+ * over: when the migrations fail, the caller never receives `close`, so the
+ * helper must close the pool itself and let the error through. No Postgres
+ * here — the connection, the migrations and the `pg` admin client are stubs,
+ * since the subject is the helper's ownership of what it opened, not the
+ * database.
+ */
+
+const stubs = vi.hoisted(() => ({
+  db: { kind: 'fake-db' },
+  createDb: vi.fn(),
+  closeDb: vi.fn(async () => {}),
+  runCoreMigrations: vi.fn(async () => {}),
+  adminQuery: vi.fn(async () => ({ rows: [] })),
+}));
+
+vi.mock('../modules/database/connection.js', () => ({
+  createDb: stubs.createDb,
+  closeDb: stubs.closeDb,
+}));
+vi.mock('../modules/database/migrate.js', () => ({
+  runCoreMigrations: stubs.runCoreMigrations,
+}));
+vi.mock('../assets.js', () => ({ coreMigrationsDir: () => '/migrations' }));
+vi.mock('pg', () => ({
+  default: {
+    Client: class {
+      connect = async () => {};
+      query = stubs.adminQuery;
+      end = async () => {};
+    },
+  },
+}));
+
+// Read once, at import: a URL the stubbed admin client will never dial.
+process.env.TEST_DATABASE_URL = 'postgres://scratch:scratch@127.0.0.1:1/admin';
+const { openMigratedScratchDb } = await import('./pg-scratch.js');
+
+describe('openMigratedScratchDb', () => {
+  beforeEach(() => {
+    stubs.createDb.mockReturnValue(stubs.db);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+    stubs.runCoreMigrations.mockResolvedValue(undefined);
+  });
+
+  it('hands the migrated database over with a close the caller owns', async () => {
+    const opened = await openMigratedScratchDb('hexis_owned');
+    expect(opened.db).toBe(stubs.db);
+    expect(stubs.runCoreMigrations).toHaveBeenCalledWith(stubs.db, '/migrations');
+    // The pool stays open until the caller closes it.
+    expect(stubs.closeDb).not.toHaveBeenCalled();
+    await opened.close();
+    expect(stubs.closeDb).toHaveBeenCalledWith(stubs.db);
+  });
+
+  it('closes the pool it opened when the migrations fail, and lets the failure through', async () => {
+    stubs.runCoreMigrations.mockRejectedValueOnce(new Error('migration 0022 failed'));
+    await expect(openMigratedScratchDb('hexis_failed')).rejects.toThrow('migration 0022 failed');
+    // Closed by the helper: the caller never received a handle to close.
+    expect(stubs.closeDb).toHaveBeenCalledTimes(1);
+    expect(stubs.closeDb).toHaveBeenCalledWith(stubs.db);
+  });
+});

package/src/__tests__/pg-scratch.ts

@@ -1,5 +1,8 @@
 import { randomBytes } from 'node:crypto';
 import pg from 'pg';
+import { closeDb, createDb, type Database } from '../modules/database/connection.js';
+import { runCoreMigrations } from '../modules/database/migrate.js';
+import { coreMigrationsDir } from '../assets.js';
 
 /**
  * The one fixture for tests that cross a real Postgres. They run where
@@ -9,6 +12,11 @@ import pg from 'pg';
  * of its own, made by {@link scratchDatabaseUrl} and dropped by
  * {@link dropScratchDatabases}; the database the URL names is only connected
  * to, never written.
+ *
+ * A test that wants the schema as a deployment has it opens the database
+ * through {@link openMigratedScratchDb}: this fixture is the one place
+ * outside the database module that knows how a core database is connected
+ * to and migrated, so a module's test need not import those files itself.
  */
 export const PG_ADMIN_URL = process.env.TEST_DATABASE_URL;
 
@@ -38,6 +46,29 @@ export async function scratchDatabaseUrl(prefix: string): Promise<string> {
   return url.toString();
 }
 
+/**
+ * A scratch database at the current core schema — created, connected to with
+ * the PII key given (a fresh random one when none is), and every core
+ * migration run — as a module's test wants it. `close` ends the connection;
+ * {@link dropScratchDatabases} drops the database afterwards as for any other.
+ */
+export async function openMigratedScratchDb(
+  prefix: string,
+  opts: { piiKey?: string } = {},
+): Promise<{ db: Database; close: () => Promise<void> }> {
+  const piiKey = opts.piiKey ?? randomBytes(32).toString('base64');
+  const db = createDb(await scratchDatabaseUrl(prefix), { piiKey });
+  try {
+    await runCoreMigrations(db, coreMigrationsDir());
+  } catch (err) {
+    // The caller never receives the handle on this path, so the pool is
+    // closed here; the database itself is dropped with the others.
+    await closeDb(db);
+    throw err;
+  }
+  return { db, close: () => closeDb(db) };
+}
+
 /** Drop every scratch database this file made; for `afterAll`, with {@link PG_TEST_TIMEOUT}. */
 export async function dropScratchDatabases(): Promise<void> {
   const names = created.splice(0);

package/src/__tests__/real-disk.ts

@@ -0,0 +1,21 @@
+import { NodeFs } from '../modules/kb-fs/node-fs.js';
+import { KbPluginSource } from '../modules/plugins/index.js';
+import type { KbContext } from '../shared/kb-context.js';
+
+/**
+ * The real disk, and the plugin source that reads it, wired the way the
+ * composition root wires them (`core/create-core-services.ts`: one `NodeFs`,
+ * one `KbPluginSource` over it). A module's suite that drives its service over
+ * real files takes them from HERE rather than constructing another module's
+ * implementation itself: the root is the one place that knows those files
+ * (`NodeFs` is on no module entry, by design — a filesystem arrives by
+ * injection), and this fixture stands in for the root, as `kb-context.ts`
+ * does for the knowledge-base context.
+ */
+export function realDisk(): NodeFs {
+  return new NodeFs();
+}
+
+export function realPluginSource(disk: NodeFs, kb: KbContext): KbPluginSource {
+  return new KbPluginSource(disk, kb);
+}

package/src/__tests__/slow-ripgrep.ts

@@ -0,0 +1,65 @@
+import { execFile } from 'node:child_process';
+import { chmod, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { promisify } from 'node:util';
+
+/**
+ * A ripgrep that never finishes a TREE search, for the suites about the
+ * search budget and about stopping: an `rg` put first on this process's PATH,
+ * where the server finds its ripgrep. A run reading stdin (the pattern check,
+ * a document's text) is handed to the real `rg`, so a pattern is judged as it
+ * always is; a walk records its process id and sleeps for a minute, which no
+ * budget waits out — or, given `walkMs`, sleeps that long and then finishes
+ * having found nothing, which is how a suite spends a budget in parts.
+ *
+ * `alive()` answers which of the walks it started are still running, so a
+ * suite can assert that a stopped search left no process behind. `remove()`
+ * puts the PATH back.
+ */
+export interface SlowRipgrep {
+  alive(): Promise<number[]>;
+  remove(): Promise<void>;
+}
+
+export async function slowRipgrep(opts: { walkMs?: number } = {}): Promise<SlowRipgrep> {
+  const seconds = opts.walkMs === undefined ? '60' : (opts.walkMs / 1000).toFixed(3);
+  const real = (await promisify(execFile)('sh', ['-c', 'command -v rg'])).stdout.trim();
+  const dir = await mkdtemp(join(tmpdir(), 'slow-rg-'));
+  const pids = join(dir, 'pids');
+  const binary = join(dir, 'rg');
+  await writeFile(
+    binary,
+    [
+      '#!/bin/sh',
+      'for a in "$@"; do last="$a"; done',
+      `if [ "$last" = "-" ]; then exec '${real}' "$@"; fi`,
+      `echo $$ >> '${pids}'`,
+      `exec sleep ${seconds}`,
+      '',
+    ].join('\n'),
+  );
+  await chmod(binary, 0o755);
+  const path = process.env.PATH;
+  process.env.PATH = `${dir}${delimiter}${path ?? ''}`;
+  return {
+    async alive() {
+      const started = (await readFile(pids, 'utf8').catch(() => ''))
+        .split('\n')
+        .filter(Boolean)
+        .map(Number);
+      return started.filter((pid) => {
+        try {
+          process.kill(pid, 0);
+          return true;
+        } catch {
+          return false;
+        }
+      });
+    },
+    async remove() {
+      process.env.PATH = path;
+      await rm(dir, { recursive: true, force: true });
+    },
+  };
+}

package/src/__tests__/tokens.ts

@@ -0,0 +1,19 @@
+import { Tiktoken } from 'js-tiktoken/lite';
+import o200kBase from 'js-tiktoken/ranks/o200k_base';
+import { GUIDE_TOKEN_ENCODING } from '../modules/agent-guide/index.js';
+
+/**
+ * Token counts for the tests that hold agent-facing text to a budget
+ * (`modules/agent-guide/guide-budget.ts`): a real BPE tokenizer, offline and
+ * deterministic, so a count in CI is the count on a laptop. Built once: the
+ * rank table is large and the counts never change between calls.
+ */
+const encoder = new Tiktoken(o200kBase);
+
+if (GUIDE_TOKEN_ENCODING !== 'o200k_base') {
+  throw new Error(`The budgets name ${GUIDE_TOKEN_ENCODING}, but the counter is built on o200k_base.`);
+}
+
+export function countTokens(text: string): number {
+  return encoder.encode(text).length;
+}

package/src/__tests__/tool-manuals.ts

@@ -0,0 +1,32 @@
+import { ToolManualService, type McpAuthDiscoveryPort } from '../modules/tool-manuals/tool-manuals.service.js';
+import type { IAccessControl } from '../modules/access/index.js';
+import type { WorkspaceService } from '../modules/workspace/index.js';
+import type { KbContext } from '../shared/kb-context.js';
+import { realDisk, realPluginSource } from './real-disk.js';
+
+export type { McpAuthDiscoveryPort };
+
+/**
+ * The tool-manual service over real files, wired the way the composition root
+ * wires it (`core/create-core-services.ts`): the real disk, the plugin source
+ * reading that same disk, and the discovery port set afterwards. A suite that
+ * drives the service over real tool files takes it from HERE and never
+ * constructs the class from its file — the class is on no module entry (a
+ * service arrives by injection), and this fixture stands in for the root, as
+ * `kb-context.ts` and `real-disk.ts` do for what they wire.
+ */
+export function realToolManualService(
+  deps: {
+    workspaceService: WorkspaceService;
+    accessControl: IAccessControl;
+    kb: KbContext;
+    /** The disk the suite writes its files to; the service reads the same one. */
+    disk?: ReturnType<typeof realDisk>;
+  },
+  discovery?: McpAuthDiscoveryPort,
+): ToolManualService {
+  const disk = deps.disk ?? realDisk();
+  const svc = new ToolManualService(deps.workspaceService, deps.accessControl, deps.kb, disk, realPluginSource(disk, deps.kb));
+  if (discovery) svc.setMcpAuthDiscovery(discovery);
+  return svc;
+}

package/src/__tests__/tool-wiring.ts

@@ -0,0 +1,25 @@
+/**
+ * The pieces the composition root wires from module internals, for a suite
+ * that builds a tool surface the way `core/create-core-server.ts` does: the
+ * handler factory and context resolver, the tool-auth middleware, the two
+ * registrars that take their dependencies by hand, the session sink, the
+ * routine write policy, the access resolver and the workflow hooks.
+ *
+ * A module's entry holds its contracts, and a suite asserts through entries.
+ * These are not contracts: they are what the root composes, so a suite that
+ * needs them reaches them here, the one root fixture that imports past the
+ * entries, as the root itself does. A suite that imports one of these files
+ * directly is a second wiring that drifts from the root's.
+ */
+export { createToolHandlerFactory } from '../modules/tool-helpers/tool-handler.js';
+export { createToolContextResolver } from '../modules/tool-helpers/tool-context.js';
+export { createToolAuthMiddleware } from '../modules/tool-auth/tool-auth.middleware.js';
+export { InternalTokenService } from '../modules/tool-auth/internal-token.service.js';
+export { registerWorkspaceTools } from '../modules/workspace/workspace.tools.js';
+export { registerWorkflowTools } from '../modules/workflow/agent-tools/workflow.tools.js';
+export { registerChangeRequestReadTools } from '../modules/workflow/agent-tools/change-request-read.tools.js';
+export { registerEmbedTools } from '../modules/embed/embed.tools.js';
+export { UuidSessionSink } from '../modules/workspace/session-sink.js';
+export { RoutineWritePolicyService } from '../modules/workspace/routine-write-policy.js';
+export { AccessControlService, loadActiveGroups } from '../modules/access/access-control.service.js';
+export { WorkflowHooks, type AgentOperationContext } from '../modules/workflow/workflow-hooks.js';

package/src/core/__tests__/boot-without-ripgrep.test.ts

@@ -0,0 +1,34 @@
+import { execFile } from 'node:child_process';
+import { mkdtemp, rm, symlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { afterEach, describe, expect, it } from 'vitest';
+import { createCoreServices } from '../../index.js';
+import type { TenantConfig } from '../../core-config.js';
+
+/**
+ * The server's boot, through the package's own entry, on a PATH that carries
+ * git and no ripgrep: it refuses to build any service, naming the binary.
+ */
+describe('booting without ripgrep', () => {
+  const path = process.env.PATH;
+  let bin = '';
+  afterEach(async () => {
+    process.env.PATH = path;
+    if (bin) await rm(bin, { recursive: true, force: true });
+    bin = '';
+  });
+
+  it('refuses to start, naming rg and the Dockerfile that installs it', async () => {
+    const git = (await promisify(execFile)('sh', ['-c', 'command -v git'])).stdout.trim();
+    bin = await mkdtemp(join(tmpdir(), 'no-rg-'));
+    await symlink(git, join(bin, 'git'));
+    process.env.PATH = bin;
+    // The binaries are checked before the configuration is read, so none is needed.
+    const err = (await createCoreServices({} as TenantConfig).catch((e: unknown) => e)) as Error;
+    expect(err).toBeInstanceOf(Error);
+    expect(err.message).toMatch(/^ripgrep \(`rg`\) is required on the server's PATH but could not be run: .*ENOENT/);
+    expect(err.message).toContain('The Hexis Dockerfile installs it');
+  });
+});

package/src/core/__tests__/catalog-revision.test.ts

@@ -4,6 +4,7 @@ import type { Server } from 'node:http';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import type { SkillSummary } from '../../modules/skills/skills.contract.js';
 import { catalogRevision, createCatalogRevisionRoutes } from '../catalog-revision.js';
+import { agentFile, agentScopeOver, inMemoryKb, type InMemoryKb } from '../../modules/agent-scope/__tests__/in-memory-kb.js';
 
 /**
  * The fingerprint a long-lived client polls to learn that the released catalog
@@ -228,3 +229,91 @@ describe('GET /agent/catalog-revision', () => {
     expect(await res.json()).toEqual({ revision: catalogRevision([], []), tools: 0, skills: 0 });
   });
 });
+
+describe('GET /agent/catalog-revision, for a connection made as an .agent file', () => {
+  let http: Server | null = null;
+
+  afterEach(async () => {
+    if (http) await new Promise<void>((resolve) => http!.close(() => resolve()));
+    http = null;
+  });
+
+  const lines = [
+    ['ops', 'ops', 'Plugins/Ops/ops.tool', 'http', 'remote', '', 's'].join('\u0000'),
+    ['crm', 'crm', 'Plugins/Sales/crm.tool', 'http', 'remote', '', 's'].join('\u0000'),
+  ];
+  const paths = ['Plugins/Ops/ops.tool', 'Plugins/Sales/crm.tool'];
+  const skills = [skill({ name: 'notes', path: 'Skills/Release/notes' }), skill({ name: 'pitch', path: 'Skills/Sales/pitch' })];
+
+  async function mount(kb: InMemoryKb, agentPath: string | undefined) {
+    // The two services narrow by the predicate they are handed, AFTER their
+    // own read gate — stood in for here by the lists above, all readable.
+    const catalogFingerprints = vi.fn(async (_email: string, within?: (p: string) => boolean) =>
+      lines.filter((_, i) => !within || within(paths[i]!)),
+    );
+    const listSkills = vi.fn(async (_email: string, opts?: { within?: (p: string) => boolean }) =>
+      skills.filter((s) => !opts?.within || opts.within(s.path)),
+    );
+    const agentScope = agentScopeOver(kb);
+    const resolve = vi.spyOn(agentScope, 'resolve');
+    const app = express();
+    app.use(
+      createCatalogRevisionRoutes({
+        toolManuals: { catalogFingerprints } as never,
+        skills: { listSkills } as never,
+        manualAuth: (req, _res, next) => {
+          req.toolAuth = { userId: 'u1', ...(agentPath ? { agentPath } : {}) } as never;
+          next();
+        },
+        resolveUserEmail: async () => 'ada@example.com',
+        agentScope,
+      }),
+    );
+    http = app.listen(0);
+    await new Promise<void>((r) => http!.once('listening', r));
+    const url = `http://127.0.0.1:${(http.address() as AddressInfo).port}/agent/catalog-revision`;
+    const read = async () =>
+      (await (await fetch(url)).json()) as { revision: string; tools: number; skills: number; connection?: unknown };
+    return { read, catalogFingerprints, listSkills, resolve };
+  }
+
+  it('Everything is the revision it always was: nothing resolved, nothing narrowed, no `connection`', async () => {
+    const { read, catalogFingerprints, listSkills, resolve } = await mount(inMemoryKb({}), undefined);
+    expect(await read()).toEqual({ revision: catalogRevision(lines, skills), tools: 2, skills: 2 });
+    expect(catalogFingerprints).toHaveBeenCalledWith('ada@example.com');
+    expect(listSkills).toHaveBeenCalledWith('ada@example.com');
+    expect(resolve).not.toHaveBeenCalled();
+  });
+
+  it("is the fingerprint of what the agent loads, and names the agent", async () => {
+    const kb = inMemoryKb({ 'Agents/ops.agent': agentFile('name: ops\nconnectors: [Plugins/Ops]\nskills: [Skills/Release]') });
+    const { read } = await mount(kb, 'Agents/ops.agent');
+    const body = await read();
+    expect(body.tools).toBe(1);
+    expect(body.skills).toBe(1);
+    expect(body.connection).toEqual({ agent: { path: 'Agents/ops.agent', name: 'ops' } });
+    expect(body.revision).not.toBe(catalogRevision(lines, skills));
+  });
+
+  it('moves at the next read after the .agent file is edited — no reconnect', async () => {
+    const kb = inMemoryKb({ 'Agents/ops.agent': agentFile('connectors: [Plugins/Ops]') });
+    const { read } = await mount(kb, 'Agents/ops.agent');
+    const before = await read();
+    expect(await read()).toEqual(before);
+    kb.files.set('Agents/ops.agent', agentFile('connectors: [Plugins/Ops]\nskills: [Skills/Sales]'));
+    const after = await read();
+    expect(after.revision).not.toBe(before.revision);
+    expect(after.skills).toBe(1);
+    // Even an edit that changes nothing listed moves it: the file is the configuration.
+    kb.files.set('Agents/ops.agent', agentFile('connectors: [Plugins/Ops]\nskills: [Skills/Sales]\ndescription: now described'));
+    expect((await read()).revision).not.toBe(after.revision);
+  });
+
+  it('a deleted file is an empty catalog with the reason, never Everything', async () => {
+    const { read } = await mount(inMemoryKb({}), 'Agents/gone.agent');
+    const body = await read();
+    expect(body.tools).toBe(0);
+    expect(body.skills).toBe(0);
+    expect((body.connection as { unavailable?: string }).unavailable).toMatch(/no longer exists or which you can no longer read/);
+  });
+});

package/src/core/__tests__/damaged-document.tools.test.ts

@@ -16,7 +16,7 @@ import { RoutineWritePolicyService } from '../../modules/workspace/routine-write
 import { WorkflowHooks } from '../../modules/workflow/workflow-hooks.js';
 import { ToolDescriptionNotes } from '../../modules/workspace/agent-access.gate.js';
 import { SpillStore } from '../../modules/workspace/spill-store.js';
-import { WorkerPatternMatcher } from '../../modules/workspace/bounded-matcher.js';
+import { RipgrepPatternMatcher } from '../../modules/workspace/index.js';
 import { DocExtractService, type UnreadableDocument } from '../../modules/workspace/file-readers/doc-extract.service.js';
 import type { IDocumentExtractor } from '../../modules/workspace/file-readers/document-extractor.contract.js';
 import { WorkerDocumentExtractor, type WorkerDocumentExtractorOptions } from '../../modules/workspace/file-readers/extract-in-worker.js';
@@ -82,7 +82,7 @@ async function startPlatform(extractorOpts: WorkerDocumentExtractorOptions = {})
   };
   const told: UnreadableDocument[] = [];
   const docExtract = new DocExtractService(join(tempDir, '.doc-extract'), counting, { onUnreadable: (d) => told.push(d) });
-  const matcher = new WorkerPatternMatcher();
+  const matcher = new RipgrepPatternMatcher();
 
   const registry = new ToolRegistry();
   const resolve = async (auth: ToolAuth, signal: AbortSignal, sessionId?: string): Promise<ToolContext> => ({

package/src/core/__tests__/gated-boot.test.ts

@@ -37,7 +37,7 @@ afterEach(async () => {
 
 /** A core whose startup phase fails in a way the test picks. */
 function bootable(runAll: () => Promise<void>) {
-  const retries = { started: 0 };
+  const retries = { started: 0, tmpSweeps: 0 };
   const core: BootableCore = {
     config: { workspacesRoot },
     kbDirName: 'knowledge-base',
@@ -53,6 +53,11 @@ function bootable(runAll: () => Promise<void>) {
       tidyAfterSweep: async () => ({ closedEmpty: 0, removedLeftovers: 0 }),
     } as BootableCore['workflowService'],
     pluginJoinRequestJobs: { startSweeping() {} } as BootableCore['pluginJoinRequestJobs'],
+    tmpSweeper: {
+      startSweeping() {
+        retries.tmpSweeps += 1;
+      },
+    },
     startupRetry: null,
   };
   return { core, retries };
@@ -79,6 +84,8 @@ describe('startCore over a repository the host will not serve', () => {
     // that is granted access to it, needs no settings change on this side.
     expect(retries.started).toBe(1);
     expect(core.startupRetry).not.toBeNull();
+    // The tmp sweep reads the workspaces root alone, so a gated boot still runs it.
+    expect(retries.tmpSweeps).toBe(1);
   });
 
   it('comes up gated when the host rejected the credentials', async () => {