@bevel-software/platform-core-backend 0.7.4 → 0.8.0

package/src/modules/tool-manuals/tool-manuals.routes.ts

@@ -1,7 +1,15 @@
 import express, { type Request, type RequestHandler } from 'express';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import AdmZip from 'adm-zip';
+import { DEFAULT_BRANCH, PLUGINS_DIR } from '@bevel-software/platform-shared';
+import { workspaceIdForBranch, type WorkspaceService } from '../workspace/workspace.service.js';
+import type { IAccessControl } from '../access/access-control.interface.js';
 import '@utcp/http'; // side effect: register the 'http' call-template type
 import { CallTemplateSerializer, type CallTemplate } from '@utcp/sdk';
 import { type IToolManualService, EXTERNAL_KB_MANUAL_NAME } from './tool-manuals.contract.js';
+import { McpServerEditError, type McpServerEditService, type McpServerWrite } from './mcp-server-edit.service.js';
+import type { AuthUser } from '@bevel-software/platform-shared';
 import '../auth/auth.middleware.js'; // Express Request augmentation (req.userId / req.userEmail)
 import '../tool-auth/tool-auth.middleware.js'; // Express Request augmentation (req.toolAuth)
 
@@ -35,6 +43,7 @@ export function createToolManualsAgentRoutes(
   toolManualService: IToolManualService,
   manualAuth: RequestHandler,
   resolveUserEmail: ResolveUserEmail,
+  archiveDeps?: { workspaceService: WorkspaceService; accessControl: IAccessControl; kbDirName: string },
 ): express.Router {
   const router = express.Router();
 
@@ -63,6 +72,173 @@ export function createToolManualsAgentRoutes(
     }
   });
 
+  /**
+   * The whole plugin, byte-for-byte, as a zip — the materialization surface
+   * for the local MCP server. `read_file` is the agent's READING tool (text,
+   * one file at a time); this exists because a stdio server's plugin must
+   * land on the user's disk exactly as it is, binaries included. Access is
+   * per-file and the caller's own: every entry is filtered through the same
+   * read verdicts `list_files` uses, so a file the key cannot read is a file
+   * that is not in the archive — not an error, an absence.
+   */
+  router.get('/agent/plugins/:folder/archive', manualAuth, async (req, res) => {
+    if (!archiveDeps) return void res.status(404).json({ error: 'Not available' });
+    try {
+      const email = await callerEmail(req);
+      if (!email) return void res.status(403).json({ error: 'Forbidden' });
+      const folder = String(Array.isArray(req.params.folder) ? req.params.folder[0] : req.params.folder);
+      if (!folder || folder === '.' || folder === '..' || /[/\\]/.test(folder)) {
+        return void res.status(422).json({ error: 'Not a plugin folder name' });
+      }
+      const { workspaceService, accessControl, kbDirName } = archiveDeps;
+      const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+      await workspaceService.getOrCreateForBranch(DEFAULT_BRANCH);
+      const wsDir = await workspaceService.getWorkspacePath(wsId);
+      const pluginDir = path.join(wsDir, kbDirName, PLUGINS_DIR, folder);
+      // SYMLINKS ARE NOT SUPPORTED IN PLUGINS, anywhere. Access control
+      // resolves rules by path, and a symlink is a second path to the same
+      // content — a standing invitation for the spelling the ACL judged and
+      // the bytes served to diverge. The platform's own write paths never
+      // create one (they arrive only via direct git pushes), so every symlink
+      // is skipped rather than resolved: no target following, no cycle
+      // guards, no read-time re-resolution — complexity that existed only to
+      // support what the platform has no use for. Starting with the plugin
+      // folder itself: a symlinked `Plugins/<folder>` is not a plugin.
+      // Only ENOENT is an absence; an EACCES/EIO answered with 404 would
+      // dress a real read problem up as a missing plugin (the same contract
+      // as the realpath/open probes below).
+      const folderStat = await fs.lstat(pluginDir).catch((err: NodeJS.ErrnoException) => {
+        if (err.code === 'ENOENT') return null;
+        throw err;
+      });
+      if (folderStat === null || !folderStat.isDirectory()) {
+        return void res.status(404).json({ error: 'Not found' });
+      }
+      const rels: string[] = [];
+      const walk = async (dir: string, rel: string): Promise<void> => {
+        let entries;
+        try {
+          entries = await fs.readdir(dir, { withFileTypes: true });
+        } catch (err) {
+          // Only an absent directory is a non-event; anything else (EACCES,
+          // EIO) silently missing from the archive would hand the client an
+          // incomplete plugin stamped as success.
+          if ((err as NodeJS.ErrnoException).code === 'ENOENT') return;
+          throw err;
+        }
+        for (const e of entries) {
+          if (e.name === '.git') continue;
+          const childRel = rel ? `${rel}/${e.name}` : e.name;
+          // Dirent's isDirectory/isFile are both false for a symlink, so a
+          // link is never walked and never listed — but say so, once, because
+          // an author who committed one deserves to know it went nowhere.
+          if (e.isDirectory()) await walk(path.join(dir, e.name), childRel);
+          else if (e.isFile()) rels.push(childRel);
+          else if (e.isSymbolicLink()) {
+            console.warn(`[tool-manuals] archive of "${folder}": ${childRel} is a symlink — not supported in plugins, skipped.`);
+          }
+        }
+      };
+      await walk(pluginDir, '');
+      if (rels.length === 0) return void res.status(404).json({ error: 'Not found' });
+      const verdicts = await accessControl.canReadBatch(
+        wsId,
+        email,
+        rels.map((r) => `${PLUGINS_DIR}/${folder}/${r}`),
+      );
+      const zip = new AdmZip();
+      let included = 0;
+      let bytes = 0;
+      // The zip is built in memory; without a ceiling one plugin full of large
+      // assets is a backend OOM any key holder can trigger.
+      const MAX_ARCHIVE_BYTES = 64 * 1024 * 1024;
+      // Canonical base for the read-time identity check below. The folder was
+      // lstat-verified a real directory above, so this is normalization
+      // (case, 8.3 names, drive spelling), not link resolution — but that
+      // verification is a moment old, and a plugin deleted since (a workspace
+      // reset, a merged deletion) is an ABSENCE, the same 404 it would have
+      // been a moment earlier, not an internal error.
+      const pluginRealBase = await fs.realpath(pluginDir).catch((err: NodeJS.ErrnoException) => {
+        if (err.code === 'ENOENT') return null;
+        throw err;
+      });
+      if (pluginRealBase === null) return void res.status(404).json({ error: 'Not found' });
+      for (const rel of rels) {
+        // Fail closed, per file — only an explicit `true` verdict is included.
+        if (verdicts.get(`${PLUGINS_DIR}/${folder}/${rel}`) !== true) continue;
+        const abs = path.join(pluginDir, ...rel.split('/'));
+        // The no-symlink rule, re-checked at read time over the WHOLE path.
+        // The open below guards only the final component — a PARENT directory
+        // swapped for a link between walk and read makes `abs` traverse the
+        // link with the final component still a regular file. realpath
+        // resolves every component, so demanding it equal the spelled path is
+        // exactly "no component is a link": identity, not mere containment.
+        const realNow = await fs.realpath(abs).catch((err: NodeJS.ErrnoException) => {
+          if (err.code === 'ENOENT') return null; // deleted since the walk — an absence, not a failure
+          throw err;
+        });
+        if (realNow === null || realNow !== path.join(pluginRealBase, ...rel.split('/'))) {
+          if (realNow !== null) {
+            console.warn(`[tool-manuals] archive of "${folder}": ${rel} no longer resolves to itself — skipped.`);
+          }
+          continue;
+        }
+        // Check and read through ONE file handle, so the bytes that land in
+        // the zip come from the very inode the checks passed — a path-based
+        // stat-then-readFile pair leaves a window where the path is swapped
+        // between the two and the archive ships bytes the ACL never judged.
+        // O_NOFOLLOW makes a final-component symlink fail the open itself
+        // where the platform defines it (Linux — production; Windows test
+        // runs fall back to the realpath identity check above alone). Only an
+        // ENOENT is a skip; any other failure is a real read problem that
+        // must surface as a 500, not ship as a silently partial archive.
+        const handle = await fs
+          .open(abs, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0))
+          .catch((err: NodeJS.ErrnoException) => {
+            if (err.code === 'ENOENT') return null; // deleted since the walk — an absence
+            if (err.code === 'ELOOP') {
+              // O_NOFOLLOW's spelling of "the final component is a symlink".
+              console.warn(`[tool-manuals] archive of "${folder}": ${rel} is a symlink — not supported in plugins, skipped.`);
+              return null;
+            }
+            throw err;
+          });
+        if (handle === null) continue;
+        try {
+          // fstat on the handle types and sizes the OPENED file — the size
+          // still gates BEFORE content, because rejecting after the read
+          // would already have spiked memory by exactly the payload the
+          // limit exists to refuse.
+          const stat = await handle.stat();
+          if (!stat.isFile()) continue;
+          bytes += stat.size;
+          if (bytes > MAX_ARCHIVE_BYTES) {
+            return void res.status(413).json({
+              error: `Plugin "${folder}" exceeds the ${MAX_ARCHIVE_BYTES / (1024 * 1024)}MB archive limit.`,
+            });
+          }
+          // Unix mode rides in the zip attrs so a `./`-command stdio server is
+          // still executable after materialization (0 on Windows — harmless).
+          // PLAIN mode, no shifting: adm-zip masks a numeric attr with 0xfff and
+          // positions it into the external-attribute high bits itself — a
+          // pre-shifted value is destroyed by that mask.
+          zip.addFile(rel, await handle.readFile(), '', stat.mode & 0o7777);
+          included += 1;
+        } finally {
+          await handle.close();
+        }
+      }
+      // An all-filtered plugin looks exactly like an absent one — a 404 must
+      // not confirm to a keyless caller that the folder exists.
+      if (included === 0) return void res.status(404).json({ error: 'Not found' });
+      res.setHeader('Content-Type', 'application/zip');
+      res.send(zip.toBuffer());
+    } catch (err) {
+      console.error('[tool-manuals] plugin archive failed:', err instanceof Error ? err.message : err);
+      res.status(500).json({ error: 'Failed to archive plugin' });
+    }
+  });
+
   router.get('/tools/:slug/manual', manualAuth, async (req, res) => {
     try {
       const email = await callerEmail(req);
@@ -89,9 +265,54 @@ export function createToolManualsAgentRoutes(
  *                            literal sibling is shadowed by the param segment;
  *                            `preview` is POST-only, so it never collides.
  */
-export function createToolManualsBrowserRoutes(toolManualService: IToolManualService): express.Router {
+export function createToolManualsBrowserRoutes(
+  toolManualService: IToolManualService,
+  serverEdit?: { service: McpServerEditService; getUser: (userId: string) => Promise<AuthUser | undefined> },
+): express.Router {
   const router = express.Router();
 
+  /**
+   * Server-scoped read/write of one MCP server — the tool page's edit form.
+   * One server's truth spans mcp.json AND plugin.json's extensions block; a
+   * raw file editor shows a writer half of it at best, so the form talks to
+   * this pair instead. PUT commits both files together and refuses the states
+   * that would strand a half (see McpServerEditService).
+   */
+  router.get('/tools/:slug/server', async (req, res) => {
+    if (!serverEdit) return void res.status(404).json({ error: 'Not available' });
+    const email = req.userEmail;
+    if (!email) return void res.status(401).json({ error: 'Not authenticated' });
+    try {
+      const view = await serverEdit.service.getServer(email, String(req.params.slug));
+      if (!view) return void res.status(404).json({ error: 'Not found' });
+      res.json(view);
+    } catch (err) {
+      console.error('[tool-manuals] server read failed:', err instanceof Error ? err.message : err);
+      res.status(500).json({ error: 'Failed to read the server' });
+    }
+  });
+
+  router.put('/tools/:slug/server', async (req, res) => {
+    if (!serverEdit) return void res.status(404).json({ error: 'Not available' });
+    if (!req.userId) return void res.status(401).json({ error: 'Not authenticated' });
+    try {
+      const user = await serverEdit.getUser(req.userId);
+      if (!user) return void res.status(401).json({ error: 'Not authenticated' });
+      const result = await serverEdit.service.putServer(
+        user,
+        String(req.params.slug),
+        (req.body ?? {}) as McpServerWrite,
+      );
+      res.json(result);
+    } catch (err) {
+      if (err instanceof McpServerEditError) {
+        return void res.status(err.status).json({ error: err.message });
+      }
+      console.error('[tool-manuals] server write failed:', err instanceof Error ? err.message : err);
+      res.status(500).json({ error: 'Failed to save the server' });
+    }
+  });
+
   router.get('/tools', async (req, res) => {
     const email = req.userEmail;
     if (!email) return void res.status(401).json({ error: 'Not authenticated' });

package/src/modules/tool-manuals/tool-manuals.service.ts

@@ -9,11 +9,18 @@ import {
   DefaultVariableSubstitutor,
   type CallTemplate,
 } from '@utcp/sdk';
-import { DEFAULT_BRANCH, GROUPS_DIR } from '@bevel-software/platform-shared';
+import {
+  DEFAULT_BRANCH,
+  PLUGINS_DIR,
+  PLUGIN_MANIFEST_FILE,
+  PLUGIN_MCP_FILE,
+} from '@bevel-software/platform-shared';
+import { descriptorsFromMcpJson } from './mcp-json-discovery.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { workspaceIdForBranch } from '../workspace/workspace.service.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import { assertSafeFetchUrl } from '../../shared/ssrf.js';
+import { RESERVED_VARIABLE_NAMES, findReservedVariableRef } from '../../shared/variable-refs.js';
 import { extractFrontmatter, resolveDeclaredId, isValidId, dedupeById } from '../../shared/frontmatter-id.js';
 import { walkFiles } from '../../shared/fs-walk.js';
 import { TtlCache } from '../../shared/ttl-cache.js';
@@ -27,6 +34,7 @@ import {
   EXTERNAL_KB_MANUAL_NAME,
   type IToolManualService,
   type ToolManualDescriptor,
+  type ToolManualDescriptorBase,
   type ToolManualSummary,
   type ToolManualDetail,
   type ToolCapability,
@@ -60,46 +68,26 @@ const MAX_CAPABILITIES = 100;
 const RESERVED_TOOL_NAMESPACES = [INTERNAL_MANUAL_NAME, EXTERNAL_KB_MANUAL_NAME].map((n) => n.toLowerCase());
 
 /**
- * Variable names the platform seeds for its own (Bevel-hosted) manuals:
- * `<ns>_API_URL` points a manual at the backend and `<ns>_CONNECTION_KEY`
- * carries the platform bearer. No user `.tool` may REFERENCE them
- * (`${API_URL}` / `$API_URL`), in any `.tool` type: the only seeded user
- * namespace is an inline `.tool`'s (its discovery template is platform-served),
- * and a reference inside author-written content would resolve platform creds
- * into a request the author shaped. Refusing every `.tool` at the producing
- * boundary makes "user tools never carry platform credentials" structural
- * rather than dependent on which namespaces happen to be seeded.
+ * No user `.tool` may REFERENCE the platform-seeded variables (`${API_URL}` /
+ * `$API_URL`), in any `.tool` type: the only seeded user namespace is an
+ * inline `.tool`'s (its discovery template is platform-served), and a
+ * reference inside author-written content would resolve platform creds into a
+ * request the author shaped. Refusing every `.tool` at the producing boundary
+ * makes "user tools never carry platform credentials" structural rather than
+ * dependent on which namespaces happen to be seeded. The names and the
+ * reference grammar live in `shared/variable-refs.ts` — one definition for
+ * every boundary that classifies references.
  */
-const RESERVED_VARIABLE_NAMES: readonly string[] = ['API_URL', 'CONNECTION_KEY'];
-
-/** The SDK substitutor's reference grammar, exactly: `${VAR}` or `$VAR`. */
-const VARIABLE_REFERENCE_RE = /\$\{([a-zA-Z0-9_]+)\}|\$([a-zA-Z0-9_]+)/g;
-
-/**
- * A REFERENCE is reserved by SUFFIX, not by exact name: the substitutor looks a
- * variable up under the manual's UTCP namespace first, so `${<ns>_CONNECTION_KEY}`
- * resolves the very same seeded value the bare `${CONNECTION_KEY}` does. Matching
- * the bare name only would let a `.tool` reach the platform bearer just by
- * spelling the namespace out. Suffix matching also refuses harmless-looking
- * near-misses (`MY_API_URL`) — deliberately fail-closed: a `.tool` author who
- * wants their own base URL has the whole namespace minus two suffixes.
- */
-function isReservedVariableRef(varName: string): boolean {
-  return RESERVED_VARIABLE_NAMES.some((reserved) => varName.endsWith(reserved));
-}
 
 /** Throw if any string in the `.tool` document references a reserved variable. */
 function assertNoReservedVariableRefs(doc: unknown, name: string): void {
-  const text = JSON.stringify(doc) ?? '';
-  for (const match of text.matchAll(VARIABLE_REFERENCE_RE)) {
-    const varName = match[1] ?? match[2];
-    if (isReservedVariableRef(varName)) {
-      throw new Error(
-        `\`.tool\` "${name}" references the reserved variable "${match[0]}" — ` +
-          'API_URL and CONNECTION_KEY (bare or namespaced, e.g. `<namespace>_CONNECTION_KEY`) ' +
-          'are seeded by the platform for its own manuals and may not appear anywhere in a `.tool`.',
-      );
-    }
+  const ref = findReservedVariableRef(doc);
+  if (ref !== null) {
+    throw new Error(
+      `\`.tool\` "${name}" references the reserved variable "${ref}" — ` +
+        'API_URL and CONNECTION_KEY (bare or namespaced, e.g. `<namespace>_CONNECTION_KEY`) ' +
+        'are seeded by the platform for its own manuals and may not appear anywhere in a `.tool`.',
+    );
   }
 }
 
@@ -270,7 +258,7 @@ export class ToolManualService implements IToolManualService {
   async preview(content: string): Promise<ToolManualPreview> {
     let descriptor: ToolManualDescriptor;
     try {
-      descriptor = normalizeToolManual('draft', 'Groups/draft.tool', content);
+      descriptor = normalizeToolManual('draft', 'Plugins/draft.tool', content);
     } catch (err) {
       return { ok: false, errors: [err instanceof Error ? err.message : String(err)] };
     }
@@ -316,6 +304,28 @@ export class ToolManualService implements IToolManualService {
         headers: { Authorization: 'Bearer ${CONNECTION_KEY}' },
       };
     }
+    if (m.type === 'mcp' && m.stdio) {
+      // A stdio server, for LOCAL consumers only (`remote: false` is implied
+      // at discovery). Command/args/env/cwd pass through verbatim — the Agent
+      // Plugins placeholders (`${PLUGIN_ROOT}`/`${PLUGIN_DATA}`) are expanded
+      // by the LOCAL runtime against its materialized plugin copy; this
+      // process has no such paths and must not guess them.
+      return {
+        name: m.name,
+        call_template_type: 'mcp',
+        config: {
+          mcpServers: {
+            [m.name]: {
+              transport: 'stdio',
+              command: m.stdio.command,
+              args: m.stdio.args,
+              ...(m.stdio.env ? { env: m.stdio.env } : {}),
+              ...(m.stdio.cwd ? { cwd: m.stdio.cwd } : {}),
+            },
+          },
+        },
+      };
+    }
     if (m.type === 'mcp') {
       // Remote (HTTP/streamable) MCP server. Exact plugin field shape is
       // finalized in Phase 4 (native `@utcp/mcp`); the proxy try/catches
@@ -487,14 +497,41 @@ export class ToolManualService implements IToolManualService {
     }
     const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
 
-    // A `.tool` sits under `Groups/`, beside the skills that use it.
+    // A `.tool` sits under `Plugins/`, beside the skills that use it.
     const files: { abs: string; rel: string }[] = [];
-    const root = path.join(kbRoot, GROUPS_DIR);
+    const root = path.join(kbRoot, PLUGINS_DIR);
     for (const rel of await walkFiles(root, (n) => n.toLowerCase().endsWith('.tool'))) {
-      files.push({ abs: path.join(root, rel), rel: `${GROUPS_DIR}/${rel}` });
+      files.push({ abs: path.join(root, rel), rel: `${PLUGINS_DIR}/${rel}` });
     }
 
+    // MCP servers come from each plugin's mcp.json — the AUTHORITATIVE source
+    // (the Agent Plugins fixed location), synthesized into the same descriptor
+    // shape. Listed BEFORE the `.tool` files: on a name collision (a legacy
+    // mcp `.tool` the migration has not converted yet), the shared dedup keeps
+    // the first occurrence, and the authoritative source must be the one kept.
     const parsed: ToolManualDescriptor[] = [];
+    let pluginFolders: string[] = [];
+    try {
+      pluginFolders = (await fs.readdir(root, { withFileTypes: true }))
+        .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+        .map((e) => e.name)
+        .sort();
+    } catch {
+      /* no Plugins/ root — nothing to scan */
+    }
+    for (const folder of pluginFolders) {
+      let mcpJson: string;
+      try {
+        mcpJson = await fs.readFile(path.join(root, folder, PLUGIN_MCP_FILE), 'utf-8');
+      } catch {
+        continue; // no mcp.json is the common case, not an error
+      }
+      const pluginJson = await fs
+        .readFile(path.join(root, folder, PLUGIN_MANIFEST_FILE), 'utf-8')
+        .catch(() => null);
+      parsed.push(...descriptorsFromMcpJson(folder, mcpJson, pluginJson));
+    }
+
     for (const f of files) {
       let content: string;
       try {
@@ -654,7 +691,10 @@ export function normalizeToolManual(
   // reference the platform-seeded variables.
   assertNoReservedVariableRefs(obj, name);
 
-  const descriptor: ToolManualDescriptor = {
+  // The non-stdio constituent of the union, by name: `.tool` parsing can
+  // never produce a spawn spec, and the stdio side pins `remote: false`,
+  // which this builder must stay free to set from the file's own `remote:`.
+  const descriptor: ToolManualDescriptorBase & { remote?: boolean; stdio?: undefined } = {
     slug: provisionalSlug,
     name,
     path: repoPath,

package/src/modules/tool-manuals/tool-manuals.tools.ts

@@ -179,9 +179,12 @@ async function buildListLocalToolsDef(svc: IToolManualService, userEmail?: strin
     description:
       'List tools your workspace admins configured that run ONLY in a local environment ' +
       '(e.g. a self-hosted MCP server on localhost) and therefore cannot be called through this ' +
-      'remote endpoint. Each entry gives the tool’s name and its `.tool` file path in the knowledge ' +
-      'base — read that file with `read_file` and configure the tool yourself in your local setup ' +
-      '(e.g. add the MCP server to your client). ' +
+      'remote endpoint. To CALL them, run the workspace as a local MCP server instead of this one: ' +
+      '`npx @bevel-software/hexis-mcp --url <workspace-url> --key <connection-key>` serves every tool ' +
+      'you have here plus these, because it runs where they exist (their own credentials come from ' +
+      'that process\'s environment). Otherwise each entry gives the tool’s name and its `.tool` file ' +
+      'path in the knowledge base — read that file with `read_file` and wire the tool into your local ' +
+      'setup by hand. ' +
       (await localToolsLine(svc, userEmail)),
     path: '/api/agent/tools/list_local_tools',
     inputs: { type: 'object', properties: {}, additionalProperties: false },

package/src/modules/workflow/__tests__/pending-commits.worker.test.ts

@@ -52,6 +52,7 @@ function makeService(): PendingCommitsService {
   return {
     enqueue: vi.fn().mockResolvedValue(undefined),
     claimNext: vi.fn().mockResolvedValue(null),
+    hasReadyRow: vi.fn().mockResolvedValue(false),
     markSucceeded: vi.fn().mockResolvedValue(undefined),
     markTransientFailure: vi.fn().mockResolvedValue(undefined),
     markRecoveryStarted: vi.fn().mockResolvedValue(undefined),
@@ -114,6 +115,8 @@ describe('PendingCommitsWorker.drainOnce', () => {
       'feat/x',
       'Foo.md',
       expect.objectContaining<Partial<AuthUser>>({ email: 'alice@example.com', name: 'Alice' }),
+      // Last (only) row of the burst, so the advisory validator runs.
+      { skipValidation: false },
     );
     expect(service.markSucceeded).toHaveBeenCalledWith('row-1');
     expect(service.markTransientFailure).not.toHaveBeenCalled();
@@ -221,6 +224,121 @@ describe('PendingCommitsWorker.drainOnce', () => {
     await expect(worker.drainOnce()).resolves.toBeUndefined();
     expect(service.markNeedsAttention).toHaveBeenCalled();
   });
+
+  /**
+   * A sweep used to take exactly ONE row per workspace and then sleep
+   * `POLL_INTERVAL_MS`, capping a workspace at ~2 commits/second however fast
+   * git was. A bulk change — a migration, an agent run — paid a minute of
+   * pure polling latency, and anything waiting for the queue to settle (a
+   * change request being applied) waited with it.
+   */
+  describe('draining a burst', () => {
+    /** Queue `count` rows, then nothing — the shape a bulk change leaves. */
+    function queue(count: number) {
+      const claim = service.claimNext as ReturnType<typeof vi.fn>;
+      const ready = service.hasReadyRow as ReturnType<typeof vi.fn>;
+      for (let i = 0; i < count; i += 1) {
+        claim.mockResolvedValueOnce(makeRow({ id: `row-${i}`, path: `File${i}.md` }));
+        // True until the last row is the one in hand.
+        ready.mockResolvedValueOnce(i < count - 1);
+      }
+      claim.mockResolvedValue(null);
+      ready.mockResolvedValue(false);
+    }
+
+    it('commits every queued row in ONE pass', async () => {
+      queue(12);
+      await worker.drainOnce();
+      expect(workflow.runPendingCommit).toHaveBeenCalledTimes(12);
+      expect(service.markSucceeded).toHaveBeenCalledTimes(12);
+    });
+
+    it('validates once — on the last commit, whose tree is the end state', async () => {
+      // The validator parses the whole KB for a report that is only logged,
+      // so per-file runs cost a full parse each and all say the same thing.
+      queue(5);
+      await worker.drainOnce();
+      const skipped = workflow.runPendingCommit.mock.calls.map((c) => c[4]?.skipValidation);
+      expect(skipped).toEqual([true, true, true, true, false]);
+    });
+
+    it('stops at the burst ceiling so one workspace cannot starve the rest', async () => {
+      // The loop holds the single in-flight commit slot; an unbounded drain
+      // would park every other user's save behind a huge migration.
+      queue(200);
+      await worker.drainOnce();
+      expect(workflow.runPendingCommit).toHaveBeenCalledTimes(50);
+    });
+
+    it('gives up the pass the moment stop() lands mid-burst', async () => {
+      queue(12);
+      workflow.runPendingCommit.mockImplementation(async () => {
+        (worker as unknown as { running: boolean }).running = false;
+      });
+      await worker.drainOnce();
+      expect(workflow.runPendingCommit).toHaveBeenCalledTimes(1);
+    });
+
+    it('carries on after a transient failure and ends the pass when nothing is ready', async () => {
+      // What keeps the drain loop from SPINNING on a failing row is the SQL
+      // backoff gate: `markTransientFailure` leaves `lastAttemptedAt` set, so
+      // `claimNext` refuses that row until its backoff elapses. That gate is
+      // not exercised here — `claimNext` is a stub, so this would pass with
+      // the gate removed. It lives in `readyPredicate`, shared by `claimNext`
+      // and `hasReadyRow` precisely so the two cannot drift; there is no
+      // database-backed test for it in this package.
+      //
+      // What this DOES pin is the loop's own half of the contract: a failure
+      // is recorded and the pass keeps going rather than aborting the sweep,
+      // and the row is attempted once.
+      (service.claimNext as ReturnType<typeof vi.fn>)
+        .mockResolvedValueOnce(makeRow({ id: 'bad' }))
+        .mockResolvedValueOnce(makeRow({ id: 'good' }))
+        .mockResolvedValue(null);
+      workflow.runPendingCommit
+        .mockRejectedValueOnce(new Error('push rejected'))
+        .mockResolvedValueOnce(undefined);
+
+      await worker.drainOnce();
+
+      expect(service.markTransientFailure).toHaveBeenCalledTimes(1);
+      expect(service.markSucceeded).toHaveBeenCalledTimes(1);
+      expect(workflow.runPendingCommit).toHaveBeenCalledTimes(2);
+    });
+
+    it('validates the final slot when the burst hits its ceiling', async () => {
+      // Rows remain queued, so the peek says "more" — but this is the last
+      // commit of the PASS, and skipping it would end every sweep of a big
+      // backlog on an unvalidated commit.
+      queue(200);
+      await worker.drainOnce();
+      const calls = workflow.runPendingCommit.mock.calls;
+      expect(calls).toHaveLength(50);
+      expect(calls[49]?.[4]?.skipValidation).toBe(false);
+      expect(calls[48]?.[4]?.skipValidation).toBe(true);
+      // …and does not ASK on that slot: the ceiling already answers it, so
+      // peeking would be a wasted round-trip on every sweep of a backlog.
+      expect(service.hasReadyRow).toHaveBeenCalledTimes(49);
+    });
+
+    it('commits the claimed row even if the peek throws', async () => {
+      // The row is already claimed and `running`; nothing resets that, so
+      // throwing out of the peek would strand it and the workspace would stop
+      // draining until the process restarted. A failed peek assumes "last",
+      // which costs one extra validation and nothing else.
+      (service.claimNext as ReturnType<typeof vi.fn>)
+        .mockResolvedValueOnce(makeRow({ id: 'claimed' }))
+        .mockResolvedValue(null);
+      (service.hasReadyRow as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
+        new Error('connection reset'),
+      );
+
+      await expect(worker.drainOnce()).resolves.toBeUndefined();
+
+      expect(service.markSucceeded).toHaveBeenCalledTimes(1);
+      expect(workflow.runPendingCommit.mock.calls[0]?.[4]?.skipValidation).toBe(false);
+    });
+  });
 });
 
 describe('PendingCommitsWorker lifecycle', () => {

package/src/modules/workflow/__tests__/workflow.service.facade.test.ts

@@ -93,7 +93,7 @@ function makeAccessControl(): IAccessControl {
     grantSources: vi.fn().mockResolvedValue({}),
     invalidate: vi.fn(),
     findEmailByHash: vi.fn().mockResolvedValue(null),
-    kbPrincipals: vi.fn().mockResolvedValue({ groups: [], people: [] }),
+    kbPrincipals: vi.fn().mockResolvedValue({ plugins: [], people: [] }),
     validateRolesYaml: vi.fn().mockReturnValue({ ok: true }),
     referencesToRole: vi.fn().mockResolvedValue([]),
     canWriteAtRef: vi.fn().mockResolvedValue(null),

package/src/modules/workflow/git/__tests__/branch-name.test.ts

@@ -49,9 +49,9 @@ describe('assertValidRelativePath', () => {
     // now sets `GIT_LITERAL_PATHSPECS=1` on every git subprocess, so KB files
     // arriving with bracketed prefixes (`[Approved]`, `[New]`, `[Updated …]`)
     // or other glob metacharacters round-trip through commit cleanly.
-    '[Approved] Purchasing_Order archive.docx',
-    'Purchasing/[New] Purchasing_E-Invoicing DE.docx',
-    'Purchasing/[Updated 03.09.2025] Purchasing_How to search_Product detail page.docx',
+    '[Approved] Handbook_Order archive.docx',
+    'Handbook/[New] Handbook_E-Invoicing DE.docx',
+    'Handbook/[Updated 03.09.2025] Handbook_How to search_Detail page.docx',
     'docs/wildcard*name.md',
     'docs/question?name.md',
     'docs/bang!name.md',

package/src/modules/workflow/git/__tests__/git.service.accessGating.test.ts

@@ -124,7 +124,7 @@ function recordingAccessControl(opts: {
     eligibleWritersForPathsAtRef: async (_w, _ref, paths) =>
       new Map(paths.map((p) => [p, { roles: [], users: [], emails: new Set<string>() }])),
     findEmailByHash: async () => null,
-    kbPrincipals: async () => ({ groups: [], people: [] }),
+    kbPrincipals: async () => ({ plugins: [], people: [] }),
     validateRolesYaml: () => ({ ok: true }),
     referencesToRole: async () => [],
   };
@@ -279,8 +279,8 @@ describe('GitService — push gate uses origin/<branch> (not HEAD or working tre
   });
 
   it('systemAuthorized skips the gate entirely, and the push still lands', async () => {
-    // The group-provisioning path: its endpoint IS the authorization (any
-    // signed-in user may claim an unused name under Groups/), and the gate
+    // The plugin-provisioning path: its endpoint IS the authorization (any
+    // signed-in user may claim an unused name under Plugins/), and the gate
     // could only read the new folder's chain at origin as `write: Admin`.
     const { svc, calls } = await setupWithOrigin();
     await svc.push(workspaceId, USER, { systemAuthorized: true });