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

package/src/modules/workspace/agent-access.gate.ts

@@ -0,0 +1,164 @@
+/**
+ * Agent access gate — the per-call seam every gated agent tool runs through.
+ *
+ * It decides nothing of its own. It calls the hooks a DEPLOYMENT registered
+ * (`WorkflowHooks`): one before an agent read of a knowledge-base path, one
+ * before an agent write. A hook that throws refuses the operation and the
+ * caller sees that hook's own message and status. With no hook registered —
+ * every core-only deployment — nothing is refused and nothing is recorded, and
+ * a call that carries no `sessionId` is an ordinary call.
+ *
+ * The gate owns exactly two skips, and they are the ones core can decide on
+ * its own identity model: the caller is not an agent (a person in the app, a
+ * browser JWT), or the caller is the recovery/merge bot. Everything else —
+ * which paths matter, whether a session id is required, what the refusal says
+ * — belongs to the hook.
+ *
+ * Lives beside `assertCanRead` in the workspace tools; it does NOT touch
+ * `acquireLock` (that gate is protected-branch-only, and this one applies on
+ * all branches and to reads).
+ */
+
+import type { JsonSchema } from '../tool-registry/tool.contract.js';
+import type { ToolContext } from '../tool-helpers/tool.contract.js';
+import type { WorkflowHooks } from '../workflow/workflow-hooks.js';
+
+/**
+ * What the `sessionId` input says on its own, before any deployment note. The
+ * id is the CONVERSATION's id: the in-process agent supplies its thread id
+ * automatically (via its per-run internal token), and an external agent mints
+ * one with `start_session` and passes it explicitly, because the MCP proxy is
+ * a pure passthrough and never injects args. The same id is the one `ask`
+ * takes, so a run's reads and its questions share one conversation.
+ */
+export const SESSION_ID_DESCRIPTION =
+  "This conversation's id, so the server can tell one run's calls apart. External agents (direct MCP calls and `call_tool_chain` alike): call the `start_session` tool ONCE at the very start of your work to obtain it, then pass that id here — the same id `ask` takes. The in-process agent runtime supplies this automatically (do not set it yourself).";
+
+/**
+ * The `sessionId` input every gated tool declares. The description a MOUNTED
+ * tool ends up advertising is {@link ToolDescriptionNotes.sessionIdDescription},
+ * which appends whatever note the deployment registered; this constant is the
+ * unadorned default the notes are applied on top of.
+ */
+export const SESSION_ID_INPUT: JsonSchema = {
+  type: 'string',
+  description: SESSION_ID_DESCRIPTION,
+};
+
+/**
+ * The registration point for the wording a DEPLOYMENT wants agents to read
+ * about the gated tools — the counterpart of the hooks, which carry its rule.
+ * A deployment that refuses some calls can say so here; core registers
+ * nothing, so a core-only deployment advertises the plain descriptions.
+ *
+ * Registration may land AFTER the tools are mounted (an overlay registers from
+ * the tool-surface hook), so mounted tools subscribe with {@link onChange} and
+ * rewrite their own description and `sessionId` input when a note arrives.
+ */
+export class ToolDescriptionNotes {
+  private gatedTool = '';
+  private sessionId = '';
+  private readonly listeners = new Set<() => void>();
+
+  /** Append `note` to the description of every gated tool. */
+  registerGatedToolNote(note: string): void {
+    this.gatedTool = note;
+    this.announce();
+  }
+
+  /** Append `note` to the description of the `sessionId` input. */
+  registerSessionIdNote(note: string): void {
+    this.sessionId = note;
+    this.announce();
+  }
+
+  /** The registered gated-tool note, `''` when none is registered. */
+  gatedToolNote(): string {
+    return this.gatedTool;
+  }
+
+  /** The `sessionId` input's description, with any registered note appended. */
+  sessionIdDescription(): string {
+    return SESSION_ID_DESCRIPTION + this.sessionId;
+  }
+
+  /** Re-run `listener` whenever a note is registered (mounted tools re-describe). */
+  onChange(listener: () => void): void {
+    this.listeners.add(listener);
+  }
+
+  private announce(): void {
+    for (const listener of this.listeners) listener();
+  }
+}
+
+/** The per-deployment configuration the gate needs, built once in the composition root. */
+export interface AgentAccessGate {
+  /** Lowercased email of the recovery/merge bot, which never reaches the hooks. */
+  recoveryBotEmail: string;
+  /**
+   * The workflow lifecycle-hook registry holding the BLOCKING `agentRead` and
+   * `preWrite` hooks. Core registers none; a deployment registers against
+   * `workflowService.hooks` — pass that same instance here.
+   */
+  hooks: WorkflowHooks;
+  /** The notes a deployment adds to what agents read about these tools. */
+  notes: ToolDescriptionNotes;
+}
+
+/** Only agent callers are gated; `session` (browser JWT) and humans are not. */
+function agentSourceOf(ctx: ToolContext): 'internal' | 'external' | null {
+  return ctx.source === 'internal' || ctx.source === 'external' ? ctx.source : null;
+}
+
+/**
+ * The hook context for this call, or `null` when the call never reaches a hook:
+ * the caller is a person rather than an agent, or is the recovery/merge bot,
+ * which legitimately spans everything.
+ */
+function operationContext(
+  gate: AgentAccessGate,
+  ctx: ToolContext,
+  branch: string,
+  wsPath?: string,
+): { sessionId?: string; wsPath?: string; branch: string; user: ToolContext['user']; source: 'internal' | 'external' } | null {
+  const source = agentSourceOf(ctx);
+  if (source === null) return null;
+  if (ctx.user.email.toLowerCase() === gate.recoveryBotEmail) return null;
+  return { sessionId: ctx.sessionId, wsPath, branch, user: ctx.user, source };
+}
+
+/**
+ * Tell the registered read hooks about an agent read of `wsPath`. A hook that
+ * throws refuses the read with its own message and status; with none
+ * registered this is a no-op.
+ */
+export async function notifyAgentRead(
+  gate: AgentAccessGate,
+  ctx: ToolContext,
+  branch: string,
+  wsPath: string,
+): Promise<void> {
+  const op = operationContext(gate, ctx, branch, wsPath);
+  if (op === null) return;
+  await gate.hooks.runAgentRead(op);
+}
+
+/**
+ * Ask the registered write hooks whether an agent write may proceed. A hook
+ * that throws refuses it with its own message and status; with none registered
+ * this is a no-op.
+ *
+ * `wsPath` is omitted by the one write-capable tool with no resolvable target,
+ * `execute_command` — the hook then decides at the coarser session level.
+ */
+export async function assertAgentWriteAllowed(
+  gate: AgentAccessGate,
+  ctx: ToolContext,
+  branch: string,
+  wsPath?: string,
+): Promise<void> {
+  const op = operationContext(gate, ctx, branch, wsPath);
+  if (op === null) return;
+  await gate.hooks.runPreWrite(op);
+}

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;