@bevel-software/platform-core-backend 0.22.0 → 0.24.0

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

@@ -84,11 +84,14 @@ export type HolderList = {
 export type PathHolders = { read: HolderList; write: HolderList };
 
 /**
- * One file's holders where it is now and where a move would put it — see
- * {@link IAccessControl.prospectiveHolders}.
+ * One file's or folder's holders where it is now and where a move would put
+ * it — see {@link IAccessControl.prospectiveHolders}.
  */
 export type ProspectiveHolders = { before: PathHolders; after: PathHolders };
 
+/** One caller's own verdict per access verb on one path. */
+export type PathVerbs = { read: boolean; write: boolean; download: boolean; owner: boolean };
+
 /**
  * Per-verb sources of a principal's access on a target. Only verbs the principal
  * actually holds (via a named file entry) appear; each maps to the closest-first
@@ -358,19 +361,17 @@ export interface IAccessControl {
   }>;
 
   /**
-   * Who can open and who can edit one file where it IS, and where a move
-   * would put it. `toPath` names a path that does not exist yet — the point
-   * of the call is to answer before the move happens — so the resolution
-   * layers the file's OWN rules (its frontmatter, read from `fromPath`,
-   * which travels with the bytes) over the destination's folder chain.
+   * Who can open and who can edit one file or folder where it IS, and where a
+   * move would put it. `toPath` names a path that does not exist yet — the
+   * point of the call is to answer before the move happens — so the
+   * resolution is over what travels with the bytes: a file's OWN rules (its
+   * frontmatter, read from `fromPath`) layered over the destination's folder
+   * chain, or a folder's `access.md` files keyed at the directories they
+   * land in. Either way the rules the source inherited from its old parent
+   * are left behind and the new parent's apply.
    *
    * Writes nothing and moves nothing. The move confirmation diffs the two
    * sides to name who loses and who gains access.
-   *
-   * A FILE question only: a `fromPath` that is a directory is refused with a
-   * 400. A folder's access is its own `access.md` — which moves with it and
-   * governs everything beneath it — so resolving it as a file would name the
-   * wrong principals with the same confidence as the right ones.
    */
   prospectiveHolders(
     workspaceId: string,
@@ -378,6 +379,36 @@ export interface IAccessControl {
     toPath: string,
   ): Promise<ProspectiveHolders>;
 
+  /**
+   * The CALLER'S OWN `{ read, write, download, owner }` at `toPath` as they
+   * will be once `fromPath` has been moved (`sourceRemains: false`, the
+   * default) or copied (`sourceRemains: true`) there — the question a move's
+   * or copy's dry run asks, which the same four gates at `toPath` cannot
+   * answer because what travels with the bytes is not at the destination yet:
+   * the `access.md` files inside a folder, keyed at the directories they land
+   * in, and a file's own frontmatter.
+   *
+   * What a single file's rules GOVERN follows the name it lands under, not the
+   * one it leaves: landing as a directory's `access.md` they are that
+   * directory's rules (so copying `Sales/access.md` to `Legal/access.md`
+   * previews the access `Legal/` is about to have), and landing under any
+   * other name they are the file's own and govern nothing but it. Either way
+   * the answer is the one the gates will give a moment later.
+   *
+   * PREVIEW ONLY. It describes a tree that does not exist, so it must never
+   * decide whether an operation may run: the gates keep resolving against the
+   * tree that does. It writes nothing and moves nothing, and it answers the
+   * caller's own verbs only — never the content of an `access.md` they may
+   * not read.
+   */
+  previewAccessAfterRelocation(
+    workspaceId: string,
+    userEmail: string,
+    fromPath: string,
+    toPath: string,
+    opts?: { sourceRemains?: boolean },
+  ): Promise<PathVerbs>;
+
   /**
    * Finite expanded email set for configured users who could approve this path
    * — role members + direct user grants, minus anyone denied. The built-in

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

@@ -5,7 +5,7 @@ import { logger } from '../../shared/logging.js';
 const log = logger('access');
 
 import { isAbsence, type ITreeWalker, type WalkListener } from '../../shared/fs.contract.js';
-import { isGitTimeout, type IGitRunner } from '../../shared/git.contract.js';
+import { assertOneSpecPerLine, 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 type { WorkspaceService } from '../workspace/workspace.service.js';
@@ -19,6 +19,7 @@ import type {
   GrantSource,
   GrantSources,
   PathHolders,
+  PathVerbs,
   ProspectiveHolders,
   ResolvedPrincipal,
 } from './access-control.interface.js';
@@ -31,7 +32,6 @@ import {
 } from '@bevel-software/platform-shared';
 import type { KbContext } from '../../shared/kb-context.js';
 import { AccessConfigError, AccessUnreadableError } from '../access-model/access-errors.js';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import { synthesizePluginPrincipals } from '../access-model/plugin-principals.js';
 import {
   GROUPS_YAML,
@@ -81,6 +81,12 @@ async function catFileBatch(
 ): Promise<(string | null)[]> {
   // Bytes, not text: every `<size>` in the header counts bytes, and the walk
   // below has to step by that count through content that is not all ASCII.
+  // One spec per LINE is the protocol, and this walk depends on getting back
+  // exactly as many answers as it sent: a spec carrying a line break would
+  // insert an extra answer and shift every result after it, so each directory
+  // would be handed the NEXT one's `access.md`. Paths are refused a control
+  // character at the normaliser; this is the fence at the protocol.
+  assertOneSpecPerLine(specs);
   const { stdout: out } = await runner.run(repoDir, ['cat-file', '--batch'], {
     input: `${specs.join('\n')}\n`,
     encoding: 'buffer',
@@ -951,6 +957,95 @@ function resolveDenialSourcesForVerb(
   return out;
 }
 
+/**
+ * The model as it will be once `fromPath` has been moved or copied to
+ * `toPath`: every `access.md` the operation carries, keyed at the directory
+ * it lands in, since the rules a folder carries travel with its bytes.
+ *
+ * What travels is BYTES, and the name they land under decides what they
+ * govern — `landing` is the caller's answer to that (see
+ * `relocationSubject`), already parsed as the destination path:
+ *
+ * - a FOLDER takes every `access.md` at or under it, each re-keyed to the
+ *   directory it lands in, and `landing` plays no part;
+ * - a FILE governs a directory exactly when it lands as that directory's
+ *   `access.md`, whatever it was called before — a copy `copy_file` allows,
+ *   and one that governs the destination folder the moment it lands. Its key
+ *   is a PARENT directory, never a path under `fromPath`, which is why the
+ *   prefix walk above cannot see it.
+ *
+ * The emptied side is the mirror: an `access.md` that MOVES stops governing
+ * the directory it left, whether or not it governs anything where it lands.
+ *
+ * PREVIEW ONLY. Nothing here reads disk and nothing here decides whether an
+ * operation may run — the gates resolve against the model as it IS. This
+ * answers the other question, the one a dry run asks: what will be true
+ * afterwards. Judging the destination as it stands today is what made a
+ * rename warn about losing the owner access the folder's own `access.md` was
+ * about to hand straight back.
+ *
+ * `sourceRemains` is the difference between a copy and a move: a copy leaves
+ * the rules where they were, a move takes them away. It changes the answer
+ * only when the destination resolves through a directory the source
+ * occupied; nothing else consults those keys.
+ */
+function withRelocatedAccessFiles(
+  model: AccessModel,
+  fromPath: string,
+  toPath: string,
+  opts: { sourceRemains: boolean; sourceIsFolder: boolean; landing?: AccessFile | null },
+): AccessModel {
+  /** Directories the operation takes an `access.md` AWAY from. */
+  const emptied: string[] = [];
+  /** Directories it leaves one IN, with the file as it will be read there. */
+  const landing: { toDir: string; file: AccessFile }[] = [];
+  if (opts.sourceIsFolder) {
+    for (const [dir, file] of model.accessFilesByDir) {
+      if (dir !== fromPath && !dir.startsWith(`${fromPath}/`)) continue;
+      emptied.push(dir);
+      landing.push({ toDir: `${toPath}${dir.slice(fromPath.length)}`, file });
+    }
+  } else {
+    const fromDir = parentDirOf(fromPath);
+    if (isAccessMdPath(fromPath) && model.accessFilesByDir.has(fromDir)) emptied.push(fromDir);
+    if (opts.landing) landing.push({ toDir: parentDirOf(toPath), file: opts.landing });
+  }
+  if (emptied.length === 0 && landing.length === 0) return model;
+  const accessFilesByDir = new Map(model.accessFilesByDir);
+  if (!opts.sourceRemains) for (const dir of emptied) accessFilesByDir.delete(dir);
+  for (const { toDir, file } of landing) {
+    // A directory that already has an `access.md` keeps it. The operation
+    // would be refused for landing on something that exists long before the
+    // two files could meet, so the model must not invent a merge either.
+    if (accessFilesByDir.has(toDir)) continue;
+    accessFilesByDir.set(toDir, {
+      ...file,
+      dir: toDir,
+      path: toDir ? `${toDir}/access.md` : 'access.md',
+    });
+  }
+  return { ...model, accessFilesByDir };
+}
+
+/** The directory a repo-relative file path sits in; `''` for the repo root. */
+function parentDirOf(relativePath: string): string {
+  const cut = relativePath.lastIndexOf('/');
+  return cut === -1 ? '' : relativePath.slice(0, cut);
+}
+
+/**
+ * One file's own-entries, parsed as the path `asName` would be read.
+ *
+ * The same frontmatter means two different things by name: in an `access.md`
+ * it is the FOLDER's rules (and the file governs itself only through the
+ * body format — see {@link accessMdSelfEntries}), and anywhere else it is the
+ * file's own. Which is why a preview must read the bytes as the name they
+ * LAND under, not the one they are leaving.
+ */
+function ownEntriesFromText(text: string, asName: string): OwnEntries | null {
+  return isAccessMdPath(asName) ? accessMdSelfEntries(text) : parseOwnAccessEntries(text);
+}
+
 /**
  * Build the repo-root → path chain of directory scopes that govern
  * `relativePath`, e.g. `Knowledge/Sales/Foo.md` →
@@ -1586,16 +1681,25 @@ export class AccessControlService implements IAccessControl {
   }
 
   /**
-   * The read and write holders of one file at its current path and at a path
-   * it has not moved to yet (see the interface).
+   * The read and write holders of one file or folder at its current path and
+   * at a path it has not moved to yet (see the interface).
+   *
+   * A move changes nothing about what the thing itself carries — a file's
+   * frontmatter and a folder's `access.md` files travel with the bytes — and
+   * everything about the folder chain above it. So the hypothetical side is
+   * the ordinary resolution at the destination path, over what travels:
    *
-   * A move changes nothing about the file's own frontmatter — that travels
-   * with the bytes — and everything about the folder chain above it. So the
-   * hypothetical side is the ordinary resolution with the destination path
-   * substituted: the same model, the same own-entries (read from the SOURCE,
-   * since nothing sits at the destination to read), resolved against the
-   * destination's ancestors. One model load and one file read serve all four
-   * lookups.
+   * - a FILE's own-entries, read from the SOURCE (nothing sits at the
+   *   destination to read) and parsed as the name they LAND under, layered
+   *   over the destination's ancestors — the two sides can differ, because
+   *   the same frontmatter is a folder's rules in an `access.md` and the
+   *   file's own anywhere else;
+   * - a FOLDER's `access.md` files, keyed at the directories they land in,
+   *   and a file landing as a directory's `access.md` at the directory it
+   *   lands in (`withRelocatedAccessFiles`). A folder has no frontmatter of
+   *   its own, so it passes none.
+   *
+   * One model load and one file read serve all four lookups.
    */
   async prospectiveHolders(
     workspaceId: string,
@@ -1604,31 +1708,64 @@ export class AccessControlService implements IAccessControl {
   ): Promise<ProspectiveHolders> {
     const model = await this.loadModel(workspaceId);
     const repoDir = await this.repoDir(workspaceId);
-    // A FILE question only. A folder carries its own `access.md` — which moves
-    // with it and governs everything under it — so resolving it as a file
-    // would read frontmatter it does not have and omit the rules it does,
-    // naming principals that are not the ones a folder move changes. Refuse
-    // rather than answer the wrong question convincingly.
-    //
-    // Only absence is an answer here (see `isAbsence`): a probe that failed on
-    // permissions or I/O does not say "this is a file", and folding it into
-    // one would let the very case above through on an unreadable source.
-    const fromStat = await fs.stat(path.join(repoDir, fromPath)).catch((err: unknown) => {
-      if (isAbsence(err)) return null;
-      throw err;
+    const { isFolder, ownHere, ownThere, landing } =
+      await this.relocationSubject(repoDir, fromPath, toPath);
+    const after = withRelocatedAccessFiles(model, fromPath, toPath, {
+      sourceRemains: false,
+      sourceIsFolder: isFolder,
+      landing,
     });
-    if (fromStat?.isDirectory()) {
-      throw new WorkflowDomainError(
-        'prospective access answers for a file, not a folder',
-        400,
-      );
-    }
-    const own = await this.readOwnEntries(repoDir, fromPath);
-    const holdersAt = (relativePath: string): PathHolders => ({
-      read: eligibleHoldersResolved(model, 'read', relativePath, own),
-      write: eligibleHoldersResolved(model, 'write', relativePath, own),
+    const holdersAt = (m: AccessModel, relativePath: string, own: OwnEntries | null): PathHolders => ({
+      read: eligibleHoldersResolved(m, 'read', relativePath, own),
+      write: eligibleHoldersResolved(m, 'write', relativePath, own),
     });
-    return { before: holdersAt(fromPath), after: holdersAt(toPath) };
+    return {
+      before: holdersAt(model, fromPath, ownHere),
+      after: holdersAt(after, toPath, ownThere),
+    };
+  }
+
+  /**
+   * The caller's own verbs at `toPath` as they will be once `fromPath` has
+   * been moved or copied there (see the interface).
+   *
+   * Identical to asking `canRead`/`canWrite`/`canDownload`/`canOwner` at
+   * `toPath` whenever nothing travels — an ordinary file with no rules of its
+   * own, or a folder with no `access.md` of its own — so the cases this was
+   * not written for answer exactly as they always did.
+   *
+   * What travels is what `prospectiveHolders` says travels, and for the same
+   * reason: the preview and the dialog's holder lists must not disagree about
+   * one move. A file's own-entries come from the SOURCE, where the bytes
+   * carrying them still are — asking the destination, which does not exist
+   * yet, always answered null and so dropped the frontmatter a rename hands
+   * straight back (requirement 6: what the caller has afterwards equals what
+   * the preview said) — and they are parsed as the name they LAND under,
+   * because that is the parse the gates will use a moment later.
+   */
+  async previewAccessAfterRelocation(
+    workspaceId: string,
+    userEmail: string,
+    fromPath: string,
+    toPath: string,
+    opts?: { sourceRemains?: boolean },
+  ): Promise<PathVerbs> {
+    const repoDir = await this.repoDir(workspaceId);
+    const { isFolder, ownThere: own, landing } =
+      await this.relocationSubject(repoDir, fromPath, toPath);
+    const model = withRelocatedAccessFiles(
+      await this.loadModel(workspaceId),
+      fromPath,
+      toPath,
+      { sourceRemains: opts?.sourceRemains === true, sourceIsFolder: isFolder, landing },
+    );
+    const machineOwned = this.machineOwnedWriteRule(userEmail, toPath);
+    return {
+      read: canReadResolved(model, userEmail, toPath, own),
+      write: machineOwned ?? hasPermissionResolved(model, 'write', userEmail, toPath, own),
+      download: hasPermissionResolved(model, 'download', userEmail, toPath, own),
+      owner: hasPermissionResolved(model, 'owner', userEmail, toPath, own),
+    };
   }
 
   async eligibleWriterEmails(
@@ -2219,8 +2356,69 @@ export class AccessControlService implements IAccessControl {
     } catch {
       return null;
     }
-    if (isAccessMdPath(relativePath)) return accessMdSelfEntries(text);
-    return parseOwnAccessEntries(text);
+    return ownEntriesFromText(text, relativePath);
+  }
+
+  /**
+   * What a move or a copy of `fromPath` to `toPath` CARRIES — the one disk
+   * read both preview surfaces need:
+   *
+   * - `isFolder`: the source is a folder, so the `access.md` files under it
+   *   travel, keyed at the directories they land in;
+   * - `ownHere` / `ownThere`: a file's own-entries as the SOURCE's name reads
+   *   them and as the DESTINATION's name will. They differ because the same
+   *   frontmatter means two things by name (see `ownEntriesFromText`), so
+   *   `Sales/access.md` copied to `Legal/rules-copy.md` arrives as an
+   *   ordinary file whose frontmatter is its own — reading it as the source's
+   *   name had the preview contradict the copy it was previewing;
+   * - `landing`: the folder rules the bytes WILL be, when they land under the
+   *   name `access.md`. Parsed as the destination path, so the directory it
+   *   governs is already the right one. An `access.md` that will not parse
+   *   travels as nothing, as the loader treats it.
+   *
+   * `lstat`, not `stat`: a SYMLINK is none of this. `move_file` refuses a
+   * symlink source outright, so a link to a directory must not be previewed
+   * as a folder taking access files along, and nothing is read THROUGH the
+   * link either — the link's target is not what would move.
+   *
+   * Only absence is an answer (see `isAbsence`): a probe that failed on
+   * permissions or I/O does not say "this is a file", and reading a folder as
+   * one would resolve it through frontmatter it does not have.
+   */
+  private async relocationSubject(
+    repoDir: string,
+    fromPath: string,
+    toPath: string,
+  ): Promise<{
+    isFolder: boolean;
+    ownHere: OwnEntries | null;
+    ownThere: OwnEntries | null;
+    landing: AccessFile | null;
+  }> {
+    const nothing = { isFolder: false, ownHere: null, ownThere: null, landing: null };
+    const fromStat = await fs.lstat(path.join(repoDir, fromPath)).catch((err: unknown) => {
+      if (isAbsence(err)) return null;
+      throw err;
+    });
+    if (fromStat?.isSymbolicLink() === true) return nothing;
+    if (fromStat?.isDirectory() === true) return { ...nothing, isFolder: true };
+    // `roles.yaml` carries no own-entries wherever it sits, exactly as
+    // `readOwnEntries` has it; a read that fails for any reason is no rules,
+    // which is what the gates would say about the same file.
+    if (fromPath === 'roles.yaml' || toPath === 'roles.yaml') return nothing;
+    let text: string;
+    try {
+      text = await fs.readFile(path.join(repoDir, fromPath), 'utf-8');
+    } catch {
+      return nothing;
+    }
+    const parsed = isAccessMdPath(toPath) ? parseAccessFile(text, toPath) : null;
+    return {
+      isFolder: false,
+      ownHere: ownEntriesFromText(text, fromPath),
+      ownThere: ownEntriesFromText(text, toPath),
+      landing: parsed?.ok === true ? parsed.file : null,
+    };
   }
 
   /**

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

@@ -368,27 +368,25 @@ export function createAccessRoutes(
   });
 
   /**
-   * GET /api/workspace/:id/access/prospective?from=<file>&toDir=<folder>
+   * GET /api/workspace/:id/access/prospective?from=<file|folder>&toDir=<folder>
    *
-   * Who can open and who can edit one file where it is, and where a move
-   * would put it — `{ before, after }`, each `{ read, write }` lists of
-   * principals named as their grants name them. `toDir` is the destination
-   * FOLDER (`''` is the repo root); the file keeps its name, so the route
-   * derives the destination path itself rather than trusting a second one.
+   * Who can open and who can edit one file OR FOLDER where it is, and where
+   * a move would put it — `{ before, after }`, each `{ read, write }` lists
+   * of principals named as their grants name them. `toDir` is the
+   * destination FOLDER (`''` is the repo root); the thing keeps its name, so
+   * the route derives the destination path itself rather than trusting a
+   * second one.
    *
    * The destination path does not exist yet, which is why this cannot be two
-   * calls to `GET /access`: the resolver is asked for a hypothetical, with
-   * the file's own frontmatter (read where the file actually is) layered over
-   * the destination's folder chain. Nothing is written and nothing is moved.
+   * calls to `GET /access`: the resolver is asked for a hypothetical, over
+   * what the move carries — a file's own frontmatter, or the `access.md`
+   * files inside a folder, at the paths they land on. Nothing is written and
+   * nothing is moved.
    *
    * Gated like the sibling `overrides` route rather than the permissive
-   * `GET /access`: the caller must resolve read on the file being moved. The
-   * lists name people, and someone who cannot see the file has no business
+   * `GET /access`: the caller must resolve read on the thing being moved. The
+   * lists name people, and someone who cannot see it has no business
    * learning who can.
-   *
-   * `from` must be a FILE. A folder carries its own `access.md` and governs
-   * everything under it, which is a different question; the resolver refuses
-   * one with a 400 rather than answering it as if it were a file.
    */
   router.get('/workspace/:id/access/prospective', async (req, res) => {
     const user = await requireUser(req, res);
@@ -726,10 +724,13 @@ export function createAccessRoutes(
   async function accountsAmong(emails: string[]): Promise<Set<string>> {
     // `inArray` refuses an empty list, and there is nothing to ask anyway.
     if (emails.length === 0) return new Set();
+    // Through the blind index: `email` is randomized ciphertext, and the
+    // index is what the unique constraint and every lookup key on. It is
+    // compared with the addresses themselves.
     const rows = await db
       .select({ email: users.email })
       .from(users)
-      .where(inArray(users.email, emails));
+      .where(inArray(users.emailBidx, emails));
     return new Set(rows.map((r) => r.email.trim().toLowerCase()));
   }
 

package/src/modules/access/directory-sync-bot.ts

@@ -26,8 +26,12 @@ export const DIRECTORY_SYNC_BOT_NAME = 'Directory Sync Bot';
 export async function ensureDirectorySyncBot(db: Database): Promise<AuthUser> {
   const inserted = await db
     .insert(users)
-    .values({ email: DIRECTORY_SYNC_BOT_EMAIL, name: DIRECTORY_SYNC_BOT_NAME })
-    .onConflictDoNothing({ target: users.email })
+    .values({
+      email: DIRECTORY_SYNC_BOT_EMAIL,
+      emailBidx: DIRECTORY_SYNC_BOT_EMAIL,
+      name: DIRECTORY_SYNC_BOT_NAME,
+    })
+    .onConflictDoNothing({ target: users.emailBidx })
     .returning();
   if (inserted.length > 0) {
     const row = inserted[0];
@@ -37,7 +41,7 @@ export async function ensureDirectorySyncBot(db: Database): Promise<AuthUser> {
   const [row] = await db
     .select()
     .from(users)
-    .where(eq(users.email, DIRECTORY_SYNC_BOT_EMAIL))
+    .where(eq(users.emailBidx, DIRECTORY_SYNC_BOT_EMAIL))
     .limit(1);
   if (!row) {
     throw new Error(

package/src/modules/agent-instructions/__tests__/agent-instructions.route.test.ts

@@ -6,7 +6,11 @@ import type { IExternalApiKeyService } from '../../tool-auth/external-api-key.in
 import type { InternalTokenService } from '../../tool-auth/internal-token.service.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import { createAgentInstructionsRoutes } from '../agent-instructions.routes.js';
-import { PLATFORM_HEADER, TOOL_PREFIX_LINE } from '../compose.js';
+import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
+import { TOOL_PREFIX_LINE, platformInstructions } from '../compose.js';
+
+/** The platform-owned text the route leads with: header + the shared file rules. */
+const PLATFORM = platformInstructions(DEFAULT_KB_LAYOUT);
 
 /**
  * `GET /agent/instructions` behind the REAL manual-auth gate, with the three
@@ -31,11 +35,13 @@ async function serve(readPreamble: () => Promise<string | null>): Promise<string
     looksLikeInternalToken: (t: string) => t.startsWith('bit_'),
     verify: (t: string) => (t === INTERNAL_TOKEN ? { userId: 'u-internal' } : null),
   } as unknown as InternalTokenService;
+  // Sessions and internal tokens are accepted only for an account that is on; these are.
   const authService = {
-    verifyToken: (t: string) => {
+    resolveSession: async (t: string) => {
       if (t !== BROWSER_JWT) throw new Error('bad jwt');
       return { userId: 'u-browser' };
     },
+    isActive: async () => true,
   } as unknown as AuthService;
   const app = express();
   app.use('/api', createAgentInstructionsRoutes(createManualAuthMiddleware(externalKeys, internalTokens, authService), readPreamble));
@@ -59,7 +65,7 @@ describe('GET /agent/instructions', () => {
       expect(res.status, bearer).toBe(200);
       expect(res.headers.get('cache-control')).toBe('no-store');
       const body = (await res.json()) as Record<string, unknown>;
-      expect(body.instructions).toBe(`${PLATFORM_HEADER}\n\nAcme builds solar farms.`);
+      expect(body.instructions).toBe(`${PLATFORM}\n\nAcme builds solar farms.`);
       expect(body.toolPrefix).toBe(`${TOOL_PREFIX_LINE} Acme builds solar farms.`);
       expect(body).toMatchObject({
         truncated: false,
@@ -77,12 +83,12 @@ describe('GET /agent/instructions', () => {
     expect((await fetch(url, { headers: { Authorization: 'Bearer not-a-session' } })).status).toBe(401);
   });
 
-  it('a missing file yields the header alone', async () => {
+  it('a missing file yields the platform text alone', async () => {
     const url = await serve(async () => null);
     const res = await fetch(url, { headers: { Authorization: `Bearer ${CONNECTION_KEY}` } });
     expect(res.status).toBe(200);
     const body = (await res.json()) as { instructions: string; toolPrefix: string; preambleChars: number };
-    expect(body.instructions).toBe(PLATFORM_HEADER);
+    expect(body.instructions).toBe(PLATFORM);
     expect(body.toolPrefix).toBe(TOOL_PREFIX_LINE);
     expect(body.preambleChars).toBe(0);
   });

package/src/modules/agent-instructions/__tests__/compose.test.ts

@@ -1,6 +1,8 @@
+import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
 import { describe, expect, it } from 'vitest';
 import {
   PLATFORM_HEADER,
+  platformInstructions,
   PREAMBLE_CAP,
   PREAMBLE_TRUNCATION_MARKER,
   TOOL_PREFIX_CAP,
@@ -13,13 +15,19 @@ import {
  * The composer is pure, so every rule of the two texts is pinned here: what
  * an absent or empty preamble yields, how comments are withheld, where both
  * caps cut, and that a cut never splits a character.
+ *
+ * `PLATFORM` is everything the code owns and the admin cannot edit: the header
+ * and the rules every file tool shares, which is what the handshake leads with.
+ * The rules themselves are pinned in `shared-file-rules.test.ts`; here they are
+ * only the fixed text the preamble follows.
  */
+const PLATFORM = platformInstructions(DEFAULT_KB_LAYOUT);
 
 describe('composeAgentInstructions: the handshake text', () => {
-  it('sends the header alone for an absent, empty, whitespace or comment-only preamble', () => {
+  it('sends the platform text alone — header and shared rules — for an absent, empty, whitespace or comment-only preamble', () => {
     for (const raw of [null, '', '   \n\n', '<!-- notes to myself -->', '<!--\nline one\nline two\n-->\n']) {
       const out = composeAgentInstructions(raw);
-      expect(out.instructions, JSON.stringify(raw)).toBe(PLATFORM_HEADER);
+      expect(out.instructions, JSON.stringify(raw)).toBe(PLATFORM);
       expect(out.toolPrefix).toBe(TOOL_PREFIX_LINE);
       expect(out.truncated).toBe(false);
       expect(out.toolPrefixTruncated).toBe(false);
@@ -28,15 +36,16 @@ describe('composeAgentInstructions: the handshake text', () => {
     }
   });
 
-  it('is the header, a blank line, then the preamble body', () => {
+  it('is the platform text, a blank line, then the preamble body', () => {
     const out = composeAgentInstructions('We sell permits.\n\nLook in Permitting/ first.\n');
-    expect(out.instructions).toBe(`${PLATFORM_HEADER}\n\nWe sell permits.\n\nLook in Permitting/ first.`);
+    expect(out.instructions).toBe(`${PLATFORM}\n\nWe sell permits.\n\nLook in Permitting/ first.`);
     expect(out.preambleChars).toBe('We sell permits.\n\nLook in Permitting/ first.'.length);
   });
 
   it('hands the two parts and the fixed prefix line back separately, for the card', () => {
     const out = composeAgentInstructions('We sell permits.');
-    expect(out.header).toBe(PLATFORM_HEADER);
+    expect(out.header).toBe(PLATFORM);
+    expect(out.header.startsWith(PLATFORM_HEADER)).toBe(true);
     expect(out.preamble).toBe('We sell permits.');
     expect(out.toolPrefixLine).toBe(TOOL_PREFIX_LINE);
     expect(out.toolPrefix.startsWith(out.toolPrefixLine)).toBe(true);
@@ -56,7 +65,7 @@ describe('composeAgentInstructions: the handshake text', () => {
 
   it('an unterminated comment withholds everything after it and is reported', () => {
     const out = composeAgentInstructions('Visible.\n\n<!-- forgot to close\nSecret folder names\n');
-    expect(out.instructions).toBe(`${PLATFORM_HEADER}\n\nVisible.`);
+    expect(out.instructions).toBe(`${PLATFORM}\n\nVisible.`);
     expect(out.instructions).not.toContain('Secret');
     expect(out.toolPrefix).toBe(`${TOOL_PREFIX_LINE} Visible.`);
     expect(out.unterminatedComment).toBe(true);
@@ -66,12 +75,12 @@ describe('composeAgentInstructions: the handshake text', () => {
     const exact = 'a'.repeat(PREAMBLE_CAP);
     const atCap = composeAgentInstructions(exact);
     expect(atCap.truncated).toBe(false);
-    expect(atCap.instructions).toBe(`${PLATFORM_HEADER}\n\n${exact}`);
+    expect(atCap.instructions).toBe(`${PLATFORM}\n\n${exact}`);
     expect(atCap.instructions).not.toContain('truncated');
 
     const over = composeAgentInstructions(`${exact}b`);
     expect(over.truncated).toBe(true);
-    expect(over.instructions).toBe(`${PLATFORM_HEADER}\n\n${exact}\n${PREAMBLE_TRUNCATION_MARKER}`);
+    expect(over.instructions).toBe(`${PLATFORM}\n\n${exact}\n${PREAMBLE_TRUNCATION_MARKER}`);
     expect(PREAMBLE_TRUNCATION_MARKER).toContain('6,000');
     expect(PREAMBLE_TRUNCATION_MARKER).toContain('mcp-description.md');
   });
@@ -93,7 +102,7 @@ describe('composeAgentInstructions: the handshake text', () => {
     const raw = `${'a'.repeat(PREAMBLE_CAP - 1)}😀tail`;
     const out = composeAgentInstructions(raw);
     expect(out.truncated).toBe(true);
-    const body = out.instructions.slice(PLATFORM_HEADER.length + 2);
+    const body = out.instructions.slice(PLATFORM.length + 2);
     const sent = body.slice(0, body.indexOf('\n'));
     expect(sent).toBe('a'.repeat(PREAMBLE_CAP - 1));
     expect(sent.length).toBe(PREAMBLE_CAP - 1);
@@ -222,7 +231,7 @@ describe('composeAgentInstructions: the tool prefix', () => {
   it('CRLF input still yields the first paragraph', () => {
     const out = composeAgentInstructions('# Title\r\n\r\nFirst paragraph.\r\n\r\nSecond.\r\n');
     expect(out.toolPrefix).toBe(`${TOOL_PREFIX_LINE} First paragraph.`);
-    expect(out.instructions).toBe(`${PLATFORM_HEADER}\n\n# Title\n\nFirst paragraph.\n\nSecond.`);
+    expect(out.instructions).toBe(`${PLATFORM}\n\n# Title\n\nFirst paragraph.\n\nSecond.`);
   });
 
   it('is at most the cap, still starting with the fixed line, and reports the count before the cut', () => {