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

package/src/core/create-core-services.ts

@@ -34,6 +34,8 @@ import { TemplateFilesStep } from '../modules/workspace/startup/steps/template-f
 import { RolesYamlStep } from '../modules/workspace/startup/steps/roles-yaml.step.js';
 import { buildSeedTree } from '../modules/workspace/startup/steps/seed-tree.js';
 import { DeploymentSettingsService, retireMergedBranchesOn } from '../modules/settings/deployment-settings.service.js';
+import { ToolReadOnlyHints } from '../modules/tool-registry/read-only-hints.js';
+import type { IToolReadOnlyHints } from '../modules/tool-registry/read-only-hints.contract.js';
 import { KbSyncService } from '../modules/kb-sync/kb-sync.service.js';
 import { NodeFs } from '../modules/kb-fs/node-fs.js';
 import { assertKbDirNameFree } from '../modules/kb-fs/repo-path.js';
@@ -67,7 +69,11 @@ import { createDownloadFetcherIdentifier } from '../modules/workspace/agent-down
 import { WorkerPatternMatcher } from '../modules/workspace/bounded-matcher.js';
 import type { IPatternMatcher } from '../modules/workspace/pattern-matcher.contract.js';
 import type { Request } from 'express';
-import { DocExtractService } from '../modules/workspace/file-readers/doc-extract.service.js';
+import {
+  DocExtractService,
+  WorkerDocumentExtractor,
+  type IDocumentExtractor,
+} from '../modules/workspace/index.js';
 import { UuidSessionSink, type ISessionSink } from '../modules/workspace/session-sink.js';
 import { AuthService } from '../modules/auth/auth.service.js';
 import { AccountHooks, type IAccountHooks } from '../modules/auth/account-hooks.js';
@@ -75,6 +81,7 @@ import { AccountErasureService } from '../modules/auth/account-erasure.service.j
 import { OidcAuthProvider, oidcSettingsFrom } from '../modules/auth/oidc-auth-provider.js';
 import { createAuthMiddleware, readAuthCookie } from '../modules/auth/auth.middleware.js';
 import { AccessControlService, loadActiveGroups } from '../modules/access/access-control.service.js';
+import { AccessMutationService } from '../modules/access/access-mutation.service.js';
 import { CreatorAccessService } from '../modules/access/creator-access.js';
 import { ChangeReadGate } from '../modules/access/change-read-gate.js';
 import { GroupsAdminService } from '../modules/access/groups-admin.service.js';
@@ -122,11 +129,12 @@ import { assertGitVersion } from '../modules/workflow/git/git-version.js';
 import { DiffService } from '../modules/diff/diff.service.js';
 import { ReviewWorkflowService } from '../modules/workflow/review-workflow/review-workflow.service.js';
 import { FileLockService } from '../modules/workflow/file-lock.service.js';
-import { WorkflowEventBus } from '../modules/workflow/event-bus.js';
+import { WorkflowEventBus } from '../modules/workflow/index.js';
 import { FileChangeNotifier } from '../modules/kb-fs/file-change-notifier.js';
 import { StarterPackService } from '../modules/onboarding/starter-pack.service.js';
 import { WorkflowService } from '../modules/workflow/workflow.service.js';
 import { WorkflowHooks } from '../modules/workflow/workflow-hooks.js';
+import { ChangeRequestHooks, type IChangeRequestHooks } from '../modules/workflow/change-request-hooks.js';
 import { PendingCommitsService } from '../modules/workflow/pending-commits.service.js';
 import {
   PendingCommitsWorker,
@@ -255,6 +263,8 @@ export interface CoreServices {
    * download route can refuse a link presented by someone it was not issued to.
    */
   agentDownloadFetcher: (req: Request) => Promise<string[]>;
+  /** Runs every document extraction off the request thread under a budget; its workers end when the graph stops. */
+  documentExtractor: IDocumentExtractor;
   docExtractService: DocExtractService;
   accessControl: AccessControlService;
   creatorAccess: CreatorAccessService;
@@ -324,6 +334,12 @@ export interface CoreServices {
   reviewWorkflowService: ReviewWorkflowService;
   fileLockService: FileLockService;
   workflowService: WorkflowService;
+  /**
+   * The seam for "a change request was opened": a deployment registers here
+   * how the reviewers are told (the cloud's mail, say), and the open's answer
+   * says whether somebody did. Core registers nothing.
+   */
+  changeRequestHooks: IChangeRequestHooks;
   /** Remote sync (`POST /api/sync`): a git host or pipeline makes the clones catch up. */
   kbSyncService: KbSyncService;
   eventBus: WorkflowEventBus;
@@ -392,6 +408,8 @@ export interface CoreServices {
   /** The Audit log: what every connected agent and key called, and the revoke of an agent's grant. */
   agentAuditService: AgentAuditService;
   toolRegistry: ToolRegistry;
+  /** Each platform tool's and meta-tool's read-only hint, and an admin's overrides of them. */
+  readOnlyHints: IToolReadOnlyHints;
   toolAuthMiddleware: ReturnType<typeof createToolAuthMiddleware>;
   manualAuthMiddleware: ReturnType<typeof createManualAuthMiddleware>;
   toolHandlerFactory: ReturnType<typeof createToolHandlerFactory>;
@@ -784,9 +802,9 @@ export async function createCoreServices(
     // `<tenant>-down_`: recognisable by shape beside the upload token.
     tokenPrefix: config.uploadTokenPrefix.replace(/up_$/, 'down_'),
   });
-  // Office-document/PDF text extraction for `read_file`/`grep`, cached by
-  // content hash beside the workspaces root (see `DocExtractionCache`).
-  const docExtractService = new DocExtractService(config.docExtractCacheRoot);
+  // The worker threads every office/PDF/email extraction runs in, under a
+  // 10 s budget per file (see `WorkerDocumentExtractor`).
+  const documentExtractor = new WorkerDocumentExtractor();
   // The deployment owner counts as Admin for the two hardcoded `write`
   // rescues (`roles.yaml` and any `access.md`) — the SAME list
   // `AdminAccessService` below is given, so the admin surfaces and the write
@@ -945,11 +963,23 @@ export async function createCoreServices(
   // browser sessions. Single instance per Node process — survives across
   // requests, doesn't survive restarts (clients reconnect + resync).
   const eventBus = new WorkflowEventBus();
+  // Office-document/PDF/email text extraction for `read_file`/`grep`, cached
+  // by content hash beside the workspaces root (see `DocExtractionCache`),
+  // failures included. A fresh failure is told to the people looking at the
+  // file: the events route delivers it only to sessions that may read it.
+  const docExtractService = new DocExtractService(config.docExtractCacheRoot, documentExtractor, {
+    onUnreadable: ({ workspaceId, path, reason }) =>
+      eventBus.emit({ kind: 'document-unreadable', workspaceId, path, reason }),
+  });
   // In-process post-commit hook (distinct from the SSE bus): fires once per
   // committed change (batched paths) so catalogs refresh instantly and the
   // id-repair keeps the id namespace collision-free. Subscribers are registered
   // below, once the reacting services exist.
   const fileChangeNotifier = new FileChangeNotifier();
+  // Who tells the reviewers of an opened change request: the composition root
+  // of a distribution registers its listener here, after this returns (see
+  // `ChangeRequestHooks`).
+  const changeRequestHooks = new ChangeRequestHooks();
   const workflowService = new WorkflowService(
     db,
     gitService,
@@ -967,6 +997,11 @@ export async function createCoreServices(
     // the agent-access gate consult, so a deployment's registrations against
     // it reach every hook point.
     workflowHooks,
+    // Exposed as `changeRequestHooks`, the same instance, for the same reason.
+    changeRequestHooks,
+    // The opened event names the approvers as accounts; auth answers which
+    // of the addresses the access model names have one.
+    authService,
   );
   // The leftover-branch cleanup asks the Deployment page at every round, so
   // switching it off there applies without a restart.
@@ -1022,6 +1057,7 @@ export async function createCoreServices(
     workspaceService,
     workflowService,
     accessControl,
+    new AccessMutationService(workspaceService, accessControl, kb.kbDirName),
     skillService,
     pluginLinkIndex,
     kb,
@@ -1370,6 +1406,8 @@ export async function createCoreServices(
       // the setup save applies lands without a restart.
       kbLayout: () => kb.layout,
       secretsScope,
+      // Read at listing time, by when the hints below exist.
+      readOnlyOverrides: () => readOnlyHints.overrides(),
     },
     // Pre-dispatch per-user credential check: the vault answers "has this caller
     // set it?" and the manual catalog answers "which user-scoped vars does this
@@ -1438,6 +1476,9 @@ export async function createCoreServices(
   // `internalTokenService` minted above (shared with the agent factories) is
   // the same one the tool-auth middleware verifies internal tokens against.
   const toolRegistry = new ToolRegistry();
+  // What MCP clients are told about each platform tool's effect: its write
+  // declaration, or an admin's override from the Tools page.
+  const readOnlyHints = new ToolReadOnlyHints(toolRegistry, settings);
   const resolveToolContext = createToolContextResolver({
     authService,
     workspaceService,
@@ -1634,6 +1675,7 @@ export async function createCoreServices(
     agentDownloadStore,
     patternMatcher,
     agentDownloadFetcher,
+    documentExtractor,
     docExtractService,
     accessControl,
     creatorAccess,
@@ -1668,6 +1710,7 @@ export async function createCoreServices(
     reviewWorkflowService,
     fileLockService,
     workflowService,
+    changeRequestHooks,
     kbSyncService,
     eventBus,
     fileChangeNotifier,
@@ -1691,6 +1734,7 @@ export async function createCoreServices(
     mcpResourceMetadataUrl,
     agentAuditService,
     toolRegistry,
+    readOnlyHints,
     toolAuthMiddleware,
     manualAuthMiddleware,
     toolHandlerFactory,

package/src/core/lifecycle.ts

@@ -454,6 +454,12 @@ export interface CoreStopDeps {
    * caller that has not built one passes nothing.
    */
   patternMatcher?: { close(): Promise<void> };
+  /**
+   * The document extractor, whose worker threads are this graph's own for the
+   * same reason: ended here, so no extraction worker outlives its graph.
+   * Optional like the matcher.
+   */
+  documentExtractor?: { close(): Promise<void> };
   /**
    * The workflow service, for the tidy-up it runs after each sweep (closing
    * empty requests, removing leftover branches): detached from whatever
@@ -591,6 +597,10 @@ async function releaseCore(deps: CoreStopDeps, remaining: () => number, log: (m:
   if (deps.patternMatcher) {
     await bounded(deps.patternMatcher.close(), remaining(), 'ending the search workers', log);
   }
+  // Likewise: an extraction still running is answered busy, and nothing about its file is remembered.
+  if (deps.documentExtractor) {
+    await bounded(deps.documentExtractor.close(), remaining(), 'ending the extraction workers', log);
+  }
   await bounded(deps.commitWorker.stop(), remaining(), 'stopping the commit worker', log);
   if (deps.secretsScope !== undefined) unregisterBevelSecretsVariableLoader(deps.secretsScope);
   await bounded(closeDb(deps.db), remaining(), 'ending the database pool', log);

package/src/core/public-config.ts

@@ -85,5 +85,15 @@ export function publicConfig(kb: KbContext, { marketplaceGitUrl, mcpUrl }: Publi
      * there.
      */
     catalogRevision: true as const,
+    /**
+     * This deployment serves `GET /api/agent/tool-hints`, the read-only hint
+     * of every platform tool and code-mode meta-tool (see
+     * modules/tool-registry/read-only-hints.ts). The local `hexis-mcp` bridge
+     * reads it on every `tools/list` only when this is advertised — on the
+     * same terms as the two flags above: an older deployment answers the
+     * unknown route with 401, and an OAuth bridge reads a 401 as an expired
+     * token and refreshes its sign-in on every listing.
+     */
+    toolHints: true as const,
   };
 }

package/src/index.ts

@@ -151,3 +151,10 @@ export {
   type AgentReadHook,
   type PreWriteHook,
 } from './modules/workflow/workflow-hooks.js';
+export {
+  ChangeRequestHooks,
+  type ChangeRequestOpenedEvent,
+  type ChangeRequestOpenedHook,
+  type ChangeRequestPerson,
+  type IChangeRequestHooks,
+} from './modules/workflow/change-request-hooks.js';

package/src/modules/access/__tests__/access-requests.routes.test.ts

@@ -49,7 +49,8 @@ interface HarnessOpts {
   lastClosed?: { number: number; state: 'closed' | 'merged' } | null;
   liveRules?: string | null;
   branchRules?: string | null;
-  detailBody?: string;
+  /** What `getChangeRequestDetail` answers for every request: the body, and the access request's own facts. */
+  detail?: { body?: string; accessRequest?: { level: 'write' | 'owner'; note?: string } };
 }
 
 async function makeHarness(opts: HarnessOpts = {}) {
@@ -62,7 +63,7 @@ async function makeHarness(opts: HarnessOpts = {}) {
     lastClosed = null,
     liveRules = '---\n---\nwrite:\n  - Ed <ed@x.io>\n',
     branchRules = null,
-    detailBody = '',
+    detail = {},
   } = opts;
 
   const absent = Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
@@ -92,7 +93,7 @@ async function makeHarness(opts: HarnessOpts = {}) {
     }),
     latestClosedChangeRequest: vi.fn(async () => lastClosed),
     getChangeRequest: vi.fn(async (n: number) => ({ number: n, state: 'open' })),
-    getChangeRequestDetail: vi.fn(async () => ({ body: detailBody })),
+    getChangeRequestDetail: vi.fn(async () => ({ body: '', ...detail })),
   } as unknown as IWorkflowService;
 
   const workspaceService = {
@@ -345,13 +346,14 @@ describe('GET /workspace/:id/access/request — what the requester is told', ()
   it('reports the open request, taking the level off the REQUEST rather than the branch', async () => {
     // The branch is where the proposal lives, but a clone whose refs are
     // seconds stale cannot read a branch cut moments ago. "Requested: Owner"
-    // is a promise about a request, so it is answered from the request — here
-    // the branch is deliberately unreadable and the line is still right.
+    // is a promise about a request, so it is answered from the request's own
+    // row — here the branch is deliberately unreadable and the line is still
+    // right.
     const branch = joinBranchFor(RITA.email, FOLDER);
     const h = await makeHarness({
       openCrs: [{ number: 31, branch, state: 'open' }],
       proposals: null,
-      detailBody: '<!--hexis:access-request-level:owner-->\nRita asked for Owner.',
+      detail: { body: 'Rita asked for Owner.', accessRequest: { level: 'owner' } },
     });
     server = h.server;
     expect(await (await status(h)).json()).toEqual({ state: 'pending', level: 'owner', number: 31 });
@@ -361,7 +363,7 @@ describe('GET /workspace/:id/access/request — what the requester is told', ()
     const branch = joinBranchFor(RITA.email, FOLDER);
     const h = await makeHarness({
       openCrs: [{ number: 31, branch, state: 'open' }],
-      detailBody: 'Opened before the level was recorded.',
+      detail: { body: 'Opened before the level was recorded.' },
     });
     server = h.server;
     expect(await (await status(h)).json()).toMatchObject({ state: 'pending', level: 'write' });
@@ -410,12 +412,14 @@ describe('the editors\' side', () => {
   const listUrl = (base: string) =>
     `${base}/${LIVE_WS}/access/requests?path=${encodeURIComponent(`${KB}/${FOLDER}`)}&kind=folder`;
 
-  it('lists the item\'s open requests for an editor, with the note read back as plain text', async () => {
+  it("lists the item's open requests for an editor, with the note off the request's own row", async () => {
     const h = await makeHarness({
       writable: [`${FOLDER}/access.md`],
       proposals: [proposalFor('owner')],
-      detailBody:
-        'x\n\n<!--hexis:access-request-note-->\n> I maintain these pages now\n<!--/hexis:access-request-note-->\n',
+      detail: {
+        body: 'x\n\nNote from Rita:\n\n> I maintain these pages now',
+        accessRequest: { level: 'owner', note: 'I maintain these pages now' },
+      },
     });
     server = h.server;
     const body = await (await fetch(listUrl(h.base))).json();
@@ -565,19 +569,29 @@ describe('a branch left over from an answered request', () => {
     // request asking for Owner.
     const h = await makeHarness({
       openCrs: [{ number: 31, branch: stale, state: 'open' }],
-      detailBody: '<!--hexis:access-request-level:owner-->',
+      detail: { accessRequest: { level: 'owner' } },
     });
     server = h.server;
     const res = await post(`${h.base}/${LIVE_WS}/access/request`, { ...folderBody, level: 'write' });
     expect(await res.json()).toEqual({ ok: true, state: 'pending', number: 31, level: 'owner' });
   });
 
-  it('records the level on the request itself, so it can be read back', async () => {
+  it('records the level and the note on the request itself, never hidden in its description', async () => {
     const h = await makeHarness();
     server = h.server;
-    await post(`${h.base}/${LIVE_WS}/access/request`, { ...folderBody, level: 'owner' });
-    const { description } = h.opened[0] as { description: string };
-    expect(description).toContain('<!--hexis:access-request-level:owner-->');
+    await post(`${h.base}/${LIVE_WS}/access/request`, { ...folderBody, level: 'owner', note: 'For the Q3 review' });
+    const { description, accessRequest } = h.opened[0] as { description: string; accessRequest: unknown };
+    expect(accessRequest).toEqual({ level: 'owner', note: 'For the Q3 review' });
+    // The description is prose for the people who read it: no marker, no fence.
+    expect(description).not.toMatch(/<!--/);
+    expect(description).toContain('For the Q3 review');
+  });
+
+  it('records no note when none was written', async () => {
+    const h = await makeHarness();
+    server = h.server;
+    await post(`${h.base}/${LIVE_WS}/access/request`, { ...folderBody, level: 'write' });
+    expect((h.opened[0] as { accessRequest: unknown }).accessRequest).toEqual({ level: 'write' });
   });
 });
 

package/src/modules/access/access-control.service.ts

@@ -7,9 +7,9 @@ const log = logger('access');
 import { isAbsence, type ITreeWalker, type WalkListener } from '../../shared/fs.contract.js';
 import { assertOneSpecPerLine, isCommitSha, isGitTimeout, type IGitRunner } from '../../shared/git.contract.js';
 import { hashEmail } from '../../shared/email-identity.js';
-import { NodeGitRunner } from '../workflow/git/node-git-runner.js';
+import { NodeGitRunner } from '../workflow/index.js';
 import { readRevSha } from '../kb-fs/index.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type {
   IAccessControl,
   AccessDecision,
@@ -32,14 +32,13 @@ import {
   platformRestoreDestination,
 } from '@bevel-software/platform-shared';
 import type { KbContext } from '../../shared/kb-context.js';
-import { AccessConfigError, AccessUnreadableError } from '../access-model/access-errors.js';
-import { synthesizePluginPrincipals } from '../access-model/plugin-principals.js';
+import { AccessConfigError, AccessUnreadableError, synthesizePluginPrincipals } from '../access-model/index.js';
 import {
   GROUPS_YAML,
   SYNCED_GROUPS_YAML,
   parseGroupsFile,
   type GroupsIndex,
-} from '../access-model/group-files.js';
+} from '../access-model/index.js';
 import {
   ADMIN_CANONICAL,
   EVERYONE_CANONICAL,
@@ -61,7 +60,7 @@ import {
   type ParsedEntry,
   type RolesIndex,
   type Verb,
-} from '../access-model/access-grammar.js';
+} from '../access-model/index.js';
 import {
   DIRECTORY_SYNC_BOT_EMAIL,
   DIRECTORY_SYNC_BOT_NAME,

package/src/modules/access/access-declarations.ts

@@ -9,7 +9,7 @@ import {
   parseOwnAccessEntries,
   type ParsedEntry,
   type Verb,
-} from '../access-model/access-grammar.js';
+} from '../access-model/index.js';
 
 /**
  * WHERE access rules are DECLARED inside a folder — a read-only inventory, not

package/src/modules/access/access-mutation.service.ts

@@ -35,10 +35,10 @@
 
 import path from 'node:path';
 
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { IAccessControl } from './access-control.interface.js';
 import { isAbsence } from '../../shared/fs.contract.js';
-import { isTextBytes } from '../workspace/file-readers/text-reader.js';
+import { isTextBytes } from '../workspace/index.js';
 import {
   type Verb,
   ADMIN_CANONICAL,
@@ -46,7 +46,7 @@ import {
   ROLE_TOKEN_PREFIX,
   canonicalRoleName,
   accessFrontmatterExtensionList,
-} from '../access-model/access-grammar.js';
+} from '../access-model/index.js';
 import {
   spliceRevoke,
   spliceGrant,
@@ -54,7 +54,7 @@ import {
   AccessSpliceError,
   type Principal,
   type TokenMatch,
-} from '../access-model/access-splice.js';
+} from '../access-model/index.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import {
   canCarryFrontmatter,
@@ -610,3 +610,9 @@ export class AccessMutationService {
     return new AccessMutationError(err instanceof Error ? err.message : 'mutation failed', 500);
   }
 }
+
+/**
+ * What another module needs of the mutation service: to grant and to revoke.
+ * Injected by the composition root, which owns the implementation.
+ */
+export type IAccessMutation = Pick<AccessMutationService, 'grant' | 'revoke'>;

package/src/modules/access/access-requests.contract.ts

@@ -1,5 +1,5 @@
 import type { AuthUser, ChangeRequest } from '@bevel-software/platform-shared';
-import type { Verb } from '../access-model/access-grammar.js';
+import type { Verb } from '../access-model/index.js';
 import { accessMdPathForFolder, type TargetKind } from './access-mutation.service.js';
 
 /**

package/src/modules/access/access-requests.routes.ts

@@ -1,11 +1,10 @@
 import express from 'express';
-import type { AuthUser } from '@bevel-software/platform-shared';
-import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
 import { logger } from '../../shared/logging.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
-import type { AuthService } from '../auth/auth.service.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { AuthService } from '../auth/index.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { IAccessControl } from './access-control.interface.js';
 import {
   AccessMutationError,
@@ -22,12 +21,8 @@ import {
   type AccessRequestTarget,
   type IAccessRequestLifecycle,
 } from './access-requests.contract.js';
-import {
-  AccessRequestsService,
-  extractRequestNote,
-  itemNameOf,
-} from './access-requests.service.js';
-import '../auth/auth.middleware.js'; // Express Request.userId augmentation
+import { AccessRequestsService, itemNameOf } from './access-requests.service.js';
+import '../auth/index.js'; // Express Request.userId augmentation
 
 const log = logger('access.request');
 
@@ -235,16 +230,16 @@ export function createAccessRequestRoutes(deps: {
       }
       const crs = await workflow.listChangeRequests();
       const rows = await lifecycle.list(target.path, target, crs, user);
-      // The note lives in the request's description and nowhere else, so it
-      // is read back per request. Bounded by the open requests on ONE item —
-      // a handful at most — and a detail that cannot be fetched costs the
-      // note, never the line it belongs to.
+      // The note is the request's own column, read back per request.
+      // Bounded by the open requests on ONE item — a handful at most — and a
+      // detail that cannot be fetched costs the note, never the line it
+      // belongs to.
       const withNotes = await Promise.all(
         rows.map(async (row) => {
           const detail = await workflow
             .getChangeRequestDetail(row.number, { patches: false })
             .catch(() => null);
-          const note = extractRequestNote(detail?.body);
+          const note = detail?.accessRequest?.note;
           return note ? { ...row, note } : row;
         }),
       );

package/src/modules/access/access-requests.service.ts

@@ -10,8 +10,8 @@ import {
 } from '../../shared/domain-errors.js';
 import { isAbsence } from '../../shared/fs.contract.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import { spliceGrant } from '../access-model/access-splice.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import { spliceGrant } from '../access-model/index.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import { logger } from '../../shared/logging.js';
 import { AccessMutationError } from './access-mutation.service.js';
 import {
@@ -50,7 +50,7 @@ export function itemNameOf(repoRelPath: string): string {
 /**
  * Neutralise every character a markdown renderer would read as structure.
  *
- * The note is somebody's free text and it lands in a change request's
+ * The note is somebody's free text and it is quoted in a change request's
  * description, which IS rendered. Escaping it is what makes "plain text" true:
  * without this a note can carry a heading, a link, or an image pointing at a
  * URL that logs whoever opens the request.
@@ -59,64 +59,6 @@ export function escapeMarkdown(text: string): string {
   return text.replace(/[\\`*_{}[\]()#+\-.!|<>~]/g, (c) => `\\${c}`);
 }
 
-/** The exact inverse of {@link escapeMarkdown} — only our own backslashes go. */
-function unescapeMarkdown(text: string): string {
-  return text.replace(/\\([\\`*_{}[\]()#+\-.!|<>~])/g, '$1');
-}
-
-/**
- * The fence the note sits behind in a request's description.
- *
- * The description is the note's only home — there is no column for it — so the
- * editors' banner has to read it back out of prose. Marking the block means
- * that read is exact rather than a guess at which paragraph was the note, and
- * an HTML comment is invisible in every surface that renders the description.
- */
-const NOTE_OPEN = '<!--hexis:access-request-note-->';
-const NOTE_CLOSE = '<!--/hexis:access-request-note-->';
-
-/**
- * The level, recorded on the change request itself.
- *
- * The branch says what is proposed, but only while it can be read — and a
- * clone whose refs are a few seconds stale cannot read a branch cut moments
- * ago. The request's own row always can. "Requested: <level>" is a promise
- * about a request, so it is answered from the request, not from a file at a
- * ref that may not have arrived yet.
- */
-const LEVEL_MARK = /<!--hexis:access-request-level:(write|owner)-->/;
-
-/**
- * The requester's own words, back out of a request's description, or
- * undefined when they wrote none. Unescaped exactly as they were escaped, so
- * what the banner shows is what was typed.
- */
-/**
- * The level a request asks for, off its own description. Undefined for a
- * request opened before this marker existed — those are the skill route's,
- * and the skill route only ever asked for `write`.
- */
-export function extractRequestLevel(body: string | null | undefined): RequestLevel | undefined {
-  const hit = body ? LEVEL_MARK.exec(body) : null;
-  return hit ? (hit[1] as RequestLevel) : undefined;
-}
-
-export function extractRequestNote(body: string | null | undefined): string | undefined {
-  if (!body) return undefined;
-  const start = body.indexOf(NOTE_OPEN);
-  if (start < 0) return undefined;
-  const end = body.indexOf(NOTE_CLOSE, start);
-  if (end < 0) return undefined;
-  const note = body
-    .slice(start + NOTE_OPEN.length, end)
-    .split(/\r?\n/)
-    .filter((line) => line.startsWith('>'))
-    .map((line) => unescapeMarkdown(line.replace(/^>\s?/, '')))
-    .join('\n')
-    .trim();
-  return note || undefined;
-}
-
 /**
  * Asking for Can edit or Owner on ONE item, and reading back what came of it.
  *
@@ -261,11 +203,15 @@ export class AccessRequestsService {
     }
 
     try {
+      // The level and the note are the request's own columns — what the
+      // dialog and the editors' banner read back. The description is for the
+      // people who read the request, and says the same things in prose.
       const detail = await workflow.openChangeRequest(ws.id, user, {
         sourceBranch: branch,
         targetBranch: kb.defaultBranch,
         title: `Access request: ${itemName}`,
         description: this.describe({ user, target, level, note }),
+        accessRequest: { level, ...(note ? { note } : {}) },
       });
       return { number: detail.number, level };
     } catch (err) {
@@ -331,18 +277,21 @@ export class AccessRequestsService {
   }
 
   /**
-   * The level change request `number` asks for, off its own description.
+   * The level change request `number` asks for, off the request's own row.
    *
-   * `write` when the description does not say: every request that predates the
-   * marker came from the skill page's "Request write access", which asks for
-   * exactly that. A detail that cannot be fetched falls there too — the line
-   * it feeds says which level was asked for, and Can edit is the lesser claim.
+   * The branch says what is proposed, but only while it can be read — and a
+   * clone whose refs are a few seconds stale cannot read a branch cut moments
+   * ago. The request's row always can. `write` when the row does not say:
+   * every request that predates the column came from the skill page's
+   * "Request write access", which asks for exactly that. A detail that cannot
+   * be fetched falls there too — the line it feeds says which level was asked
+   * for, and Can edit is the lesser claim.
    */
   private async levelOf(number: number): Promise<RequestLevel> {
     const detail = await this.deps.workflow
       .getChangeRequestDetail(number, { patches: false })
       .catch(() => null);
-    return extractRequestLevel(detail?.body) ?? 'write';
+    return detail?.accessRequest?.level ?? 'write';
   }
 
   /**
@@ -390,7 +339,12 @@ export class AccessRequestsService {
     }
   }
 
-  /** The description an editor reads: who, what, where, the note, and how to answer. */
+  /**
+   * The description an editor reads: who, what, where, the note, and how to
+   * answer. Prose only — the level and the note the platform reads back are
+   * the request's own columns, so nothing hidden is written here and an edit
+   * of the description loses nothing.
+   */
   private describe(input: {
     user: AuthUser;
     target: AccessRequestTarget;
@@ -400,14 +354,12 @@ export class AccessRequestsService {
     const { user, target, level, note } = input;
     const who = escapeMarkdown(user.name || user.email);
     const lines = [
-      `<!--hexis:access-request-level:${level}-->`,
       `${who} (${escapeMarkdown(user.email)}) asked for **${LEVEL_LABEL[level]}** on ` +
         `${escapeMarkdown(target.path || 'the workspace')}.`,
     ];
     if (note) {
-      lines.push('', `Note from ${who}:`, '', NOTE_OPEN);
+      lines.push('', `Note from ${who}:`, '');
       for (const line of note.split(/\r?\n/)) lines.push(`> ${escapeMarkdown(line)}`);
-      lines.push(NOTE_CLOSE);
     }
     lines.push(
       '',
@@ -418,3 +370,9 @@ export class AccessRequestsService {
     return lines.join('\n');
   }
 }
+
+/**
+ * What another module needs of the access-request service: to open one.
+ * Injected by the composition root, which owns the implementation.
+ */
+export type IAccessRequests = Pick<AccessRequestsService, 'open'>;