@bevel-software/platform-core-backend 0.28.1 → 0.30.0

package/mcp-app/page.html

@@ -72,6 +72,26 @@
          * owns the view; later ones are ignored.
          */
         var loading = false;
+        /**
+         * What the view calls `open_page` with to renew its token: the path
+         * and heading the result that owns the view echoed. Null until then,
+         * and when the result echoed no path (nothing to ask for).
+         */
+        var pageArgs = null;
+        /** The deployment the owning result named; a renewed token must name the same one. */
+        var deployment = null;
+        /**
+         * Whether the host runs a server tool for the view (`tools/call`,
+         * app to host): true or false when the handshake's reply said so in
+         * `hostCapabilities.serverTools`, null when it said nothing — then
+         * the view tries once, and a refusal is the answer.
+         */
+        var serverTools = null;
+        /** Replies the view is waiting for, by request id. */
+        var pending = {};
+        var callCount = 0;
+        /** The one renewal in flight, shared by every call refused meanwhile. */
+        var renewing = null;
 
         /** The name the deployment's Vite build gives the embed entry. */
         var EMBED_ENTRY = 'embed';
@@ -90,6 +110,14 @@
          * part of the conversation rather than the whole screen.
          */
         var PREFERRED_HEIGHT = 640;
+        /** The tool that minted the token, and the one that renews it. */
+        var OPEN_PAGE_TOOL = 'open_page';
+        /**
+         * How long a renewal waits for the host before it gives up and the
+         * view says it has expired. A host that never answers must not leave
+         * a save spinning.
+         */
+        var RENEW_TIMEOUT_MS = 20000;
 
         function send(message) {
           // The host is this view's parent; it told us its origin on the
@@ -128,6 +156,87 @@
           });
         }
 
+        /**
+         * Ask the host to call one of this server's tools for the view, over
+         * the connection the chat already holds — and so as the identity
+         * that connection authenticated. Resolves with the CallToolResult;
+         * rejects when the host refuses or does not answer in time.
+         */
+        function callServerTool(name, args) {
+          return new Promise(function (resolve, reject) {
+            callCount += 1;
+            var id = 'call-' + callCount;
+            var timer = setTimeout(function () {
+              delete pending[id];
+              var silent = new Error('the chat app did not answer');
+              silent.timedOut = true;
+              reject(silent);
+            }, RENEW_TIMEOUT_MS);
+            pending[id] = function (message) {
+              clearTimeout(timer);
+              delete pending[id];
+              if (message.error || !message.result) reject(message.error || new Error('no result'));
+              else resolve(message.result);
+            };
+            send({ jsonrpc: '2.0', id: id, method: 'tools/call', params: { name: name, arguments: args } });
+          });
+        }
+
+        /**
+         * A fresh token for the page this view shows, or null when there is
+         * none to be had. The view cannot mint one — minting needs the
+         * identity, which lives on the chat's connection — so it asks the
+         * host to call `open_page` again for the same path and heading and
+         * takes the token out of the `embedUrl` it answers. That call goes
+         * through `open_page`'s own gate: a reader whose access was
+         * withdrawn is refused there exactly as on a first call, and gets
+         * null here.
+         *
+         * Null without asking when the host said it runs no server tools for
+         * a view, or after a host that said nothing refused once. The bundle
+         * calls this at most once per refused call (see `embed-config.ts`).
+         */
+        function renew() {
+          if (renewing) return renewing;
+          if (serverTools === false || !pageArgs || !deployment) return Promise.resolve(null);
+          // Every Hexis tool takes its arguments under `body`; flat ones are
+          // refused ("takes its arguments under body") and no token comes back.
+          renewing = callServerTool(OPEN_PAGE_TOOL, { body: pageArgs })
+            .then(
+              function (result) {
+                var data = (result && result.structuredContent) || {};
+                if (result && result.isError) return null;
+                var url;
+                try {
+                  url = new URL(data.embedUrl);
+                } catch (err) {
+                  return null;
+                }
+                // The same deployment, or nothing: the bundle already runs
+                // against this one, and its API is the token's.
+                if (baseOf(url) !== deployment) return null;
+                var token = url.searchParams.get('token');
+                if (!token) return null;
+                var handoff = window[HANDOFF_GLOBAL];
+                if (handoff && typeof handoff === 'object') handoff.token = token;
+                return token;
+              },
+              function (err) {
+                // The host refused the call: one that said nothing about
+                // server tools has now said no. One that did not answer in
+                // time has said nothing, and is asked again on the next
+                // refused call.
+                if (serverTools === null && !(err && err.timedOut)) serverTools = false;
+                return null;
+              },
+            )
+            .then(function (token) {
+              renewing = null;
+              return token;
+            });
+          return renewing;
+        }
+
         /** The text blocks of a CallToolResult, one line each. */
         function textOf(result) {
           var out = [];
@@ -226,8 +335,15 @@
           }
           if (loading) return;
           loading = true;
+          deployment = base;
+          // What the view calls `open_page` with again when the token runs
+          // out: the arguments this result was answered for, as it echoed them.
+          if (typeof data.path === 'string' && data.path) {
+            pageArgs = { path: data.path };
+            if (typeof data.heading === 'string' && data.heading) pageArgs.heading = data.heading;
+          }
           // The handoff, before the bundle: it reads this the moment it runs.
-          window[HANDOFF_GLOBAL] = { baseUrl: base, token: token, openLink: openLink };
+          window[HANDOFF_GLOBAL] = { baseUrl: base, token: token, openLink: openLink, renew: renew };
 
           fetch(base + MANIFEST_PATH, { credentials: 'omit' })
             .then(function (res) {
@@ -302,6 +418,13 @@
           if (event.source !== window.parent) return;
           if (hostOrigin === null && event.origin) hostOrigin = event.origin;
 
+          // A reply to a request the view sent (a server tool call): it has
+          // the request's id and no method of its own.
+          if (!message.method && typeof message.id === 'string' && pending[message.id]) {
+            pending[message.id](message);
+            return;
+          }
+
           if (message.method === 'ui/notifications/tool-result') {
             // The params ARE the CallToolResult. A `result` wrapper is
             // accepted too, for a host that wrapped it.
@@ -314,16 +437,25 @@
             // whole of the layout; nothing to recompute.
             return;
           }
-          // The handshake's reply carries the host's capabilities. Nothing
-          // here depends on them, but a host that sends the first tool result
-          // only after the handshake completes needs us to have sent it.
-          if (message.id === INITIALIZE_ID) {
+          // The handshake's reply carries the host's capabilities. The one
+          // read here is `serverTools`: whether the host runs this server's
+          // tools for the view, which is how the view renews its token. And a
+          // host that sends the first tool result only after the handshake
+          // completes needs us to have sent it.
+          if (!message.method && message.id === INITIALIZE_ID) {
             // A rejected handshake is not advertised as ready — and the
             // reader is told, rather than left at "Opening the page…".
             if (message.error || !message.result) {
               if (!shown) say('The chat app refused to open this page.');
               return;
             }
+            // Only a `serverTools` the host named decides: present is yes,
+            // false or null is no. Capabilities that leave it out have said
+            // nothing about it, and the view tries once.
+            var caps = message.result.hostCapabilities;
+            if (caps && typeof caps === 'object' && caps.serverTools !== undefined) {
+              serverTools = !!caps.serverTools;
+            }
             send({ jsonrpc: '2.0', method: 'ui/notifications/initialized', params: {} });
             if (!shown) say('Opening the page…');
           }
@@ -337,9 +469,11 @@
           params: {
             protocolVersion: '2026-01-26',
             appInfo: { name: 'hexis-knowledge-page', version: '1.0.0' },
-            // Asks the host for nothing: no tool calls, no messages, no
-            // model context. Links go out through ui/open-link, which every
-            // host offers.
+            // Declares nothing. The extension has no way for a view to say
+            // it CALLS server tools (`tools` here would mean the view
+            // exposes tools of its own); whether the host runs them for a
+            // view is the host's to say, in the reply's `serverTools`.
+            // Links go out through ui/open-link, which every host offers.
             appCapabilities: {},
           },
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.28.1",
+  "version": "0.30.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.28.1",
-    "@bevel-software/platform-shared": "0.28.1"
+    "@bevel-software/platform-mcp-core": "0.30.0",
+    "@bevel-software/platform-shared": "0.30.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/__tests__/test-repositories.ts

@@ -0,0 +1,22 @@
+import fs from 'node:fs/promises';
+
+/**
+ * The repository roots `testKbRepository` placed beside a suite's workspaces
+ * root (`<workspacesRoot>.repository`). A suite removes its fixture root, not
+ * what sits next to it, so `test-setup.ts` removes these once the file's
+ * suites are done. Kept free of imports so the setup file can load it without
+ * pulling in a module a suite means to mock.
+ */
+const roots = new Set<string>();
+
+export function recordTestRepositoryRoot(root: string): void {
+  roots.add(root);
+}
+
+export async function removeTestRepositoryRoots(): Promise<void> {
+  const pending = [...roots];
+  roots.clear();
+  await Promise.all(
+    pending.map((root) => fs.rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 })),
+  );
+}

package/src/__tests__/workspace-service.ts

@@ -0,0 +1,69 @@
+import path from 'node:path';
+import { NodeGitRunner } from '../modules/workflow/git/node-git-runner.js';
+import type { IGitRunner } from '../shared/git.contract.js';
+import type { ITreeWalker } from '../shared/fs.contract.js';
+import type { KbContext } from '../shared/kb-context.js';
+import { KbRepository, repositoryDirFor } from '../modules/workspace/kb-repository.js';
+import type { IKbRepository } from '../modules/workspace/kb-repository.contract.js';
+import { WorkspaceService } from '../modules/workspace/workspace.service.js';
+import { KbStartupRunner, type KbStartupRunnerOptions } from '../modules/workspace/startup/kb-startup-runner.js';
+import { recordTestRepositoryRoot } from './test-repositories.js';
+
+/**
+ * The repository a suite's services share when it builds them by hand: one
+ * next to the workspaces root (see `repositoryDirFor`), as the composition
+ * root would place it there for a deployment with no backups root. Removed
+ * once the file's suites are done (see `test-repositories.ts`): a suite's
+ * teardown removes its fixture root, not what sits beside it.
+ */
+export function testKbRepository(
+  workspacesRoot: string,
+  kbDirName: string,
+  kbRepoUrl: string | (() => string),
+  gitRunner?: IGitRunner,
+): IKbRepository {
+  const dir = repositoryDirFor(workspacesRoot, kbDirName);
+  recordTestRepositoryRoot(path.dirname(dir));
+  return new KbRepository({
+    dir,
+    kbRepoUrl: typeof kbRepoUrl === 'function' ? kbRepoUrl : () => kbRepoUrl,
+    gitRunner: gitRunner ?? new NodeGitRunner(),
+  });
+}
+
+/**
+ * A WorkspaceService as a suite builds it: the constructor's arguments, with
+ * the repository — which only the composition root builds in the product —
+ * made here when the suite passes none.
+ */
+export function newWorkspaceService(
+  workspacesRoot: string,
+  kbRepoUrl: string | (() => string),
+  kb: Pick<KbContext, 'kbDirName' | 'defaultBranch'>,
+  disk: ITreeWalker,
+  gitRunner: IGitRunner = new NodeGitRunner(),
+  setAsideRoot?: string,
+  aroundSetAside?: (workspaceId: string, move: () => Promise<void>) => Promise<void>,
+  repository?: IKbRepository,
+): WorkspaceService {
+  return new WorkspaceService(
+    workspacesRoot,
+    kbRepoUrl,
+    kb,
+    disk,
+    gitRunner,
+    setAsideRoot,
+    aroundSetAside,
+    repository ?? testKbRepository(workspacesRoot, kb.kbDirName, kbRepoUrl, gitRunner),
+  );
+}
+
+/** A KbStartupRunner as a suite builds it — the repository made here when the suite passes none. */
+export function newKbStartupRunner(
+  opts: Omit<KbStartupRunnerOptions, 'repository'> & { repository?: IKbRepository },
+): KbStartupRunner {
+  return new KbStartupRunner({
+    ...opts,
+    repository: opts.repository ?? testKbRepository(opts.workspacesRoot, opts.kbDirName, opts.kbRepoUrl, opts.gitRunner),
+  });
+}

package/src/core/__tests__/compose-embed.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it, vi } from 'vitest';
+import { testKbContext, TEST_BRANCH_MODEL } from '../../__tests__/kb-context.js';
+import { makeRolesYamlWriteValidator } from '../../modules/access-model/roles-yaml-guard.js';
+import { createFileReaderRegistry } from '../../modules/workspace/file-readers/file-reader.registry.js';
+import type { DocExtractOutcome, DocExtractService } from '../../modules/workspace/file-readers/doc-extract.service.js';
+import { composeEmbedService, type EmbedComposition } from '../compose-embed.js';
+import { EmbedRefParseError } from '../../modules/embed/embed-link.js';
+
+const KB = 'knowledge-base';
+const BRANCH = TEST_BRANCH_MODEL.defaultBranch;
+const REPO = 'Data/Thing.md';
+const USER = { id: 'u-1', email: 'alice@bevel.software', name: 'Alice' };
+
+/** The composition root's deps, as mocks: enough to mint and to say who is looking. */
+function deps(): EmbedComposition {
+  const extract = async (): Promise<DocExtractOutcome> => ({ ok: false, message: 'no documents here' });
+  return {
+    config: { jwtSecret: 'test-jwt-secret', embedSharedSecret: '', publicFrontendUrl: 'https://hexis.example', kbDirName: KB },
+    kb: testKbContext({ kbDirName: KB }),
+    workspaceService: {
+      getOrCreateForBranch: vi.fn(async (branch: string) => ({ id: encodeURIComponent(branch), kbDirName: KB })),
+      isFile: vi.fn(async (_id: string, wsPath: string) => wsPath === `${KB}/${REPO}`),
+      readFileBinary: vi.fn(async () => Buffer.from('# Thing\n')),
+      writeFile: vi.fn(async () => undefined),
+      withPathTurn: vi.fn(async (_id: string, _p: string, op: () => Promise<unknown>) => op()),
+    },
+    accessControl: { canRead: vi.fn(async () => true), canWrite: vi.fn(async () => true) } as never,
+    authService: { getUserById: vi.fn(async () => USER), isEmailDomainAllowed: () => true, isActive: async () => true },
+    workflowService: {} as never,
+    gitService: {} as never,
+    accountLinks: { getUserId: async () => null, link: async () => undefined, listForUser: async () => [], unlink: async () => true },
+    readers: createFileReaderRegistry({ extract } satisfies Pick<DocExtractService, 'extract'> as DocExtractService),
+    validateWrite: makeRolesYamlWriteValidator(KB),
+  };
+}
+
+/**
+ * The composition root is the one place the distribution's ports reach the
+ * embed. Pinned here through that composition, not by handing the service a
+ * resolver directly: a node-id reference resolves through the port when one
+ * is registered, and is refused when none is — which is what a core-only
+ * deployment ships.
+ */
+describe('composeEmbedService', () => {
+  // The app's copy-link form: the full address of a node, which is its id.
+  const NODE_LINK = `https://hexis.example/workspace/${encodeURIComponent(BRANCH)}/abc-123`;
+
+  it('resolves a node-id reference through the registered port, and mints for the file it names', async () => {
+    const embedNodeIdResolver = vi.fn(async (id: string) => (id === 'abc-123' ? REPO : null));
+    const service = composeEmbedService(deps(), { embedNodeIdResolver });
+    const { token } = await service.mintForUser({ userId: USER.id, reference: NODE_LINK });
+    expect(embedNodeIdResolver).toHaveBeenCalledWith('abc-123');
+    expect((await service.viewerOf(token)).repoRelative).toBe(REPO);
+    // An id the graph does not know is refused as a dead reference.
+    await expect(service.mintForUser({ userId: USER.id, reference: 'nope-1' })).rejects.toThrow(EmbedRefParseError);
+  });
+
+  it('refuses a node-id reference when no port is registered — core has no graph', async () => {
+    const service = composeEmbedService(deps(), {});
+    await expect(service.mintForUser({ userId: USER.id, reference: NODE_LINK })).rejects.toThrow(EmbedRefParseError);
+    // A path reference is untouched by the absence of a resolver.
+    const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
+    expect((await service.viewerOf(token)).repoRelative).toBe(REPO);
+  });
+});

package/src/core/__tests__/lifecycle.test.ts

@@ -1,7 +1,11 @@
 import { describe, it, expect } from 'vitest';
-import { createShutdown, holdCommitWorkerLease, holdable, stopCore, withStartupTask, type LeasedWorker } from '../lifecycle.js';
+import { createShutdown, stopCore, withStartupTask, type LeasedWorker } from '../../index.js';
+// The lease helpers are the module's own, not on the entry point: their
+// ordering is pinned here, where the module is the unit under test.
+import { holdCommitWorkerLease, holdable } from '../lifecycle.js';
 import { BevelSecretsVariableLoader, registerBevelSecretsVariableLoader } from '../../modules/secrets-vault/secrets-variable-loader.js';
 import type { AdvisoryLease } from '../../modules/database/advisory-lock.js';
+import { WorkerPatternMatcher } from '../../modules/workspace/bounded-matcher.js';
 
 /** A lease the suite scripts: what each `tryAcquire` answers, and a way to lose it. */
 function fakeLease(answers: boolean[]) {
@@ -254,12 +258,12 @@ describe('createShutdown', () => {
             order.push('commitWorker.stop');
           },
         },
-        backgroundJobs: {
+        pluginJoinRequestJobs: {
           stopSweeping() {
-            order.push('backgroundJobs.stopSweeping');
+            order.push('pluginJoinRequestJobs.stopSweeping');
           },
           async drain() {
-            order.push('backgroundJobs.drain');
+            order.push('pluginJoinRequestJobs.drain');
           },
         },
         agentUploadStore: {
@@ -296,12 +300,12 @@ describe('createShutdown', () => {
     expect(d.order).toEqual([
       'server.close',
       'server.closeAllConnections',
-      'backgroundJobs.stopSweeping',
+      'pluginJoinRequestJobs.stopSweeping',
       // The upload sweep is stopped in the same breath as the other timers,
       // and drained before the pool goes: a graph that is stopping must not
       // leave a sweep walking the staging root its replacement will stage into.
       'agentUploadStore.stopSweeping',
-      'backgroundJobs.drain',
+      'pluginJoinRequestJobs.drain',
       'agentUploadStore.drainSweep',
       'commitWorker.stop',
       'db.end',
@@ -311,8 +315,8 @@ describe('createShutdown', () => {
   it('waits for the jobs a tick already started before the pool goes, within the budget', async () => {
     const d = deps();
     let release: () => void = () => undefined;
-    d.deps.backgroundJobs!.drain = () => {
-      d.order.push('backgroundJobs.drain');
+    d.deps.pluginJoinRequestJobs!.drain = () => {
+      d.order.push('pluginJoinRequestJobs.drain');
       return new Promise<void>((resolve) => {
         release = resolve;
       });
@@ -326,9 +330,9 @@ describe('createShutdown', () => {
     expect(d.order).toEqual([
       'server.close',
       'server.closeAllConnections',
-      'backgroundJobs.stopSweeping',
+      'pluginJoinRequestJobs.stopSweeping',
       'agentUploadStore.stopSweeping',
-      'backgroundJobs.drain',
+      'pluginJoinRequestJobs.drain',
     ]);
     release();
     await done;
@@ -348,7 +352,7 @@ describe('createShutdown', () => {
     // `commitWorker.stop` — which awaits an in-flight commit and can take
     // most of the shutdown budget — would start fresh clone/commit/push work
     // that the process exit immediately after kills mid-git.
-    const stopped = d.order.indexOf('backgroundJobs.stopSweeping');
+    const stopped = d.order.indexOf('pluginJoinRequestJobs.stopSweeping');
     expect(stopped).toBeGreaterThanOrEqual(0);
     expect(stopped).toBeLessThan(d.order.indexOf('commitWorker.stop'));
     expect(stopped).toBeLessThan(d.order.indexOf('db.end'));
@@ -357,7 +361,7 @@ describe('createShutdown', () => {
   it('shuts down cleanly when no background jobs were built yet', async () => {
     const d = deps();
     // A stop that lands mid-boot: the services exist, the jobs do not.
-    delete (d.deps as { backgroundJobs?: unknown }).backgroundJobs;
+    delete (d.deps as { pluginJoinRequestJobs?: unknown }).pluginJoinRequestJobs;
     delete (d.deps as { agentUploadStore?: unknown }).agentUploadStore;
     const shutdown = createShutdown(d.deps as never);
     const done = shutdown('SIGTERM');
@@ -374,8 +378,8 @@ describe('createShutdown', () => {
 
   it('does not wait past the budget for jobs that never finish, and still ends the pool', async () => {
     const d = deps();
-    d.deps.backgroundJobs!.drain = () => {
-      d.order.push('backgroundJobs.drain');
+    d.deps.pluginJoinRequestJobs!.drain = () => {
+      d.order.push('pluginJoinRequestJobs.drain');
       return new Promise<void>(() => undefined); // a clone that never returns
     };
     const shutdown = createShutdown(d.deps as never, { deadlineMs: 60 });
@@ -384,7 +388,7 @@ describe('createShutdown', () => {
     d.finishClose();
     await done;
     expect(d.order.slice(-4)).toEqual([
-      'backgroundJobs.drain',
+      'pluginJoinRequestJobs.drain',
       'agentUploadStore.drainSweep',
       'commitWorker.stop',
       'db.end',
@@ -400,9 +404,9 @@ describe('createShutdown', () => {
     expect(d.order).toEqual([
       'server.close',
       'server.closeAllConnections',
-      'backgroundJobs.stopSweeping',
+      'pluginJoinRequestJobs.stopSweeping',
       'agentUploadStore.stopSweeping',
-      'backgroundJobs.drain',
+      'pluginJoinRequestJobs.drain',
       'agentUploadStore.drainSweep',
       'commitWorker.stop',
       'db.end',
@@ -432,12 +436,12 @@ describe('stopCore', () => {
             order.push('commitWorker.stop');
           },
         },
-        backgroundJobs: {
+        pluginJoinRequestJobs: {
           stopSweeping() {
-            order.push('backgroundJobs.stopSweeping');
+            order.push('pluginJoinRequestJobs.stopSweeping');
           },
           async drain() {
-            order.push('backgroundJobs.drain');
+            order.push('pluginJoinRequestJobs.drain');
           },
         },
         agentUploadStore: {
@@ -478,11 +482,11 @@ describe('stopCore', () => {
     const g = graph();
     await stopCore(g.core as never);
     expect(g.order).toEqual([
-      'backgroundJobs.stopSweeping',
+      'pluginJoinRequestJobs.stopSweeping',
       'agentUploadStore.stopSweeping',
       'startupRetry.stop',
       'workflowService.stopTidying',
-      'backgroundJobs.drain',
+      'pluginJoinRequestJobs.drain',
       'agentUploadStore.drainSweep',
       'workflowService.drainTidy',
       'commitWorker.stop',
@@ -523,10 +527,10 @@ describe('stopCore', () => {
     const core = { ...g.core, startupRetry: null, secretsScope: undefined };
     await stopCore(core as never);
     expect(g.order).toEqual([
-      'backgroundJobs.stopSweeping',
+      'pluginJoinRequestJobs.stopSweeping',
       'agentUploadStore.stopSweeping',
       'workflowService.stopTidying',
-      'backgroundJobs.drain',
+      'pluginJoinRequestJobs.drain',
       'agentUploadStore.drainSweep',
       'workflowService.drainTidy',
       'commitWorker.stop',
@@ -534,16 +538,31 @@ describe('stopCore', () => {
     ]);
   });
 
+  it('ends the grep matcher\'s workers, so an evicted graph leaves no search running behind it', async () => {
+    const g = graph();
+    const patternMatcher = new WorkerPatternMatcher();
+    // A search holding a worker for its whole 5 s budget when the graph is stopped.
+    const running = patternMatcher.search('^(a+)+$', '').matchingLines([`${'a'.repeat(39)}!`], 1);
+    await new Promise((r) => setTimeout(r, 100));
+    const started = Date.now();
+    await stopCore({ ...g.core, patternMatcher } as never);
+    await expect(running).rejects.toMatchObject({ status: 503, details: { code: 'search_busy' } });
+    expect(Date.now() - started).toBeLessThan(1_000);
+    // Closed for good: nothing after the stop starts a worker.
+    await expect(patternMatcher.search('b', '').matchingLines(['b'], 1)).rejects.toMatchObject({ status: 503 });
+    expect(g.order.at(-1)).toBe('db.end');
+  });
+
   it('does not wait past the budget for a worker that never stops, and still ends the pool', async () => {
     const g = graph();
     const core = { ...g.core, commitWorker: { stop: () => new Promise<void>(() => undefined) } };
     await stopCore(core as never, { deadlineMs: 50 });
     expect(g.order).toEqual([
-      'backgroundJobs.stopSweeping',
+      'pluginJoinRequestJobs.stopSweeping',
       'agentUploadStore.stopSweeping',
       'startupRetry.stop',
       'workflowService.stopTidying',
-      'backgroundJobs.drain',
+      'pluginJoinRequestJobs.drain',
       'agentUploadStore.drainSweep',
       'workflowService.drainTidy',
       'db.end',

package/src/core/catalog-revision.ts

@@ -29,10 +29,12 @@ const log = logger('catalog-revision');
  */
 
 /**
- * A skill's line: everything `list_skills` shows about it on an AGENT
+ * A skill's line: what `list_skills` shows about the skill ITSELF on an AGENT
  * surface. Not `plugins`, which only the browser route decorates onto the
  * catalog — a field no agent-facing listing carries cannot be a change one
- * owes a refresh for.
+ * owes a refresh for. Not `canWrite` either: it is a verdict about the caller,
+ * judged per call by the tool, not part of the skill, and it is never on the
+ * summaries this digest reads.
  */
 function skillFingerprint(s: SkillSummary): string {
   return [s.name, s.path, s.version ?? '', s.description].join('\u0000');

package/src/core/compose-embed.ts

@@ -0,0 +1,50 @@
+import type { IGitService, IWorkflowService } from '@bevel-software/platform-shared';
+import type { KbContext } from '../shared/kb-context.js';
+import type { IAccessControl } from '../modules/access/access-control.interface.js';
+import type { WriteValidator } from '../modules/kb-fs/index.js';
+import type { FileReaderRegistry } from '../modules/workspace/index.js';
+import type { CorePorts } from './core-ports.js';
+import type { IAccountLinkService } from '../modules/embed/account-link.service.js';
+import type { EmbedAuthPort, EmbedWorkspacePort } from '../modules/embed/embed.interface.js';
+import { EmbedService, type EmbedConfig } from '../modules/embed/embed.service.js';
+
+/** What the composition root hands the embed: the services it reads and writes through. */
+export interface EmbedComposition {
+  config: EmbedConfig;
+  kb: KbContext;
+  workspaceService: EmbedWorkspacePort;
+  accessControl: IAccessControl;
+  authService: EmbedAuthPort;
+  workflowService: IWorkflowService;
+  gitService: IGitService;
+  accountLinks: IAccountLinkService;
+  /** The SAME extension-to-reader registry `read_file` dispatches on. */
+  readers: FileReaderRegistry;
+  /** The SAME pre-disk gate the file editor and the agent tools run. */
+  validateWrite: WriteValidator;
+}
+
+/**
+ * The embed service as the composition root builds it — the one place the
+ * distribution's ports reach it. Lives in `core/`, beside the composition
+ * root it serves: the ports are core's contract with a distribution, and a
+ * module never reaches up into core. A node-id reference (`/workspace/<branch>/
+ * <id>`, the app's copy-link form) resolves only where a node graph is: the
+ * distribution's, when it registers `ports.embedNodeIdResolver`; core has
+ * none and refuses such a reference.
+ */
+export function composeEmbedService(deps: EmbedComposition, ports: Pick<CorePorts, 'embedNodeIdResolver'>): EmbedService {
+  return new EmbedService(
+    deps.config,
+    deps.kb,
+    deps.workspaceService,
+    deps.accessControl,
+    deps.authService,
+    deps.workflowService,
+    deps.gitService,
+    deps.accountLinks,
+    deps.readers,
+    deps.validateWrite,
+    ports.embedNodeIdResolver ?? null,
+  );
+}

package/src/core/core-ports.ts

@@ -10,6 +10,7 @@ import type { IAccountAdmission } from '../modules/auth/account-admission.js';
 import type { IWriteAccess } from '../modules/write-access/write-access.js';
 import type { OnServerStart } from '../modules/workspace/startup/on-server-start.js';
 import type { AgentGuideHook } from '../modules/agent-guide/agent-guide.js';
+import type { EmbedNodeIdResolver } from '../modules/embed/embed.interface.js';
 
 /**
  * Every seam the enterprise overlay can fill in the CORE composition
@@ -138,6 +139,15 @@ export interface CorePorts {
    * `modules/write-access/write-access.ts`.
    */
   writeAccess?: IWriteAccess;
+  /**
+   * How an embed reference that is a bare NODE ID (`/workspace/<branch>/<id>`,
+   * the app's copy-link form) becomes the repository path it names. Core has
+   * no node graph, so core refuses such a reference; a distribution with one
+   * answers from it, and the Atlassian connector's links to nodes mint as
+   * they did when that distribution served the embed itself. Returns null
+   * for an id that names nothing. See `modules/embed/embed.interface.ts`.
+   */
+  embedNodeIdResolver?: EmbedNodeIdResolver;
 }
 
 /**