@bevel-software/platform-core-backend 0.32.0 → 0.34.0

package/src/modules/database/core-schema.ts

@@ -10,7 +10,7 @@
  * `externalApiKeys`) from here. `schema.ts` re-exports both, so existing
  * imports keep working unchanged.
  *
- * PII columns (emails, display names, change-request/comment text) are
+ * PII columns (emails, display names, change-request text) are
  * `encryptedText` — AES-256-GCM ciphertext in the database, transparently
  * decrypted on read (see `shared/column-crypto.ts`). Because the ciphertext is
  * randomized, equality lookups and unique constraints on those columns go
@@ -41,6 +41,16 @@ export const users = pgTable('users', {
    * until an admin (or the user, from their Account page) sets one.
    */
   passwordHash: text('password_hash'),
+  /**
+   * Which generation of this account's sessions is honoured. Every session
+   * token carries the value it was issued at (`sv`; a token from before the
+   * column existed carries none and counts as 0), and one whose value is not
+   * the row's is refused. Changing the password moves it on, so every session
+   * opened with the old password ends at its next request — the one that
+   * made the change is handed a fresh token. Connection keys are not
+   * sessions and do not look at it.
+   */
+  sessionVersion: integer('session_version').default(0).notNull(),
   /**
    * The one onboarding fact the server keeps: has this person concluded the
    * connect-your-agent setup (the welcome page's Done, or the reminder
@@ -128,40 +138,6 @@ export const prMergeLog = pgTable('pr_merge_log', {
   byPr: index('pr_merge_log_by_pr').on(t.prNumber),
 }));
 
-/**
- * In-app PR comments. GitHub is authoritative for the diff + PR metadata;
- * Bevel owns the review conversation. Comments never round-trip to GitHub.
- *
- * Shape encodes three comment kinds:
- *   • General PR comment        — path null, line null
- *   • File-level comment        — path set,  line null
- *   • Inline (line-anchored)    — path set,  line set
- *
- * Threading: replies point at their root via `parentId`. Root comments have
- * `parentId = null`. We use a self-FK-less column (no DB-side constraint) to
- * keep the parent row independently deletable — the service layer tolerates
- * orphan replies rather than cascading deletes and losing discussion context.
- */
-export const prComments = pgTable('pr_comments', {
-  id: uuid('id').defaultRandom().primaryKey(),
-  prNumber: integer('pr_number').notNull(),
-  authorEmail: encryptedText('author_email').notNull(),
-  /** Blind index of `author_email` — GDPR-erasure lookup. */
-  authorEmailBidx: blindIndexText('author_email_bidx').notNull(),
-  authorName: encryptedText('author_name').notNull(),
-  path: text('path'),
-  line: integer('line'),
-  headSha: text('head_sha').notNull(),
-  // Encrypted: review conversation exists only in this DB (never on GitHub).
-  body: encryptedText('body').notNull(),
-  parentId: uuid('parent_id'),
-  createdAt: timestamp('created_at').defaultNow().notNull(),
-  updatedAt: timestamp('updated_at'),
-}, (t) => ({
-  byPr: index('pr_comments_by_pr').on(t.prNumber),
-  byThread: index('pr_comments_by_thread').on(t.prNumber, t.path, t.line),
-}));
-
 /**
  * Change requests (the app's own "pull request" model). The app used to lean on
  * GitHub PRs via the `gh` CLI; now a change request is a plain DB row plus git
@@ -169,7 +145,7 @@ export const prComments = pgTable('pr_comments', {
  * hosted) works — the remote only stores commits/branches.
  *
  * `number` is the human-facing id and the join key the sibling tables
- * (`pr_file_approvals`, `pr_comments`, `pr_merge_log`) reference in their
+ * (`pr_file_approvals`, `pr_merge_log`) reference in their
  * `pr_number` column — those columns now hold THIS number, not a GitHub PR
  * number. It's a DB-assigned identity so allocation is race-free.
  *
@@ -187,7 +163,24 @@ export const changeRequests = pgTable('change_requests', {
   // is deliberately stored unencrypted (see encryptPii), so a defaulted row
   // and an app-written empty body hold the identical representation.
   title: encryptedText('title').notNull(),
+  /**
+   * The request's description, and nothing else: exactly what its author (or
+   * a later edit) wrote. Hexis keeps none of its own facts in here — who must
+   * approve each file is resolved live from the access rules, and an access
+   * request's level and note have columns of their own below. Bodies written
+   * before this release carried both as prose and hidden markers; the first
+   * start on it moves them out (`moveLegacyRequestBodies` in `migrate.ts`).
+   */
   body: encryptedText('body').notNull().default(''),
+  /**
+   * Set on a request the access-request flow opened: the level the person
+   * asked for. Null on every other request. Read back by that flow to say
+   * "Requested: Owner" from the request itself, whose row is always readable,
+   * rather than from a branch a stale clone may not see yet.
+   */
+  accessRequestLevel: text('access_request_level'),
+  /** The requester's note, when they wrote one. Encrypted: a person's own words. */
+  accessRequestNote: encryptedText('access_request_note'),
   authorEmail: encryptedText('author_email').notNull(), // lowercased at insert
   /** Blind index of `author_email` — GDPR-erasure lookup. */
   authorEmailBidx: blindIndexText('author_email_bidx').notNull(),
@@ -242,6 +235,10 @@ export const changeRequests = pgTable('change_requests', {
     'change_requests_state_check',
     sql`${t.state} IN ('open', 'merged', 'closed')`,
   ),
+  accessRequestLevelCheck: check(
+    'change_requests_access_request_level_check',
+    sql`${t.accessRequestLevel} IS NULL OR ${t.accessRequestLevel} IN ('write', 'owner')`,
+  ),
 }));
 
 /**
@@ -290,6 +287,15 @@ export const externalApiKeys = pgTable('api_tokens', {
    * deleted in one step.
    */
   deletedAt: timestamp('deleted_at'),
+  /**
+   * The agent configuration the key connects as — a repo-relative knowledge-base
+   * path, chosen when the key is minted. Null is Everything: the key sees
+   * every tool, skill and plugin its owner may read, exactly as before the
+   * column existed. The path is the whole record: the file is re-read on
+   * every surface build, so editing it changes what the key sees without a
+   * new key (see `modules/agent-scope`).
+   */
+  agentPath: text('agent_path'),
 }, (t) => ({
   byUser: index('api_tokens_by_user').on(t.userId),
 }));
@@ -499,6 +505,12 @@ export const oauthAuthCodes = pgTable('oauth_auth_codes', {
   expiresAt: timestamp('expires_at').notNull(),
   consumedAt: timestamp('consumed_at'),
   createdAt: timestamp('created_at').defaultNow().notNull(),
+  /**
+   * The "Connect as" choice made on the consent step, carried from Finish to
+   * the token exchange that makes (or finds) the agent connection — the code
+   * is the only thing that travels between the two. Null is Everything.
+   */
+  agentPath: text('agent_path'),
 }, (t) => ({
   // Sweep expired/spent rows without a full scan.
   byExpiry: index('oauth_auth_codes_by_expiry').on(t.expiresAt),
@@ -538,6 +550,14 @@ export const agentConnections = pgTable('agent_connections', {
   revokedAt: timestamp('revoked_at'),
   /** `owner` | `admin` — who ended it; null while live. Same vocabulary as `api_tokens.revoked_by`. */
   revokedBy: text('revoked_by'),
+  /**
+   * The agent configuration the person chose to connect as on the consent step — a
+   * repo-relative knowledge-base path — or null for Everything. Set by every
+   * consent that lands on the row, so re-authorising with another choice
+   * changes what the agent sees from its next request. Same meaning as
+   * `api_tokens.agent_path`.
+   */
+  agentPath: text('agent_path'),
 }, (t) => ({
   byUser: index('agent_connections_by_user').on(t.userId),
   liveUnq: uniqueIndex('agent_connections_live_unq')
@@ -883,3 +903,23 @@ export const atlassianAccountLinks = pgTable('atlassian_account_links', {
 }, (t) => ({
   byUser: index('atlassian_account_links_by_user').on(t.userId),
 }));
+
+/**
+ * The ledger of the DATA halves of migrations: the rewrites SQL cannot do
+ * because they read sealed columns, run by the application right after the
+ * SQL history under the same lock (`migrate.ts`). One row per pass, written
+ * in the SAME transaction as the rows it rewrote, so a pass is recorded done
+ * exactly when its work is — a crash between the SQL history's own ledger
+ * and the pass leaves no row here, and the next start runs the pass. Drizzle's
+ * `__drizzle_migrations_core` ledger records only the SQL.
+ *
+ * The PII backfill of migration 0016 predates this table and keeps its own
+ * marker (the nullability of the blind-index columns it finalises).
+ */
+export const dataMigrations = pgTable('data_migrations', {
+  /** The pass, named after the migration whose data half it is: `0020_change_request_body_is_the_description`. */
+  name: text('name').primaryKey(),
+  appliedAt: timestamp('applied_at').defaultNow().notNull(),
+  /** What the pass did, for an operator reading the ledger: rows moved, say. */
+  note: text('note'),
+});

package/src/modules/database/index.ts

@@ -0,0 +1,9 @@
+/**
+ * What the database module offers the other modules. A consumer outside the
+ * module imports from here, never from the files: they are the module's own
+ * layout and free to move. Export what another module needs; nothing more.
+ */
+export type { Database } from './connection.js';
+export { deploymentSettings } from './core-schema.js';
+export { pgErrorCode } from './pg-error.js';
+export { agentConnections, agentEvents, atlassianAccountLinks, changeRequests, externalApiKeys, fileLocks, githubFacadeCodes, githubFacadeIdentity, oauthAuthCodes, oauthClients, oauthTokens, pendingCommits, pluginJoinRequests, prFileApprovals, prMergeLog, secrets, users } from './schema.js';

package/src/modules/database/migrate.ts

@@ -1,6 +1,8 @@
 import { migrate } from 'drizzle-orm/node-postgres/migrator';
-import { sql } from 'drizzle-orm';
+import { eq, sql } from 'drizzle-orm';
+import { parseLegacyChangeRequestBody } from '@bevel-software/platform-shared';
 import { logger } from '../../shared/logging.js';
+import { changeRequests, dataMigrations } from './core-schema.js';
 
 const log = logger('database');
 import { DEFAULT_DB_SCHEMA, dbSchemaOf, piiKeysOf, type Database } from './connection.js';
@@ -74,11 +76,87 @@ export async function runCoreMigrations(db: Database, folder: string): Promise<v
       // Under the same lock, before anything reads or writes a PII column:
       // the data half of migration 0016, which SQL cannot do (see below).
       await runPiiEncryptionBackfill(db);
+      // And the data half of 0020, recorded in `data_migrations` by the
+      // transaction that does it: a start that crashed between the SQL
+      // history's ledger and this pass finds no row and runs it.
+      await moveLegacyRequestBodies(db);
     },
     { tenantKey },
   );
 }
 
+/** The `data_migrations` row of the body move: present exactly when the move has been committed. */
+const LEGACY_REQUEST_BODIES_MOVED = '0020_change_request_body_is_the_description';
+
+/**
+ * The data half of migration 0020, which makes a request's body nothing but
+ * its description. Bodies written before it carried three other things: an
+ * `## Affected owners` block `openChangeRequest` appended (a snapshot of the
+ * eligible approvers that nothing read back — they are resolved live, per
+ * file), an access request's level and note in hidden markers (which the
+ * access-request flow parsed back out of the prose), and identity markers
+ * from the time a service account opened requests for people. Every body is
+ * read once here, under the handle's key, the level and the note are moved
+ * onto their own columns, and the prose is written back without the rest.
+ *
+ * ONE transaction: the rows it rewrites and the `data_migrations` row that
+ * records it commit together, or not at all. So the pass runs exactly once —
+ * on the start that first finds no ledger row, which is the start that applies
+ * 0020 or, if that start died between drizzle's own ledger and this pass, the
+ * next one — and never again: a body of the new shape is already clean, and
+ * the grammar this reads is written by nothing. A start that finds the row
+ * reads nothing.
+ *
+ * What the transaction does NOT do is fence the old version: its rows are
+ * read `FOR UPDATE`, which only makes an old-version edit of an existing row
+ * wait for the move, and a request the old version opens after the move has
+ * committed is stored in the old shape and never rewritten. That is why the
+ * upgrade requires the old version to be stopped before the new one starts
+ * (UPGRADING.md, "Stop the old version before the new one starts"), as the
+ * personal-data backfill of 0016 already did; this pass adds no mechanism of
+ * its own, and a rolling update across this release is not supported.
+ *
+ * Walked row by row rather than in one UPDATE because the column is sealed:
+ * SQL can neither read the marker nor write the cleaned text. Reached only
+ * through {@link runCoreMigrations}, and observed through what it leaves:
+ * the rows and the ledger.
+ */
+async function moveLegacyRequestBodies(db: Database): Promise<void> {
+  await db.transaction(async (tx) => {
+    const done = await tx
+      .select({ name: dataMigrations.name })
+      .from(dataMigrations)
+      .where(eq(dataMigrations.name, LEGACY_REQUEST_BODIES_MOVED))
+      .limit(1);
+    if (done.length > 0) return;
+
+    const rows = await tx
+      .select({ id: changeRequests.id, body: changeRequests.body })
+      .from(changeRequests)
+      .orderBy(changeRequests.id)
+      .for('update');
+    let moved = 0;
+    for (const row of rows) {
+      const legacy = parseLegacyChangeRequestBody(row.body);
+      if (!legacy.changed) continue;
+      await tx
+        .update(changeRequests)
+        .set({
+          body: legacy.description,
+          ...(legacy.accessRequestLevel ? { accessRequestLevel: legacy.accessRequestLevel } : {}),
+          ...(legacy.accessRequestNote ? { accessRequestNote: legacy.accessRequestNote } : {}),
+        })
+        .where(eq(changeRequests.id, row.id));
+      moved += 1;
+    }
+    await tx.insert(dataMigrations).values({
+      name: LEGACY_REQUEST_BODIES_MOVED,
+      note: `${moved} of ${rows.length} change-request bodies moved to the description-only shape`,
+    });
+    log.info(`Change-request bodies: ${moved} of ${rows.length} moved to the description-only shape.`);
+  });
+}
+
 /**
  * Apply the ENTERPRISE migration history from `folder`, tracked in
  * `__drizzle_migrations_enterprise`. Run AFTER {@link runCoreMigrations} —
@@ -220,7 +298,6 @@ const PII_BACKFILL_TABLES: PiiBackfillTable[] = [
   { table: 'users', key: ['id'], encrypted: ['email', 'name', 'avatar_url'], bidx: { source: 'email', column: 'email_bidx' } },
   { table: 'pr_file_approvals', key: ['id'], encrypted: ['approver_email', 'approver_name'], bidx: { source: 'approver_email', column: 'approver_email_bidx' } },
   { table: 'pr_merge_log', key: ['id'], encrypted: ['triggered_by_email', 'triggered_by_name', 'error'], bidx: { source: 'triggered_by_email', column: 'triggered_by_email_bidx' } },
-  { table: 'pr_comments', key: ['id'], encrypted: ['author_email', 'author_name', 'body'], bidx: { source: 'author_email', column: 'author_email_bidx' } },
   { table: 'change_requests', key: ['id'], encrypted: ['author_email', 'author_name', 'title', 'body', 'apply_failure_reason', 'apply_failed_by_name'], bidx: { source: 'author_email', column: 'author_email_bidx' } },
   { table: 'pending_commits', key: ['id'], encrypted: ['author_email', 'author_name', 'last_error'], bidx: { source: 'author_email', column: 'author_email_bidx' } },
   { table: 'file_locks', key: ['workspace_id', 'branch', 'path'], encrypted: ['holder_name'] },
@@ -529,7 +606,6 @@ const PII_FINALIZE_STATEMENTS = [
   'CREATE UNIQUE INDEX IF NOT EXISTS "pr_file_approvals_bidx_unq" ON "pr_file_approvals" ("pr_number","path","approver_email_bidx","head_sha")',
   'DROP INDEX IF EXISTS "pr_file_approvals_unq"',
   'ALTER TABLE "pr_merge_log" ALTER COLUMN "triggered_by_email_bidx" SET NOT NULL',
-  'ALTER TABLE "pr_comments" ALTER COLUMN "author_email_bidx" SET NOT NULL',
   'ALTER TABLE "change_requests" ALTER COLUMN "author_email_bidx" SET NOT NULL',
   'ALTER TABLE "pending_commits" ALTER COLUMN "author_email_bidx" SET NOT NULL',
   'ALTER TABLE "plugin_join_requests" ALTER COLUMN "requester_email_bidx" SET NOT NULL',

package/src/modules/declared-variables/__tests__/declared-variables.route.test.ts

@@ -4,6 +4,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import { createDeclaredVariableRoutes } from '../declared-variables.routes.js';
 import type { IToolManualService, ToolManualSummary } from '../../tool-manuals/tool-manuals.contract.js';
 import type { ISecretsVaultService } from '../../secrets-vault/secrets-vault.contract.js';
+import { ConnectionScope, type IAgentScopeResolver } from '../../agent-scope/index.js';
 
 /**
  * The one core route that releases secret VALUES. What is worth pinning here is
@@ -46,6 +47,9 @@ async function mount(opts: {
   source?: 'session' | 'external' | 'internal';
   manuals?: ToolManualSummary[];
   secrets?: Record<string, string>;
+  /** The `.agent` file the caller's connection was made as; absent is Everything. */
+  agentPath?: string;
+  agentScope?: Pick<IAgentScopeResolver, 'resolve'>;
 }): Promise<Harness> {
   const userId = opts.userId ?? 'user-1';
   const source = opts.source ?? 'external';
@@ -64,10 +68,18 @@ async function mount(opts: {
       toolManualService,
       secretsVault,
       (req, _res, next) => {
-        if (userId) req.toolAuth = { userId, source, scope: 'write' } as typeof req.toolAuth;
+        if (userId) {
+          req.toolAuth = {
+            userId,
+            source,
+            scope: 'write',
+            ...(opts.agentPath ? { agentPath: opts.agentPath } : {}),
+          } as typeof req.toolAuth;
+        }
         next();
       },
       async () => 'runner@x.eu',
+      opts.agentScope,
     ),
   );
   httpServer = await new Promise<HttpServer>((r) => {
@@ -133,6 +145,37 @@ describe('POST /agent/local-tools/:slug/variables', () => {
     expect(resolve).not.toHaveBeenCalled();
   });
 
+  it("releases only the variables of a connector the connection's .agent file loads", async () => {
+    const agent = { path: 'Agents/ops.agent', name: 'Ops' };
+    const loading = (connectors: string[]) => ({
+      resolve: async () => ConnectionScope.narrowed(agent, { skills: [], connectors, platformTools: null }, 'fp'),
+    });
+    // A folder entry over the tool's plugin loads it.
+    const inScope = await mount({
+      manuals: [GIT_TOOL],
+      secrets: { git_GITHUB_TOKEN: 'ghp_secret' },
+      agentPath: agent.path,
+      agentScope: loading(['Plugins/Engineering']),
+    });
+    expect((await fetch(`${inScope.base}/agent/local-tools/git/variables`, { method: 'POST' })).status).toBe(200);
+    await new Promise<void>((r) => httpServer!.close(() => r()));
+
+    // A readable tool the file does not load is as absent as an unreadable one.
+    const outOfScope = await mount({
+      manuals: [GIT_TOOL],
+      secrets: { git_GITHUB_TOKEN: 'ghp_secret' },
+      agentPath: agent.path,
+      agentScope: loading(['Plugins/billing.tool']),
+    });
+    expect((await fetch(`${outOfScope.base}/agent/local-tools/git/variables`, { method: 'POST' })).status).toBe(404);
+    expect(outOfScope.resolve).not.toHaveBeenCalled();
+    await new Promise<void>((r) => httpServer!.close(() => r()));
+
+    // A narrowed connection with no resolver wired loads nothing.
+    const unwired = await mount({ manuals: [GIT_TOOL], agentPath: agent.path });
+    expect((await fetch(`${unwired.base}/agent/local-tools/git/variables`, { method: 'POST' })).status).toBe(404);
+  });
+
   it('403s an unauthenticated caller', async () => {
     const { base } = await mount({ userId: '', manuals: [GIT_TOOL] });
     expect((await fetch(`${base}/agent/local-tools/git/variables`, { method: 'POST' })).status).toBe(403);

package/src/modules/declared-variables/declared-variables.routes.ts

@@ -3,8 +3,9 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('declared-variables');
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
-import type { IToolManualService } from '../tool-manuals/tool-manuals.contract.js';
-import type { ISecretsVaultService } from '../secrets-vault/secrets-vault.contract.js';
+import type { IToolManualService } from '../tool-manuals/index.js';
+import type { ISecretsVaultService } from '../secrets-vault/index.js';
+import { resolveConnectionScope, type IAgentScopeResolver } from '../agent-scope/index.js';
 
 type ResolveUserEmail = (userId: string) => Promise<string | undefined>;
 
@@ -48,6 +49,12 @@ export function createDeclaredVariableRoutes(
   secretsVault: ISecretsVaultService,
   manualAuth: RequestHandler,
   resolveUserEmail: ResolveUserEmail,
+  /**
+   * Resolves the scope of a connection made as an agent configuration: such a
+   * connection is handed only the variables of a connector the file loads.
+   * Absent, a narrowed connection is handed none.
+   */
+  agentScope?: Pick<IAgentScopeResolver, 'resolve'>,
 ): express.Router {
   const router = express.Router();
 
@@ -125,7 +132,11 @@ export function createDeclaredVariableRoutes(
       // `listAccessible` already applies the per-file read verdict, so an
       // unreadable manual is simply absent — same fail-closed read model the
       // catalog uses.
-      const manual = (await toolManualService.listAccessible(who.email)).find((m) => m.slug === slug);
+      const found = (await toolManualService.listAccessible(who.email)).find((m) => m.slug === slug);
+      // A connection made as an agent configuration is handed only the variables of
+      // a connector it loads; another is as absent as an unreadable one.
+      const scope = found ? await resolveConnectionScope(agentScope, who.email, req.toolAuth?.agentPath) : null;
+      const manual = found && scope?.allowsConnector(found.path) ? found : undefined;
       if (!manual) return void res.status(404).json({ error: 'Not found' });
       if (manual.remote !== false) {
         return void res.status(409).json({

package/src/modules/diff/diff.routes.ts

@@ -1,14 +1,14 @@
 import express from 'express';
 import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
 import type { IDiffService } from './diff.interface.js';
-import type { AuthService } from '../auth/auth.service.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
-import { canReadWorkspacePath, toKbRelative, resolveReadableMap } from '../access-model/kb-read-filter.js';
+import type { AuthService } from '../auth/index.js';
+import type { IAccessControl } from '../access/index.js';
+import { canReadWorkspacePath, toKbRelative, resolveReadableMap } from '../access-model/index.js';
 import { WorkflowDomainError, WorkflowValidationError } from '../../shared/domain-errors.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
-import { LockingFilesystem } from '../kb-fs/locking-filesystem.js';
+import { LockingFilesystem } from '../kb-fs/index.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
-import '../auth/auth.middleware.js';
+import '../auth/index.js';
 
 function toHttpError(
   err: unknown,

package/src/modules/diff/diff.service.ts

@@ -2,8 +2,8 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import type { FileDiffPayload, PendingChange, ReviewSession, ChangeKind } from '@bevel-software/platform-shared';
 import type { IDiffService } from './diff.interface.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
-import type { WorkspaceMutex } from '../kb-fs/mutex.js';
+import type { WorkspaceService } from '../workspace/index.js';
+import type { WorkspaceMutex } from '../kb-fs/index.js';
 import { gitDirOf } from '../kb-fs/index.js';
 import { isAbsence, type ITreeWalker, type TreeWalkOptions } from '../../shared/fs.contract.js';
 import { isDiffable } from './diff.config.js';

package/src/modules/diff/index.ts

@@ -0,0 +1,6 @@
+/**
+ * What the diff module offers the other modules. A consumer outside the
+ * module imports from here, never from the files: they are the module's own
+ * layout and free to move. Export what another module needs; nothing more.
+ */
+export type { IDiffService } from './diff.interface.js';

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

@@ -281,6 +281,18 @@ describe('open_page: refusals', () => {
     expect(embedService.mintForUser).not.toHaveBeenCalled();
   });
 
+  it('refuses a tmp ref — no knowledge-base page — reading and minting nothing', async () => {
+    const read = vi.fn<ReadForTool>();
+    const { call, embedService } = await serve({ read });
+    const { status, body } = await call({ path: '__tmp__/chat-uploads/plan.xlsx' });
+    expect(status).toBe(400);
+    expect(body.kind).toBe('tmp-ref-read-only');
+    expect(body.error).toContain('open_page does not take one there');
+    expect(body.error).toContain('copy_file');
+    expect(read).not.toHaveBeenCalled();
+    expect(embedService.mintForUser).not.toHaveBeenCalled();
+  });
+
   it('refuses a path outside the knowledge base, and a missing one', async () => {
     const { call, embedService } = await serve();
     expect((await call({ path: '' })).status).toBe(400);

package/src/modules/embed/account-link.service.ts

@@ -1,6 +1,6 @@
 import { and, eq } from 'drizzle-orm';
-import type { Database } from '../database/connection.js';
-import { atlassianAccountLinks } from '../database/schema.js';
+import type { Database } from '../database/index.js';
+import { atlassianAccountLinks } from '../database/index.js';
 
 /**
  * Maps an outside system's account id — today an Atlassian (Forge) account —

package/src/modules/embed/embed.routes.ts

@@ -7,8 +7,8 @@ import {
   EmbedTokenError,
 } from './embed.errors.js';
 import { EmbedRefParseError } from './embed-link.js';
-import { rawExtensionOf, rawMimeFor } from '../workspace/file-readers/raw-mime.js';
-import '../auth/auth.middleware.js'; // Express Request augmentation
+import { rawExtensionOf, rawMimeFor } from '../workspace/index.js';
+import '../auth/index.js'; // Express Request augmentation
 
 /**
  * What `/api/embed/raw` answers as `Content-Type`, by extension — the types a

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

@@ -6,7 +6,7 @@ import { suggestionsBranchPrefixFor } from '@bevel-software/platform-shared';
 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 type { IAccessControl } from '../access/index.js';
 import { changeRequestLink, changeRequestLinkBase } from '../workflow/index.js';
 import type { FileReaderRegistry } from '../workspace/index.js';
 import type { WriteValidator } from '../kb-fs/index.js';

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

@@ -1,15 +1,13 @@
 import type { Router, RequestHandler } from 'express';
-import type { IToolRegistry } from '../tool-registry/tool.contract.js';
-import { ToolError } from '../tool-helpers/tool.contract.js';
-import { toolDef } from '../tool-helpers/tool-def.js';
-import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
-import type { ToolContext } from '../tool-helpers/tool.contract.js';
+import type { IToolRegistry } from '../tool-registry/index.js';
+import { ToolError, toolDef } from '../tool-helpers/index.js';
+import type { ToolHandlerFactory, ToolContext } from '../tool-helpers/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import type { ReadForTool } from '../workspace/workspace.tools.js';
+import type { ReadForTool } from '../workspace/index.js';
 import type { IEmbedService } from './embed.interface.js';
-import { requireExternalSource } from '../tool-auth/tool-auth.middleware.js';
-import { SESSION_ID_INPUT, type ToolDescriptionNotes } from '../workspace/agent-access.gate.js';
-import { sessionIdInputOf } from '../workspace/workspace.tools.js';
+import { requireExternalSource } from '../tool-auth/index.js';
+import { assertTmpRefsTaken } from '../kb-fs/index.js';
+import { SESSION_ID_INPUT, type ToolDescriptionNotes, sessionIdInputOf } from '../workspace/index.js';
 
 /** The tool name, in one place: the app manifest keys its view by it. */
 export const OPEN_PAGE_TOOL = 'open_page';
@@ -152,6 +150,10 @@ export function registerEmbedTools(
     toolHandler(async (args, ctx: ToolContext) => {
       const raw = typeof args.path === 'string' ? args.path.trim() : '';
       if (!raw) throw new ToolError('`path` is required.', 400);
+      // A tmp ref (`__tmp__/…`) is no knowledge-base page: refused by the one
+      // admission gate the normalised tools pass, before `toRepoRelative`
+      // would read it as the repository path `<kbDirName>/__tmp__/…`.
+      assertTmpRefsTaken(OPEN_PAGE_TOOL, { path: raw });
       const heading = typeof args.heading === 'string' && args.heading.trim() ? args.heading.trim() : undefined;
       const repoRelative = toRepoRelative(raw, kbDirName);
       if (repoRelative === null) throw new ToolError(OUTSIDE_REPO(kbDirName), 400);

package/src/modules/github-app/github-app.connection.ts

@@ -1,5 +1,5 @@
 import { logger } from '../../shared/logging.js';
-import type { GitHubAppRepository, SettingReader } from '../settings/repository-source.js';
+import type { GitHubAppRepository, SettingReader } from '../settings/index.js';
 import {
   GitHubAppClient,
   type GitHubAppCredentials,

package/src/modules/github-app/github-app.routes.ts

@@ -1,11 +1,11 @@
 import { randomBytes, timingSafeEqual } from 'node:crypto';
 import express from 'express';
-import type { IAdminAccessService } from '../admin/admin.interface.js';
+import type { IAdminAccessService } from '../admin/index.js';
 import { logger } from '../../shared/logging.js';
-import type { DeploymentSettingsService } from '../settings/deployment-settings.service.js';
+import type { DeploymentSettingsService } from '../settings/index.js';
 import { GitHubAppClient, GitHubAppError } from './github-app.client.js';
 import { repositoriesAsSetting, type GitHubAppConnection } from './github-app.connection.js';
-import '../auth/auth.middleware.js'; // Express Request augmentation
+import '../auth/index.js'; // Express Request augmentation
 
 const log = logger('github-app');
 

package/src/modules/kb-fs/__tests__/locking-filesystem.test.ts

@@ -1482,6 +1482,31 @@ describe('LockingFilesystem — a destination that is taken is refused, never re
     expect(await fs.readFile(onDisk(TAKEN), 'utf-8')).toBe('the winner of the race');
   });
 
+  /**
+   * The same race for an EXCLUSIVE write (`overwrite: false`), which is how
+   * `copy_file` lands bytes read out of the workspace's tmp folder: the
+   * refusal is the clash sentence, and the lock releases untouched rather
+   * than discarding the winner's queued file.
+   */
+  it('an exclusive write onto a taken name is the same refusal, and releases UNTOUCHED', async () => {
+    const workflow = makeWorkflow();
+    const layer = new LockingFilesystem(
+      { basePath: root, contained: true },
+      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
+    );
+    await fs.writeFile(onDisk(TAKEN), 'the winner of the race');
+
+    await expect(layer.writeFile(TAKEN, 'the loser', { overwrite: false })).rejects.toMatchObject({
+      name: 'DestinationTakenError',
+      message: 'A file named taken.md already exists in KnowledgeBase.',
+    });
+
+    expect(workflow.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', TAKEN, USER);
+    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
+    expect(workflow.releaseLock).not.toHaveBeenCalled();
+    expect(await fs.readFile(onDisk(TAKEN), 'utf-8')).toBe('the winner of the race');
+  });
+
   it.skipIf(process.platform === 'win32')('answers the clash sentence when a DANGLING link holds the name', async () => {
     // A link to nothing still owns the directory entry, so the exclusive
     // create fails — and an existence probe that follows links would say the