@bevel-software/platform-core-backend 0.28.0 → 0.29.0

package/src/modules/embed/__tests__/embed.service.test.ts

@@ -168,15 +168,51 @@ describe('EmbedService: minting', () => {
   /**
    * The token rides in the tool result and so in the chat transcript;
    * whoever holds it acts on that one file as its user until it expires.
-   * One hour (Razvan, 2026-10-09), down from the two the embed used before.
+   * Five minutes (Razvan, 2026-10-09): the chat view renews it through its
+   * host when a call is refused, so a short life costs the reader nothing.
    */
-  it('mints a token that lives one hour', async () => {
+  it('mints an open_page token that lives five minutes', async () => {
     const { service } = build();
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     const { iat, exp } = claimsOf(token) as { iat: number; exp: number };
+    expect(exp - iat).toBe(5 * 60);
+  });
+
+  /** The connector frames `/embed` and has no host to renew through: its hour stands. */
+  it('mints a connector token that keeps its one-hour lifetime', async () => {
+    const { service } = build();
+    const { token } = await service.mintToken({ accountId: 'acc-1', email: USER.email, reference: REPO });
+    const { iat, exp } = claimsOf(token) as { iat: number; exp: number };
     expect(exp - iat).toBe(60 * 60);
   });
 
+  /**
+   * Both kinds are read by the same verification: each loads while it lives
+   * and is refused as a token once it has run out — the user's after five
+   * minutes, the connector's only after the hour.
+   */
+  it('reads both kinds while they live and refuses each once its own lifetime is over', async () => {
+    vi.useFakeTimers({ toFake: ['Date'] });
+    try {
+      vi.setSystemTime(new Date('2026-10-09T10:00:00Z'));
+      const { service } = build();
+      const user = await service.mintForUser({ userId: USER.id, reference: REPO });
+      const connector = await service.mintToken({ accountId: 'acc-1', email: USER.email, reference: REPO });
+
+      vi.setSystemTime(new Date('2026-10-09T10:04:50Z'));
+      await expect(service.loadFile(user.token)).resolves.toMatchObject({ repoRelative: REPO });
+
+      vi.setSystemTime(new Date('2026-10-09T10:05:01Z'));
+      await expect(service.loadFile(user.token)).rejects.toThrow(EmbedTokenError);
+      await expect(service.loadFile(connector.token)).resolves.toMatchObject({ repoRelative: REPO });
+
+      vi.setSystemTime(new Date('2026-10-09T11:00:01Z'));
+      await expect(service.loadFile(connector.token)).rejects.toThrow(EmbedTokenError);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it('mints for an outside account — the connector path, unchanged', async () => {
     const { service } = build();
     const { token } = await service.mintToken({
@@ -189,7 +225,9 @@ describe('EmbedService: minting', () => {
 
   it('keeps the token PSEUDONYMOUS — no address, no name', async () => {
     const { service } = build();
-    const { token } = await service.mintToken({ accountId: 'acc-1', email: USER.email, reference: REPO });
+    const { token, embedUrl } = await service.mintToken({ accountId: 'acc-1', email: USER.email, reference: REPO });
+    // The connector's host sizes its frame to the content: its view is told so.
+    expect(embedUrl).toBe(`https://hexis.example/embed?token=${encodeURIComponent(token)}&sizing=content`);
     expect(JSON.stringify(claimsOf(token))).not.toContain(USER.email);
     expect(JSON.stringify(claimsOf(token))).not.toContain(USER.name);
   });
@@ -711,6 +749,41 @@ describe('EmbedService: a switched-off account', () => {
   });
 });
 
+/**
+ * A distribution's own token-authed route beside the embed (a graph for a
+ * dashboard) asks who is looking before it serves anything, and must judge
+ * the viewer exactly as the embed does.
+ */
+describe('EmbedService: who is looking through a token', () => {
+  it('answers the linked user, their verdicts on the file, and the file', async () => {
+    const { service } = build({ canWrite: false });
+    const { token } = await service.mintForUser({ userId: USER.id, reference: `${REPO}#intro` });
+    expect(await service.viewerOf(token)).toEqual({
+      linked: true,
+      user: expect.objectContaining({ id: USER.id, email: USER.email }),
+      canRead: true,
+      canWrite: false,
+      repoRelative: REPO,
+    });
+  });
+
+  it('answers nobody for an unlinked outside account, and refuses a switched-off one as the embed does', async () => {
+    const unlinked = build({ linkedUserId: null });
+    const outside = await unlinked.service.mintToken({ accountId: 'acc-1', reference: REPO });
+    expect(await unlinked.service.viewerOf(outside.token)).toEqual({
+      linked: false,
+      user: null,
+      canRead: false,
+      canWrite: false,
+      repoRelative: REPO,
+    });
+    const off = build({ active: false });
+    const { token } = await off.service.mintForUser({ userId: USER.id, reference: REPO });
+    await expect(off.service.viewerOf(token)).rejects.toThrow(ACCOUNT_DEACTIVATED_MESSAGE);
+    await expect(off.service.viewerOf('not-a-token')).rejects.toThrow(EmbedTokenError);
+  });
+});
+
 describe('EmbedService: the roles.yaml write gate', () => {
   const ROLES = `${KB}/roles.yaml`;
   const VALID = 'roles:\n  Admin:\n    - a@x.eu\n';

package/src/modules/embed/__tests__/embed.tools.test.ts

@@ -2,6 +2,7 @@ import type { Server } from 'node:http';
 import type { AddressInfo } from 'node:net';
 import express from 'express';
 import { afterEach, describe, expect, it, vi } from 'vitest';
+import { checkFor } from '@bevel-software/platform-mcp-core';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
 import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
 import { ToolError, type ToolContext } from '../../tool-helpers/tool.contract.js';
@@ -122,6 +123,21 @@ describe('open_page: the listing', () => {
     expect(internal).not.toContain(OPEN_PAGE_TOOL);
   });
 
+  /**
+   * The chat view renews its token by having its host call this tool with
+   * `{ body: { path, heading } }` (see `mcp-app/page.html`). The listing's
+   * own check decides what `/api/mcp` accepts: that shape passes it, and the
+   * flat one the view once sent is refused, so no token ever came back.
+   */
+  it("accepts the chat view's renewal arguments under body, and refuses them flat", async () => {
+    const { registry } = await serve();
+    const def = (await registry.listExternal()).find((t) => t.name === OPEN_PAGE_TOOL)!;
+    const compiled = checkFor(def.inputs);
+    if (!compiled.checkable) throw new Error(`open_page's schema is not checkable: ${compiled.reason}`);
+    expect(compiled.check({ body: { path: 'Data/Thing.md', heading: 'what-it-is' } })).toEqual([]);
+    expect(compiled.check({ path: 'Data/Thing.md', heading: 'what-it-is' })).not.toEqual([]);
+  });
+
   it('takes a path and an optional heading, and no branch at all', async () => {
     const { registry } = await serve();
     const def = (await registry.listExternal()).find((t) => t.name === OPEN_PAGE_TOOL)!;
@@ -197,6 +213,19 @@ describe('open_page: the answer', () => {
     expect(body.appUrl).toContain('#what-it-is');
   });
 
+  /**
+   * The view renews its token by calling this tool again with the arguments
+   * it was opened with, and the result is all it is told — so the heading
+   * comes back beside the path, and is absent when none was named.
+   */
+  it('echoes the heading beside the path, for the view to call again with', async () => {
+    const { call } = await serve();
+    const { body } = await call({ path: 'Data/Thing.md', heading: 'what-it-is' });
+    expect(body).toMatchObject({ path: 'Data/Thing.md', heading: 'what-it-is' });
+    const plain = await call({ path: 'Data/Thing.md' });
+    expect(plain.body).not.toHaveProperty('heading');
+  });
+
   it('accepts a path with or without the knowledge-base prefix, as read_file documents', async () => {
     const { call, mints } = await serve();
     await call({ path: 'Data/Thing.md' });

package/src/modules/embed/embed.interface.ts

@@ -103,6 +103,19 @@ export interface EmbedLinkedAccount {
  */
 export type EmbedNodeIdResolver = (nodeId: string) => Promise<string | null>;
 
+/** The viewer behind a token, as {@link IEmbedService.viewerOf} answers it. */
+export interface EmbedViewer {
+  /** Whether the token's identity resolved to a user at all. */
+  linked: boolean;
+  /** The linked user; null when unlinked. */
+  user: AuthUser | null;
+  /** Read access on the token's file — always false when unlinked. */
+  canRead: boolean;
+  canWrite: boolean;
+  /** The token's file, repository-relative. */
+  repoRelative: string;
+}
+
 /**
  * What the embed service needs of the workspace: the clone of a branch, and
  * four verbs on one file of it. A port rather than the workspace service
@@ -165,6 +178,17 @@ export interface IEmbedService {
   /** Load the file the token is scoped to, with the viewer's read/write status. */
   loadFile(token: string): Promise<EmbedFileView>;
 
+  /**
+   * Who is looking through `token`, and at what: the resolved viewer (the
+   * linked user, or none), their read and write verdicts on the token's
+   * file, and the file. The one answer a distribution's own token-authed
+   * route beside this surface (a graph for a dashboard, say) asks before it
+   * serves anything, so it judges the viewer exactly as the embed does — the
+   * same token check, the same account link, the same switched-off refusal.
+   * Throws as `loadFile` throws for a token that is invalid or expired.
+   */
+  viewerOf(token: string): Promise<EmbedViewer>;
+
   /**
    * The raw bytes of the embedded file, or of one asset `path` beside it (an
    * image a markdown page shows — a file no reader edits as text, or an SVG,

package/src/modules/embed/embed.service.ts

@@ -1,6 +1,5 @@
 import { createHmac } from 'node:crypto';
-import { timingSafeStringEqual } from '../auth/password-hash.js';
-import { ACCOUNT_DEACTIVATED_MESSAGE } from '../auth/account-admission.js';
+import { ACCOUNT_DEACTIVATED_MESSAGE, timingSafeStringEqual } from '../auth/index.js';
 import jwt from 'jsonwebtoken';
 import type { AuthUser, IGitService, IWorkflowService } from '@bevel-software/platform-shared';
 import { suggestionsBranchPrefixFor } from '@bevel-software/platform-shared';
@@ -8,9 +7,9 @@ import { logger } from '../../shared/logging.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
-import { changeRequestLink, changeRequestLinkBase } from '../workflow/git/change-request-link.js';
-import type { FileReaderRegistry } from '../workspace/file-readers/file-reader.js';
-import type { WriteValidator } from '../kb-fs/locking-filesystem.js';
+import { changeRequestLink, changeRequestLinkBase } from '../workflow/index.js';
+import type { FileReaderRegistry } from '../workspace/index.js';
+import type { WriteValidator } from '../kb-fs/index.js';
 import type {
   EmbedAuthPort,
   EmbedFileView,
@@ -21,6 +20,7 @@ import type {
   EmbedProposalResult,
   EmbedSubject,
   EmbedTokenResult,
+  EmbedViewer,
   IEmbedService,
 } from './embed.interface.js';
 import {
@@ -35,16 +35,24 @@ import type { IAccountLinkService } from './account-link.service.js';
 const log = logger('embed');
 
 /**
- * Token lifetime — long enough for a view left open in a chat, short enough
- * that a token copied out of a transcript stops working on its own. The
- * token rides in `open_page`'s result, so it sits in the chat transcript, and
- * whoever holds it reads and edits that one file as the token's user until
- * it expires. One hour (Razvan, 2026-10-09; the embed used two before): a
- * page left open in a chat is still covered, and the window is halved. A
- * view older than that shows the expired sentence and the agent opens the
- * page again.
+ * Lifetime of a token `open_page` mints (`kind: user`). The token rides in
+ * the tool's result, so it sits in the chat transcript, and whoever holds it
+ * reads and edits that one file as the token's user until it expires. Five
+ * minutes (Razvan, 2026-10-09; one hour before, two before that): a token
+ * copied out of a transcript stops working almost at once. A view left open
+ * longer is not ended by it — the MCP App view asks its host to call
+ * `open_page` again when a call is refused for the token, and carries on with
+ * the fresh one (see `mcp-app/page.html`).
  */
-export const EMBED_TOKEN_TTL_SECONDS = 60 * 60;
+export const EMBED_USER_TOKEN_TTL_SECONDS = 5 * 60;
+
+/**
+ * Lifetime of a token the Atlassian connector mints through the shared-secret
+ * route (`kind: atlassian`). One hour, unchanged: the connector frames
+ * `/embed` directly and has no host to renew a token through, and its mint
+ * contract does not change (Decision 9 of the parent specification).
+ */
+export const EMBED_CONNECTOR_TOKEN_TTL_SECONDS = 60 * 60;
 
 /** What the embed's config needs from the deployment's. */
 export interface EmbedConfig {
@@ -148,7 +156,11 @@ export class EmbedService implements IEmbedService {
     if (!this.authService.isEmailDomainAllowed(email ?? '')) {
       throw new EmbedAccessError('Your email domain is not permitted to view this content');
     }
-    return this.mint({ kind: 'atlassian', accountId: input.accountId }, input.reference);
+    const minted = await this.mint({ kind: 'atlassian', accountId: input.accountId }, input.reference);
+    // The connector's host sizes its frame to the content (the issue panel
+    // grows with the page), so its view is told to report its height; the
+    // MCP path says nothing, and its host's fixed reading pane stays.
+    return { ...minted, embedUrl: this.embedUrlFor(minted.token, { sizing: 'content' }) };
   }
 
   /**
@@ -195,13 +207,20 @@ export class EmbedService implements IEmbedService {
       repoRelative,
       slug: ref.slug,
     };
-    const token = jwt.sign(claims, this.signingKey, { expiresIn: EMBED_TOKEN_TTL_SECONDS });
+    const expiresIn =
+      subject.kind === 'user' ? EMBED_USER_TOKEN_TTL_SECONDS : EMBED_CONNECTOR_TOKEN_TTL_SECONDS;
+    const token = jwt.sign(claims, this.signingKey, { expiresIn });
     return { token, embedUrl: this.embedUrlFor(token) };
   }
 
-  /** The view's address — what a host frames. */
-  embedUrlFor(token: string): string {
-    return `${this.config.publicFrontendUrl}/embed?token=${encodeURIComponent(token)}`;
+  /**
+   * The view's address — what a host frames. `sizing: 'content'` tells the
+   * view its host sizes the frame to the content and wants the height
+   * reported; absent, the host's fixed pane is kept.
+   */
+  embedUrlFor(token: string, opts: { sizing?: 'content' } = {}): string {
+    const sizing = opts.sizing === 'content' ? '&sizing=content' : '';
+    return `${this.config.publicFrontendUrl}/embed?token=${encodeURIComponent(token)}${sizing}`;
   }
 
   /** A file's address in the app — what a link opens in a new tab. */
@@ -556,6 +575,12 @@ export class EmbedService implements IEmbedService {
     return { claims, user, wsPath: this.wsPathFor(claims.repoRelative) };
   }
 
+  async viewerOf(token: string): Promise<EmbedViewer> {
+    const claims = this.verifyToken(token);
+    const identity = await this.resolveIdentity(claims);
+    return { ...identity, repoRelative: claims.repoRelative };
+  }
+
   /** Resolve the token's identity to a user + read/write verdicts. */
   private async resolveIdentity(claims: EmbedClaims): Promise<ResolvedIdentity> {
     const unresolved: ResolvedIdentity = { linked: false, user: null, canRead: false, canWrite: false };

package/src/modules/embed/embed.tools.ts

@@ -104,6 +104,10 @@ export function registerEmbedTools(
       type: 'object',
       properties: {
         path: { type: 'string', description: 'The path that was shown (echoes the input).' },
+        heading: {
+          type: 'string',
+          description: 'The heading the view opens at (echoes the input). Absent when none was named.',
+        },
         content: { type: 'string', description: "The page's text, exactly as `read_file` answers it." },
         embedUrl: {
           type: 'string',
@@ -163,12 +167,16 @@ export function registerEmbedTools(
         result.kind === 'text' ? result.text : result.kind === 'image' ? result.note : result.message;
 
       const appUrl = deps.appUrlFor(repoRelative, heading);
+      // The heading goes back beside the path: the view calls this tool again
+      // with both when its token runs out (see `mcp-app/page.html`), and a
+      // result is all it is told.
+      const echoed = heading ? { heading } : {};
       // No view on a plain-http deployment (Decision 8): a host's https
       // sandbox cannot load from it. The text and the app address are still
       // the answer, and the tool says why there is no view rather than
       // handing back an address no host can open.
       if (!deps.canBeReached()) {
-        return { path: raw, content, appUrl, branch, note: HTTP_DEPLOYMENT_NOTE };
+        return { path: raw, ...echoed, content, appUrl, branch, note: HTTP_DEPLOYMENT_NOTE };
       }
       // Minted for the identity THIS MCP session authenticated — the
       // signed-in user, or the owner of the connection key the agent carries.
@@ -178,7 +186,7 @@ export function registerEmbedTools(
         userId: ctx.user.id,
         reference: heading ? `${repoRelative}#${heading}` : repoRelative,
       });
-      return { path: raw, content, embedUrl, appUrl, branch };
+      return { path: raw, ...echoed, content, embedUrl, appUrl, branch };
     }),
   );
 }

package/src/modules/kb-fs/index.ts

@@ -0,0 +1,6 @@
+/**
+ * What the kb-fs module offers the other modules. The filesystem and the
+ * locks are wired by the composition root; a module that writes through the
+ * workspace needs only the shape of the gate every write passes first.
+ */
+export type { WriteValidator } from './locking-filesystem.js';

package/src/modules/plugins/__tests__/join-request-jobs.service.test.ts

@@ -1,11 +1,10 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { DEFAULT_BRANCH, joinBranchFor } from '@bevel-software/platform-shared';
-import {
-  PluginJoinRequestJobs,
-  JoinRequestNotReadyError,
-  type JoinRequestJobsDeps,
-  CLAIM_STALE_AFTER_MS,
-} from '../join-request-jobs.service.js';
+import { DrizzleQueryError } from 'drizzle-orm';
+import { PluginJoinRequestJobs, JoinRequestNotReadyError, type JoinRequestJobsDeps } from '../index.js';
+// The claim window is not part of the module's surface: a test that moves
+// the clock past it reads the number the service itself uses.
+import { CLAIM_STALE_AFTER_MS } from '../join-request-jobs.service.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { FakeJoinRequestStore } from './fake-join-request-store.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
@@ -146,6 +145,48 @@ describe('PluginJoinRequestJobs', () => {
     expect(row.failureReason).not.toContain('ghp_secret');
   });
 
+  it("logs a database failure as the database's reason, and shows the requester one stable sentence", async () => {
+    const h = harness();
+    // What Drizzle throws: its own error class, the SQL in the message, the
+    // driver's error as the cause.
+    h.workflow.openChangeRequest.mockRejectedValue(
+      new DrizzleQueryError(
+        'insert into "change_requests" ("id", "number", "title", "body", "source_branch", "target_branch", "author_id", "status", "created_at", "updated_at") values ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)',
+        [],
+        new Error('relation "change_requests" does not exist'),
+      ),
+    );
+    await h.jobs.start(pendingRow(h.store));
+
+    // The operator gets the reason, not the wrapper's cut-off SQL…
+    const logged = consoleError.mock.calls.map((c) => String(c[0]));
+    // (`printable` renders the reason as a JSON string, so its own quotes come escaped.)
+    expect(logged).toContainEqual(expect.stringMatching(/failed: "relation \\"change_requests\\" does not exist"/));
+    expect(logged.some((l) => l.includes('Failed query'))).toBe(false);
+    // …and the requester's card names no table.
+    const [row] = h.store.all();
+    expect(row.status).toBe('failed');
+    expect(row.failureReason).toBe('the request could not be recorded; an admin can find the reason in the server log');
+  });
+
+  it("shows the requester a wrapped failure's own words when it is not the database's", async () => {
+    const h = harness();
+    // The git work failing behind a wrapper of its own: the cause is what is
+    // logged, and what the requester reads, credentials stripped — the
+    // database's stable sentence would hide the detail they can act on.
+    h.workflow.openChangeRequest.mockRejectedValue(
+      new Error('opening the change request failed', {
+        cause: new Error('fatal: unable to access https://x:ghp_secret@github.com/acme/kb: could not resolve host'),
+      }),
+    );
+    await h.jobs.start(pendingRow(h.store));
+    const [row] = h.store.all();
+    expect(row.status).toBe('failed');
+    expect(row.failureReason).toContain('unable to access');
+    expect(row.failureReason).not.toContain('ghp_secret');
+    expect(row.failureReason).not.toContain('could not be recorded');
+  });
+
   it('fails the record rather than throwing when the plugin is gone', async () => {
     const h = harness({ target: async () => null });
     await expect(h.jobs.start(pendingRow(h.store))).resolves.toBeUndefined();
@@ -524,6 +565,32 @@ describe('PluginJoinRequestJobs', () => {
     expect(h.workflow.openChangeRequest).not.toHaveBeenCalled();
   });
 
+  it("a sweep that cannot read the table logs the database's reason, not the wrapper's cut-off SQL", async () => {
+    vi.useFakeTimers();
+    const warned = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const h = harness();
+      // What Drizzle throws: its own error class, the SQL in the message, the driver's error underneath.
+      const wrapped = new DrizzleQueryError(
+        'select "id", "requester_email", "requester_email_bidx", "requester_name", "plugin_key", "status", "failure_reason", "change_request_number", "claimed_at", "claim_token", "created_at" from "plugin_join_requests" where status = $1',
+        [],
+        new Error('Cannot use a pool after calling end on the pool'),
+      );
+      h.store.pending = async () => {
+        throw wrapped;
+      };
+      h.jobs.startSweeping(1000);
+      await vi.advanceTimersByTimeAsync(0);
+      h.jobs.stopSweeping();
+      const lines = warned.mock.calls.map((c) => String(c[0]));
+      expect(lines).toHaveLength(1);
+      expect(lines[0]).toContain('could not look at the join requests still owed: "Cannot use a pool after calling end on the pool"');
+      expect(lines[0]).not.toContain('Failed query');
+    } finally {
+      warned.mockRestore();
+    }
+  });
+
   it('proceeds past a createBranch failure only when the branch is really there', async () => {
     const h = harness();
     const branch = joinBranchFor(ALI, 'Finance');

package/src/modules/plugins/join-request-jobs.service.ts

@@ -4,6 +4,7 @@ import {
   type ChangeRequestState,
   type IWorkflowService,
 } from '@bevel-software/platform-shared';
+import { DrizzleQueryError } from 'drizzle-orm';
 import { spliceGrant } from '../access-model/access-splice.js';
 import { sanitizeError } from '../workflow/sanitize-error.js';
 import { logger } from '../../shared/logging.js';
@@ -358,12 +359,12 @@ export class PluginJoinRequestJobs {
    */
   startSweeping(intervalMs: number = SWEEP_INTERVAL_MS): void {
     void this.sweep().catch((err: unknown) => {
-      log.warn(`could not look at the join requests still owed: ${loggable(sanitizeError(err))}`);
+      log.warn(`could not look at the join requests still owed: ${loggable(sanitizeError(underlying(err)))}`);
     });
     if (this.sweepTimer) return;
     this.sweepTimer = setInterval(() => {
       void this.sweep().catch((err: unknown) => {
-        log.warn(`could not look at the join requests still owed: ${loggable(sanitizeError(err))}`);
+        log.warn(`could not look at the join requests still owed: ${loggable(sanitizeError(underlying(err)))}`);
       });
     }, intervalMs);
     // Never a reason for the process to stay alive: every row is durable, and
@@ -398,7 +399,7 @@ export class PluginJoinRequestJobs {
     // wrap the whole attempt: the claim has to be refreshed for as long as
     // the work runs, and the work is the part that can take minutes.
     const live = await this.store.claim(record.id, CLAIM_STALE_AFTER_MS).catch((err: unknown) => {
-      log.warn(`could not claim a join request: ${loggable(sanitizeError(err))}`);
+      log.warn(`could not claim a join request: ${loggable(sanitizeError(underlying(err)))}`);
       return null;
     });
     if (!live) {
@@ -426,7 +427,7 @@ export class PluginJoinRequestJobs {
         if (!still) held = false;
         return still ? 'held' : 'lost';
       } catch (err: unknown) {
-        log.warn(`could not refresh a join-request claim: ${loggable(sanitizeError(err))}`);
+        log.warn(`could not refresh a join-request claim: ${loggable(sanitizeError(underlying(err)))}`);
         return 'unknown';
       }
     };
@@ -453,7 +454,10 @@ export class PluginJoinRequestJobs {
         if (state !== 'held') throw new ClaimLostError(state);
       });
     } catch (err) {
-      const reason = sanitizeError(err);
+      // The cause when there is one (see `underlying`), for the log; a
+      // database's reason, where a wrapper's cut-off column list is not.
+      const cause = underlying(err);
+      const reason = sanitizeError(cause);
       // `pluginKey` is a persisted folder path, so it is escaped before it
       // reaches a log line: a folder carrying control characters could
       // otherwise write newlines of its own into the log.
@@ -473,22 +477,31 @@ export class PluginJoinRequestJobs {
         // claim held by a process that never really started.
         log.warn(`join request for ${key} postponed: ${loggable(reason)}`);
         await this.store.release(record.id, live.claimToken).catch((releaseErr: unknown) => {
-          log.warn(`could not release that claim: ${loggable(sanitizeError(releaseErr))}`);
+          log.warn(`could not release that claim: ${loggable(sanitizeError(underlying(releaseErr)))}`);
         });
         return;
       }
       log.error(`join request for ${key} failed: ${loggable(reason)}`);
+      // What the requester reads on their card. The git work's own words
+      // are theirs to see (credentials stripped); a database's reason is
+      // not — it names tables and columns and is for the operator, who has
+      // it in the line above — so a database failure is recorded in one
+      // stable sentence. The database's failures are the ones the query
+      // layer wraps (`DrizzleQueryError`, its cause the driver's error);
+      // any other wrapped error keeps its own sanitised words, which may be
+      // what the requester needs to act on.
+      const shown = err instanceof DrizzleQueryError ? DATABASE_FAILURE_REASON : reason;
       await this.store
         // Named with the token, so this lands only if the row is still this
         // process's. A worker that overran the window and had its row taken
         // writes nothing here rather than stamping its failure on the attempt
         // that replaced it — which would show the requester a failure for
         // work that is, at that moment, succeeding.
-        .markFailed(record.id, live.claimToken, reason)
+        .markFailed(record.id, live.claimToken, shown)
         // Nothing left to do if even that write fails: the row stays
         // `pending` and the next boot's sweep tries the whole thing again.
         .catch((writeErr: unknown) => {
-          log.error(`could not record that failure: ${loggable(sanitizeError(writeErr))}`);
+          log.error(`could not record that failure: ${loggable(sanitizeError(underlying(writeErr)))}`);
         });
     } finally {
       held = false;
@@ -669,6 +682,30 @@ function loggable(reason: string): string {
   return printable(reason);
 }
 
+/**
+ * The error behind a wrapped one. Drizzle reports a failed query as its own
+ * error whose message is the SQL and whose `cause` is the database's reason;
+ * the sanitizer caps a message at a couple of hundred characters, so logging
+ * the wrapper showed a cut-off column list and never the reason. The reason
+ * is what every LOG line this service writes needs — "the pool has been
+ * ended", "relation does not exist" — the sweep's warning, the claim and
+ * heartbeat warnings, the failure line. The requester's card is the one
+ * place it does not go: a wrapped failure is recorded there as
+ * `DATABASE_FAILURE_REASON`, since a table name is the operator's to read.
+ * An error with no cause (git's, the claim's own) is reported as it is.
+ */
+function underlying(err: unknown): unknown {
+  const cause = typeof err === 'object' && err !== null ? (err as { cause?: unknown }).cause : undefined;
+  return cause instanceof Error ? cause : err;
+}
+
+/**
+ * The sentence a requester's card carries when the database, not the git
+ * work, refused the request: stable, and naming no table or column. The
+ * database's own words go to the server log beside it.
+ */
+const DATABASE_FAILURE_REASON = 'the request could not be recorded; an admin can find the reason in the server log';
+
 /** Node's "there is no such file" errors, and only those. */
 function isFileAbsent(err: unknown): boolean {
   const code = (err as NodeJS.ErrnoException | null)?.code;

package/src/modules/skills/__tests__/branch-skills.tools.test.ts

@@ -154,7 +154,7 @@ describe('the skill tools read a branch when asked', () => {
       skills: { name: string; unmerged?: boolean }[];
     };
     expect(listArgs).toEqual([['e@x', { branch: undefined }]]);
-    expect(body.skills).toEqual([{ name: 'rfi', description: 'RFI.', path: released.path }]);
+    expect(body.skills).toEqual([{ name: 'rfi', description: 'RFI.', path: released.path, canWrite: false }]);
   });
 
   it('a blank branch is no branch at all: the released catalog answers', async () => {

package/src/modules/skills/skills.contract.ts

@@ -52,6 +52,10 @@ export interface SkillSummary {
   unmerged?: true;
   /** With `unmerged`: the branch the skill was read from. */
   branch?: string;
+  // No `canWrite` here, on purpose: whether the caller may change a skill
+  // directly is a per-caller verdict the agent tools add onto a COPY of each
+  // summary (`skills.tools.ts`). The catalog is cached across users, so a
+  // verdict stored on it would be served to the next caller.
 }
 
 export interface Skill extends SkillSummary {