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

package/src/modules/workspace/routine-write-policy.ts

@@ -1,9 +1,9 @@
 /**
  * Per-run write restriction for background/routine agents.
  *
- * The ontology-session gate ({@link ../workflow/session-ontology.service}) bounds
- * WHICH ontology a run may write; this narrower gate bounds WHAT KIND of file a
- * run may write, by extension. It exists for the `watchlist_check` routine, which is
+ * The agent-access gate ({@link ./agent-access.gate}) lets a deployment decide
+ * WHETHER a run may write a path at all; this narrower gate bounds WHAT KIND of
+ * file a run may write, by extension. It exists for the `watchlist_check` routine, which is
  * allowed to refresh dashboard views (`.html`) but must never touch the
  * knowledge-graph nodes (`.md`) or any other file — a hard, code-level guarantee
  * rather than a prompt request (a prompt-only rule has already proven insufficient).
@@ -11,9 +11,8 @@
  * Keyed by the agent run's `sessionId` (the background agent passes its run id as
  * the session id, which the internal token then carries onto every loopback tool
  * call as `ctx.sessionId`). A restriction lives only for the duration of one
- * in-process run, so the store is a plain in-memory map — no durability needed,
- * unlike the ontology touched-set which must survive restarts and span the MCP
- * proxy. The executor sets the restriction before streaming and clears it after.
+ * in-process run, so the store is a plain in-memory map — no durability needed.
+ * The executor sets the restriction before streaming and clears it after.
  */
 
 import { ToolError } from '../tool-helpers/tool.contract.js';

package/src/modules/workspace/session-sink.ts

@@ -1,12 +1,12 @@
 import { randomUUID } from 'node:crypto';
 
 /**
- * Port behind `start_session` (workspace.tools.ts): mints the session id an
- * external agent scopes its ontology boundary under. The workspace module owns
- * the port; WHAT backs the id is the composition root's choice:
+ * Port behind `start_session` (workspace.tools.ts): mints the id an external
+ * agent names its conversation with. The workspace module owns the port; WHAT
+ * backs the id is the composition root's choice:
  *
- * - Core default ({@link UuidSessionSink}): a bare random id — sufficient for
- *   the session-ontology gate, with no app-side session record.
+ * - Core default ({@link UuidSessionSink}): a bare random id — all the
+ *   agent-access hooks need, with no app-side session record.
  * - The enterprise app substitutes a sink that mints a REAL chat thread, so the
  *   same id also works end to end with `ask` (its sessionId IS a chat thread).
  *   See the `start_session` comment in workspace.tools.ts for why that

package/src/modules/workspace/set-aside-clone.ts

@@ -0,0 +1,96 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Moving a working copy of a repository that is no longer the configured one
+ * OUT OF THE WAY, rather than deleting it.
+ *
+ * Two places find such a clone: the KB startup phase, sweeping the whole
+ * workspaces root at boot and on the save that changes the address, and the
+ * workspace service, refusing to adopt one it finds on disk. Both must do the
+ * same thing with it, because what is in it is the same thing: commits that
+ * may exist nowhere else. A clone fetches and pushes through the address in
+ * its own `remote.origin.url`, and two repositories need not share a commit,
+ * so such a clone cannot be re-pointed — but that is a reason not to USE it,
+ * never a reason to destroy it.
+ */
+
+/**
+ * Where working copies are set aside. NOT under the workspaces root: the
+ * workspace service's orphan sweep removes every folder there that is not a
+ * known branch's, and what is set aside has to outlive that sweep.
+ *
+ * PASS THE OVERRIDE, and pass BOTH CALLERS THE SAME ONE. The fallback is a
+ * sibling of the workspaces root, which is a lasting place only when that
+ * parent is itself a mounted volume — in the shipped compose file it is the
+ * container's own filesystem, so a copy left there is gone at the next
+ * recreate, having been kept on the promise that it would not be. The
+ * composition root therefore roots both the startup phase and the workspace
+ * service at one directory under the backups volume; the fallback is for a
+ * test, or a caller with no deployment layout to speak of.
+ */
+export function setAsideRootFor(workspacesRoot: string, override?: string): string {
+  return override ?? path.resolve(workspacesRoot, '..', 'replaced-working-copies');
+}
+
+/**
+ * One folder per occasion, so what was set aside together stays together and
+ * two replacements never land in each other's folder.
+ */
+export function setAsideStamp(at: Date = new Date()): string {
+  return at.toISOString().replace(/[:.]/g, '-');
+}
+
+/**
+ * Move the clone at `repoDir` to `dest`. A rename when it can be one; a copy
+ * when it cannot (another volume, a handle held open on it), and only then is
+ * the original removed — so a copy that fails leaves the clone exactly where
+ * it was rather than half of it in each place.
+ *
+ * Throws with what to do about it. The caller decides how much that costs:
+ * the startup phase stops the boot (leaving the clone would fail a step later
+ * with git's words about a repository nobody configured), while a single
+ * branch open refuses that branch.
+ */
+export async function setAsideClone(repoDir: string, dest: string): Promise<void> {
+  // A destination that is already there is somebody's set-aside work, and
+  // never this call's to touch: the copy below cleans up after itself by
+  // removing the destination, which must then be one this call made.
+  const taken = (): Error =>
+    new Error(
+      `Could not set aside the working copy at ${repoDir}: ${dest} already holds one. Nothing was deleted or ` +
+        'moved. Try again; the folder is named for the moment it is made.',
+    );
+  if (await fs.access(dest).then(() => true, () => false)) throw taken();
+  await fs.mkdir(path.dirname(dest), { recursive: true });
+  try {
+    await fs.rename(repoDir, dest);
+    return;
+  } catch {
+    // Another volume, or a handle held open on it: copy instead.
+  }
+  // The destination is MADE here, by the one call that will fill it. Two
+  // calls that both found it absent above cannot both make it: the second
+  // is refused by the filesystem, before the cleanup below could ever be
+  // about a folder it did not create.
+  try {
+    await fs.mkdir(dest);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'EEXIST') throw taken();
+    throw err;
+  }
+  try {
+    // Into the empty folder made above, which is why an existing destination
+    // is not an error here; nothing is overwritten (`force: false`).
+    await fs.cp(repoDir, dest, { recursive: true, errorOnExist: false, force: false, verbatimSymlinks: true });
+  } catch (err) {
+    await fs.rm(dest, { recursive: true, force: true }).catch(() => undefined);
+    throw new Error(
+      `Could not set aside the working copy at ${repoDir}, a clone of a repository that is no longer the ` +
+        `configured one, into ${dest}: ${err instanceof Error ? err.message : String(err)}. Nothing was deleted. ` +
+        'Make room there, or move that folder away by hand, and start again.',
+      { cause: err },
+    );
+  }
+  await fs.rm(repoDir, { recursive: true, force: true });
+}

package/src/modules/workspace/startup/__tests__/kb-startup-runner.test.ts

@@ -302,6 +302,92 @@ describe('KbStartupRunner — the repository was replaced', () => {
     expect((await git(repo, ['rev-parse', 'HEAD'])).trim()).toBe(head);
   });
 
+it('tells the workspace layer about every working copy it deletes', async () => {
+    // On a SAVE the process is already running, and the workspace service
+    // caches branch→directory. A clone that was set aside, left in that cache,
+    // is a path to nothing, and nothing would ever re-clone it.
+    await bootedOnTheOldRepository();
+    const replacement = await replacementUpstream();
+    const discarded: string[] = [];
+
+    await makeRunner([touchDefault], {
+      kbRepoUrl: () => replacement,
+      onCloneDiscarded: (id: string) => discarded.push(id),
+    }).runAll();
+
+    expect(discarded.sort()).toEqual(
+      [encodeURIComponent(DEFAULT_BRANCH), encodeURIComponent('someone/draft')].sort(),
+    );
+  });
+
+  /**
+   * Holding back the queue of a working copy is a precondition of setting it
+   * aside. A phase that carried on past a failure there would clone the
+   * replacement over an untouched queue, and the worker would commit those
+   * bytes into a repository they were never meant for.
+   */
+  it('stops, with the working copy still in place, when its queue cannot be held back first', async () => {
+    await bootedOnTheOldRepository();
+    const replacement = await replacementUpstream();
+    const before = (await git(cloneDir(DEFAULT_BRANCH), ['config', '--get', 'remote.origin.url'])).trim();
+    const discarded: string[] = [];
+
+    await expect(
+      makeRunner([touchDefault], {
+        kbRepoUrl: () => replacement,
+        beforeCloneSetAside: async () => {
+          throw new Error('pending_commits is down');
+        },
+        onCloneDiscarded: (id: string) => discarded.push(id),
+      }).runAll(),
+    ).rejects.toThrow(/pending_commits is down/);
+
+    // Nothing moved: the next run finds the same copy and asks again.
+    expect((await git(cloneDir(DEFAULT_BRANCH), ['config', '--get', 'remote.origin.url'])).trim()).toBe(before);
+    expect(discarded).toEqual([]);
+  });
+
+  it('holds back the queue of each working copy before it sets that copy aside', async () => {
+    await bootedOnTheOldRepository();
+    const replacement = await replacementUpstream();
+    const order: string[] = [];
+
+    await makeRunner([touchDefault], {
+      kbRepoUrl: () => replacement,
+      beforeCloneSetAside: async (id: string) => void order.push(`queue ${id}`),
+      onCloneDiscarded: (id: string) => void order.push(`aside ${id}`),
+    }).runAll();
+
+    const main = encodeURIComponent(DEFAULT_BRANCH);
+    expect(order.indexOf(`queue ${main}`)).toBeGreaterThanOrEqual(0);
+    expect(order.indexOf(`queue ${main}`)).toBeLessThan(order.indexOf(`aside ${main}`));
+  });
+
+  it('tells the git layer that each working copy it cloned is freshly fetched', async () => {
+    // A clone holds every ref, so it IS a successful fetch. Unsaid, the git
+    // layer keeps the per-workspace record that drove the replacement — a
+    // FAILED fetch of the repository that is gone — and a strict branch
+    // listing inside its TTL refuses the new clone's refs as unproven.
+    await bootedOnTheOldRepository();
+    const replacement = await replacementUpstream();
+    const announced: string[] = [];
+
+    await makeRunner([touchDefault], {
+      kbRepoUrl: () => replacement,
+      onCloneCreated: (id: string) => announced.push(id),
+    }).runAll();
+
+    // Every working copy the phase made in place of one it set aside.
+    expect(announced).toContain(encodeURIComponent(DEFAULT_BRANCH));
+  });
+
+  it('says nothing about a working copy it keeps', async () => {
+    await bootedOnTheOldRepository();
+    const discarded: string[] = [];
+    await makeRunner([touchDefault], { onCloneDiscarded: (id: string) => discarded.push(id) }).runAll();
+    expect(discarded).toEqual([]);
+  });
+
   it('keeps every clone when the configured repository cannot be reached', async () => {
     // A typo in the address must not cost the working copies: the sweep runs
     // only once the configured remote has answered.

package/src/modules/workspace/startup/kb-startup-runner.ts

@@ -16,9 +16,11 @@ import {
   failureOf,
   gitFailure,
   type GitFailure,
+  type GitFailureKind,
 } from '../../../shared/git-failure.js';
 import { redactSecret, urlQuerySecrets } from '../../../shared/redact-secret.js';
 import { normalizeRepositoryAddress, sameRepository } from '../../kb-fs/remote-url.js';
+import { setAsideClone, setAsideRootFor, setAsideStamp } from '../set-aside-clone.js';
 
 /**
  * The KB startup phase: run every registered {@link OnServerStart} step, in
@@ -29,7 +31,9 @@ import { normalizeRepositoryAddress, sameRepository } from '../../kb-fs/remote-u
  *
  * Fully fail-closed: any failure this phase cannot DECLARE (an unhandled
  * step throw, an unreachable remote, a clone that will not come down, a
- * refused write) throws out of `runAll` and stops the boot. The container's
+ * refused write) throws out of `runAll`. The boot stops on it unless the
+ * host ANSWERED about the repository or the credentials, in which case it
+ * comes up gated instead — see `bootMaySurvive`. The container's
  * restart policy is the retry — each attempt at boot time on quiet trees —
  * so an environmental failure converges without a human the moment the
  * environment returns. The one carve-out: a push rejected because a
@@ -53,13 +57,12 @@ export interface KbStartupRunnerOptions {
   kbRepoUrl: () => string;
   workspacesRoot: string;
   /**
-   * Where a working copy of a repository that is no longer the configured
-   * one is moved to, under a folder named for the moment it happened — see
-   * `reconcileClonesWithConfiguredRepository`. NOT under `workspacesRoot`:
-   * the workspace service's orphan sweep removes every folder there that is
-   * not a known branch's, and what is set aside has to outlive that sweep.
-   * The composition root names a folder under the backups root, which is a
-   * persistent volume of its own. Default: a sibling of `workspacesRoot`.
+   * Where a working copy of a repository that is no longer the configured one
+   * is moved to, under a folder named for the moment it happened — see
+   * `reconcileClonesWithConfiguredRepository`. THE SAME VALUE THE WORKSPACE
+   * SERVICE IS GIVEN.
+   *
+   * Why, in one place: `setAsideRootFor` in `set-aside-clone.ts`.
    */
   setAsideRoot?: string;
   kbDirName: string;
@@ -78,6 +81,47 @@ export interface KbStartupRunnerOptions {
       template `.gitignore` rule can never silently drop a required seed file
       from the commit. */
   buildSeedTree: (dir: string) => Promise<string[]>;
+  /**
+   * Called with the workspace id of each working copy the phase is ABOUT TO
+   * set aside for being a clone of another repository, and awaited first.
+   * Whatever is still queued to be committed into that copy was written
+   * against the repository that was left, so it must be held back before a
+   * fresh clone of another repository appears at the same path.
+   *
+   * A PRECONDITION, so a failure here STOPS THE PHASE with the copy still
+   * where it was. Carrying on would clone the replacement with the queue
+   * untouched, and the worker would then commit those bytes into a
+   * repository they were never meant for. Stopped before anything moved, the
+   * next run finds the same copy and asks again. Optional: a minimal graph
+   * has no queue.
+   */
+  beforeCloneSetAside?: (workspaceId: string) => Promise<void>;
+  /**
+   * Called with the workspace id of each working copy the phase SET ASIDE for
+   * being a clone of another repository. The workspace service keeps a
+   * branch→directory cache and adopts whatever is on disk, so on a RUNNING
+   * server (the save that moves the deployment to another repository) the
+   * copy would otherwise stay in that cache as a path to nothing. Optional:
+   * at boot nothing has been cached yet.
+   *
+   * Never throws into the phase: a listener that fails must not stop a boot.
+   */
+  onCloneDiscarded?: (workspaceId: string) => void | Promise<void>;
+  /**
+   * Called with the workspace id of each working copy the phase CLONED fresh.
+   * A clone has just downloaded every ref, which is a successful fetch by any
+   * measure — but the git layer keeps its own per-workspace record of the last
+   * fetch and whether it worked, and the one that drove the replacement is a
+   * FAILED fetch of the repository that is gone. Left standing, a strict
+   * branch listing inside that record's TTL refuses the new clone's refs as
+   * unproven, having never touched it.
+   *
+   * The ordinary path already says this (`WorkspaceService`'s cloned
+   * listener); the phase clones with git directly, so it has to say it itself.
+   *
+   * Never throws into the phase, for the same reason as above.
+   */
+  onCloneCreated?: (workspaceId: string) => void;
 }
 
 /**
@@ -108,6 +152,42 @@ export class KbRemoteUnreachableError extends ClassifiedFailure {
   }
 }
 
+/**
+ * The failure kinds a boot may survive GATED rather than stop on: the remote
+ * ANSWERED (or could not be reached at all), and what it said is about the
+ * repository or the credentials — not about what this deployment would write.
+ *
+ * All four are fixed by an operator somewhere other than this process: the
+ * host comes back, the repository is created or the token is granted access
+ * to it, a rotated token is entered on the setup screen. Refusing to boot
+ * over any of them takes away the very screen the fix is entered on — which
+ * is what happened on 2026-09-28, when a replaced repository answered
+ * `not found` inside a step and the container crash-looped.
+ *
+ * Every OTHER failure still stops the boot: it means a step or the template
+ * would write something wrong, and booting over that is worse than not
+ * booting at all.
+ */
+const GATED_BOOT_KINDS: ReadonlySet<GitFailureKind> = new Set([
+  'unreachable',
+  'not-found',
+  'credentials-rejected',
+  'write-refused',
+]);
+
+/**
+ * Whether the boot may come up GATED on this failure instead of stopping.
+ *
+ * {@link KbRemoteUnreachableError} says so by its type — it is raised where
+ * the remote is first contacted, before any step. A failure raised INSIDE the
+ * phase says so by its classification: the same fetch that stops a boot when
+ * it is the first contact must not stop one when a step happened to make it.
+ */
+export function bootMaySurvive(err: unknown): boolean {
+  if (err instanceof KbRemoteUnreachableError) return true;
+  return err instanceof ClassifiedFailure && GATED_BOOT_KINDS.has(err.failure.kind);
+}
+
 export interface RetryOptions {
   /** First wait before trying again. Default 30s. */
   initialDelayMs?: number;
@@ -252,7 +332,7 @@ export class KbStartupRunner {
           // Stopped by either: a failure that is no longer the remote at all
           // (the knowledge base itself is wrong — asking again will not change
           // it), or a remote answer that a retry cannot change (see above).
-          if (!(err instanceof KbRemoteUnreachableError) || !worthRetrying()) return stopOnStanding();
+          if (!bootMaySurvive(err) || !worthRetrying()) return stopOnStanding();
           delay = Math.min(delay * 2, max);
           log(`remote still unreachable; trying again in ${Math.round(delay / 1000)}s`);
         }
@@ -561,9 +641,8 @@ export class KbStartupRunner {
       return; // no workspaces yet
     }
     // One folder per run, so what was set aside together stays together.
-    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-    const setAsideRoot =
-      this.opts.setAsideRoot ?? path.resolve(this.opts.workspacesRoot, '..', 'replaced-working-copies');
+    const stamp = setAsideStamp();
+    const setAsideRoot = setAsideRootFor(this.opts.workspacesRoot, this.opts.setAsideRoot);
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
       const repoDir = path.join(this.opts.workspacesRoot, entry.name, this.opts.kbDirName);
@@ -587,12 +666,25 @@ export class KbStartupRunner {
         continue;
       }
       const kept = path.join(setAsideRoot, stamp, entry.name);
-      await this.setAside(repoDir, kept);
+      // First, and allowed to stop the phase: see `beforeCloneSetAside`. The
+      // directory name IS the workspace id (`workspaceIdForBranch`).
+      await this.opts.beforeCloneSetAside?.(entry.name);
+      await setAsideClone(repoDir, kept);
       startupLog.warn(
         `working copy "${entry.name}" is a clone of another repository (${was}). Set aside at ${kept}; nothing was ` +
           'deleted, and it will be cloned fresh from the configured one. Work that was never pushed is in that ' +
           'folder: `git log` there shows it, and `git push <address> <branch>` from there sends it to a repository.',
       );
+      // Setting it aside already removed it from the workspaces root, so the
+      // cached handle the workspace service holds for it now points at
+      // nothing.
+      try {
+        await this.opts.onCloneDiscarded?.(entry.name);
+      } catch (err) {
+        startupLog.warn(`could not finish setting the working copy "${entry.name}" aside:`, {
+          detail: this.redact(err instanceof Error ? err.message : String(err)),
+        });
+      }
     }
   }
 
@@ -638,27 +730,6 @@ export class KbStartupRunner {
    * not (the backups root is a volume of its own in the shipped compose
    * files), with the original removed only once the copy is complete.
    */
-  private async setAside(repoDir: string, dest: string): Promise<void> {
-    await fs.mkdir(path.dirname(dest), { recursive: true });
-    try {
-      await fs.rename(repoDir, dest);
-      return;
-    } catch {
-      // Another volume, or a handle held open on it: copy instead.
-    }
-    try {
-      await fs.cp(repoDir, dest, { recursive: true, errorOnExist: true, force: false, verbatimSymlinks: true });
-    } catch (err) {
-      await fs.rm(dest, { recursive: true, force: true }).catch(() => undefined);
-      throw new Error(
-        `Could not set aside the working copy at ${repoDir}, a clone of a repository that is no longer the ` +
-          `configured one, into ${dest}: ${err instanceof Error ? err.message : String(err)}. Nothing was deleted. ` +
-          'Make room there, or move that folder away by hand, and start again.',
-        { cause: err },
-      );
-    }
-    await fs.rm(repoDir, { recursive: true, force: true });
-  }
 
   /**
    * The branch's working copy at the runtime layout
@@ -677,6 +748,16 @@ export class KbStartupRunner {
       await fs.mkdir(workspaceDir, { recursive: true });
       await fs.rm(repoDir, { recursive: true, force: true });
       await git(this.opts.gitRunner, workspaceDir, ['clone', '-b', branch, this.opts.kbRepoUrl(), repoDir]);
+      // Said as soon as the clone is there, before its configuration: if a
+      // command below fails, the clone stays on disk, and the retry finds it
+      // and never comes back through here.
+      try {
+        this.opts.onCloneCreated?.(workspaceIdForBranch(branch));
+      } catch (err) {
+        startupLog.warn(`could not announce the fresh working copy for "${branch}":`, {
+          detail: this.redact(err instanceof Error ? err.message : String(err)),
+        });
+      }
       await git(this.opts.gitRunner, repoDir, ['config', 'core.longpaths', 'true']);
       await stampIdentity(this.opts.gitRunner, repoDir);
       return repoDir;

package/src/modules/workspace/startup/steps/__tests__/steps.test.ts

@@ -18,12 +18,9 @@ import { mergeGroupsIntoRoles, parseRolesYaml } from '../../../../access-model/a
 import { TemplateFilesStep } from '../template-files.step.js';
 import { buildSeedTree } from '../seed-tree.js';
 import { defaultKbTemplateDir } from '../../../../../assets.js';
-import {
-  DEFAULT_KB_LAYOUT,
-  agentsFilePointerSentence,
-  renderKbLayoutPlaceholders,
-} from '@bevel-software/platform-shared';
-import { PLATFORM_HEADER, TOOL_PREFIX_LINE, composeAgentInstructions } from '../../../../agent-instructions/index.js';
+import { DEFAULT_KB_LAYOUT, agentsFilePointerSentence } from '@bevel-software/platform-shared';
+import { renderTemplateText } from '../template-source.js';
+import { TOOL_PREFIX_LINE, composeAgentInstructions, platformInstructions } from '../../../../agent-instructions/index.js';
 import { testKbContext } from '../../../../../__tests__/kb-context.js';
 
 const execFileAsync = promisify(execFile);
@@ -148,7 +145,10 @@ const PREAMBLE_IGNORE_BLOCK =
 
 /** The template as the step writes it under the default layout — placeholders rendered. */
 async function template(name: string): Promise<string> {
-  return renderKbLayoutPlaceholders(await fs.readFile(path.join(TEMPLATE_DIR, name), 'utf8'), DEFAULT_KB_LAYOUT);
+  // `renderTemplateText`, not the layout renderer alone: the managed guide also
+  // asks for the shared file rules, and a fixture rendered with half the
+  // placeholders filled would read as drifted on every boot.
+  return renderTemplateText(await fs.readFile(path.join(TEMPLATE_DIR, name), 'utf8'), DEFAULT_KB_LAYOUT);
 }
 
 /** Every required file + reserved root already present, from the real template. */
@@ -695,7 +695,7 @@ describe('TemplateFilesStep', () => {
     expect((await git(dir, ['rev-list', '--count', 'HEAD'])).trim()).toBe('1');
   });
 
-  it('ships a template that composes to the platform header alone: one comment, nothing broadcast', async () => {
+  it('ships a template that composes to the platform text alone: one comment, nothing broadcast', async () => {
     const shipped = await template('mcp-description.md');
     expect(shipped.trimStart().startsWith('<!--')).toBe(true);
     expect(shipped.trimEnd().endsWith('-->')).toBe(true);
@@ -705,7 +705,7 @@ describe('TemplateFilesStep', () => {
     expect(shipped).toContain('first paragraph under about 220');
     expect(shipped).not.toContain('{{');
     const composed = composeAgentInstructions(shipped);
-    expect(composed.instructions).toBe(PLATFORM_HEADER);
+    expect(composed.instructions).toBe(platformInstructions(DEFAULT_KB_LAYOUT));
     expect(composed.toolPrefix).toBe(TOOL_PREFIX_LINE);
     expect(composed.unterminatedComment).toBe(false);
     expect(composed.preambleChars).toBe(0);

package/src/modules/workspace/startup/steps/seed-tree.ts

@@ -1,14 +1,11 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import {
-  LEGACY_AGENTS_FILE,
-  renderKbLayoutPlaceholders,
-} from '@bevel-software/platform-shared';
+import { LEGACY_AGENTS_FILE } from '@bevel-software/platform-shared';
 import type { IFsProbe, ITreeWalker } from '../../../../shared/fs.contract.js';
 import type { KbContext } from '../../../../shared/kb-context.js';
 import { renderRolesYaml } from '../../../access-model/render-roles-yaml.js';
 import { reservedRootDirs } from './template-files.step.js';
-import { TEMPLATE_SOURCE_FALLBACKS, TemplateSource } from './template-source.js';
+import { TEMPLATE_SOURCE_FALLBACKS, TemplateSource, renderTemplateText } from './template-source.js';
 import { assertNotGitInternals, hasGitInternalsSegment } from '../../../../shared/git-internals.js';
 import { GitInternalsError } from '../../../../shared/domain-errors.js';
 
@@ -192,7 +189,7 @@ class KbSeedTree {
     if (text === null) {
       await fs.copyFile(from, to);
     } else {
-      await fs.writeFile(to, renderKbLayoutPlaceholders(text, this.kb.layout), 'utf8');
+      await fs.writeFile(to, renderTemplateText(text, this.kb.layout), 'utf8');
     }
     await fs.chmod(to, (await fs.stat(from)).mode & 0o777);
   }

package/src/modules/workspace/startup/steps/template-source.ts

@@ -1,8 +1,10 @@
 import path from 'node:path';
-import { gitignoreLiteral, renderKbLayoutPlaceholders } from '@bevel-software/platform-shared';
+import { gitignoreLiteral, renderKbLayoutPlaceholders, type KbLayout } from '@bevel-software/platform-shared';
 import { IGNORE_FILENAME, isAbsence, type EntryStat, type IFsProbe } from '../../../../shared/fs.contract.js';
 import type { KbContext } from '../../../../shared/kb-context.js';
+
 import { PREAMBLE_FILE } from '../../../agent-instructions/compose.js';
+import { sharedFileRulesSection } from '../../../agent-instructions/shared-file-rules.js';
 import { defaultKbTemplateDir } from '../../../../assets.js';
 import { logger } from '../../../../shared/logging.js';
 
@@ -37,6 +39,42 @@ export const TEMPLATE_SOURCE_FALLBACKS: ReadonlyMap<string, string> = new Map([
   ['.gitignore', 'gitignore.template'],
 ]);
 
+/**
+ * Where the managed guide asks for the rules every file tool shares. Not a
+ * layout placeholder: the layout renderer lives in `platform-shared`, which
+ * the frontend also reads, and the rules are backend text.
+ */
+export const SHARED_FILE_RULES_PLACEHOLDER = '{{sharedFileRules}}';
+
+/**
+ * Every placeholder a template file carries, filled: the layout's names on the
+ * text an author wrote, THEN the shared file rules dropped into the hole they
+ * left. ONE function, because the two writers of template content — the top-up
+ * step through {@link TemplateSource.read} and the empty-remote seeder, which
+ * streams files itself — must render identically or a freshly seeded knowledge
+ * base would carry a guide with a literal `{{sharedFileRules}}` in it.
+ *
+ * THAT ORDER, not the other one: the rules are already rendered for this
+ * layout (`sharedFileRulesSection` takes it), so running the layout renderer
+ * over them again would only reach text they STATE rather than contain — a
+ * folder a deployment really named `{{skillsDir}}` would come back as some
+ * other folder's name, and the rule would then point at a folder that is not
+ * the one it refuses a move out of. Injecting last leaves the section byte for
+ * byte what both channels carry, and costs nothing:
+ * `renderKbLayoutPlaceholders` touches only its own four tokens, so the
+ * placeholder for the rules survives the first pass untouched.
+ *
+ * A replacer FUNCTION for the rules: they carry dollar sequences (a `${VAR}`
+ * a template writes) that a string replacement would read as capture-group
+ * syntax.
+ */
+export function renderTemplateText(text: string, layout: KbLayout): string {
+  return renderKbLayoutPlaceholders(text, layout).replaceAll(
+    SHARED_FILE_RULES_PLACEHOLDER,
+    () => sharedFileRulesSection(layout),
+  );
+}
+
 /**
  * ONE template directory, read through ONE disk port — what both readers of
  * the KB template share.
@@ -112,6 +150,16 @@ export class TemplateSource {
    * placeholders the template carries (`{{pluginsDir}}` …) are filled with
    * the names in effect. Every required file is text; a template without
    * placeholders passes through unchanged.
+   *
+   * `{{sharedFileRules}}` is filled from the ONE source text the MCP handshake
+   * also sends (see `shared-file-rules.ts`), so the rules every file tool
+   * shares are stated in the guide and in the instructions without being
+   * written twice. Filled AFTER the layout pass (see
+   * {@link renderTemplateText}): the rules come back already rendered for this
+   * layout, so a layout pass over them could only misread a name they STATE as
+   * a placeholder. The two passes do not collide — the layout renderer touches
+   * only its own four tokens, so `{{sharedFileRules}}` reaches the second pass
+   * untouched.
    */
   async read(relPath: string): Promise<string> {
     let raw: string;
@@ -134,13 +182,13 @@ export class TemplateSource {
     // reads as syntax (`#Guide.md`, `!Guide.md`, brackets) would hide nothing
     // written bare. Escaped there, and only there: everywhere else the
     // placeholder is prose. ONE render, with the escaped name as the layout's
-    // — a second pass over the rendered text would read a name that happens
-    // to contain a placeholder as one.
+    // — rendering twice over text already rendered would read a name that
+    // happens to contain a placeholder as one.
     const layout = this.kb.layout;
     if (relPath === IGNORE_FILENAME) {
-      return renderKbLayoutPlaceholders(raw, { ...layout, agentsFile: gitignoreLiteral(layout.agentsFile) });
+      return renderTemplateText(raw, { ...layout, agentsFile: gitignoreLiteral(layout.agentsFile) });
     }
-    return renderKbLayoutPlaceholders(raw, layout);
+    return renderTemplateText(raw, layout);
   }
 
   /**

package/src/modules/workspace/upload-limits.ts

@@ -0,0 +1,12 @@
+/**
+ * The deployment's own upload ceiling, in bytes.
+ *
+ * ONE number for every surface that accepts bytes: the app's
+ * `POST /workspace/:id/upload` (a person dropping a file in the explorer) and
+ * the agent upload route (`POST /agent/uploads/:token`). They used to be the
+ * same number written twice, which is the shape a limit drifts in — an agent
+ * refused at 50 MB by one route and accepted by the other would have no way to
+ * read which limit applied. The refusal NAMES this value, so a caller can size
+ * its next attempt from the answer rather than by bisection.
+ */
+export const MAX_UPLOAD_BYTES = 50 * 1024 * 1024; // 50 MB