@bevel-software/platform-core-backend 0.21.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

@@ -79,6 +79,7 @@ function runnerOpts(steps: OnServerStart[], overrides: Record<string, unknown> =
     gitRunner: new NodeGitRunner(undefined, credentials),
     kbRepoUrl: () => upstream,
     workspacesRoot,
+    setAsideRoot: path.join(root, 'set-aside'),
     kbDirName: 'knowledge-base',
     templateDir: path.join(root, 'template'),
     defaultBranch: () => DEFAULT_BRANCH,
@@ -103,6 +104,302 @@ async function checkout(branch: string): Promise<string> {
   return dir;
 }
 
+/**
+ * The configured repository was replaced while working copies of the old one
+ * were still on disk. A clone fetches through its OWN stored address, so
+ * every one of them kept asking the repository that was gone: the boot
+ * stopped on "repository not found" and took the setup screen with it.
+ */
+describe('KbStartupRunner — the repository was replaced', () => {
+  const touchDefault = step('touch', async (ctx) => {
+    await (await ctx.defaultBranch()).repoDir();
+    return { outcome: 'ok' };
+  });
+  const cloneDir = (branch: string) => path.join(workspacesRoot, encodeURIComponent(branch), 'knowledge-base');
+
+  /** A second, unrelated repository with the same branch names. */
+  async function replacementUpstream(): Promise<string> {
+    const other = path.join(root, 'replacement.git');
+    await git(root, ['init', '--bare', '-b', DEFAULT_BRANCH, other]);
+    const seed = path.join(root, '.seed-replacement');
+    await fs.mkdir(seed);
+    await git(seed, ['init', '-b', DEFAULT_BRANCH]);
+    await fs.writeFile(path.join(seed, 'marker.txt'), 'replacement', 'utf8');
+    await git(seed, ['add', '-A']);
+    await git(seed, ['commit', '-m', 'init']);
+    await git(seed, ['branch', PROTECTED[1]!]);
+    await git(seed, ['remote', 'add', 'origin', other]);
+    await git(seed, ['push', 'origin', ...PROTECTED]);
+    return other;
+  }
+
+  /** Boot once against the first repository, and leave a draft's clone beside it. */
+  async function bootedOnTheOldRepository(): Promise<void> {
+    await populatedUpstream();
+    await makeRunner([touchDefault]).runAll();
+    await fs.mkdir(path.dirname(cloneDir('someone/draft')), { recursive: true });
+    await git(root, ['clone', '-b', DEFAULT_BRANCH, upstream, cloneDir('someone/draft')]);
+  }
+
+  /** Where one run set its working copies aside: the single dated folder under the root. */
+  async function setAside(): Promise<string> {
+    const runs = await fs.readdir(path.join(root, 'set-aside'));
+    expect(runs).toHaveLength(1);
+    return path.join(root, 'set-aside', runs[0]!);
+  }
+
+  it('clones the new repository in place of the old one\'s clones, even with the old one gone', async () => {
+    await bootedOnTheOldRepository();
+    const replacement = await replacementUpstream();
+    // Gone, as it was in production: any fetch through the old address fails.
+    await fs.rm(upstream, { recursive: true, force: true });
+
+    await makeRunner([touchDefault], { kbRepoUrl: () => replacement }).runAll();
+
+    const repo = cloneDir(DEFAULT_BRANCH);
+    expect((await git(repo, ['config', '--get', 'remote.origin.url'])).trim()).toBe(replacement);
+    expect(await fs.readFile(path.join(repo, 'marker.txt'), 'utf8')).toBe('replacement');
+    // A clone this boot had no reason to touch leaves the workspaces root
+    // too: the workspace service would otherwise adopt it and fetch from the
+    // old address.
+    await expect(fs.access(cloneDir('someone/draft'))).rejects.toThrow();
+  });
+
+  /**
+   * The old repository is GONE, so its clones are the last copy of what it
+   * held, and the commit nobody pushed exists nowhere else at all. They
+   * leave the workspaces root and nothing else happens to them.
+   */
+  it('sets the old repository\'s clones aside whole, unpushed work included, and deletes nothing', async () => {
+    await bootedOnTheOldRepository();
+    const old = cloneDir(DEFAULT_BRANCH);
+    await fs.writeFile(path.join(old, 'unpushed.md'), 'the only copy', 'utf8');
+    await git(old, ['add', '-A']);
+    await git(old, ['commit', '-m', 'never pushed']);
+    const head = (await git(old, ['rev-parse', 'HEAD'])).trim();
+    const replacement = await replacementUpstream();
+    await fs.rm(upstream, { recursive: true, force: true });
+
+    await makeRunner([touchDefault], { kbRepoUrl: () => replacement }).runAll();
+
+    const kept = await setAside();
+    const keptDefault = path.join(kept, encodeURIComponent(DEFAULT_BRANCH));
+    expect((await git(keptDefault, ['rev-parse', 'HEAD'])).trim()).toBe(head);
+    expect(await fs.readFile(path.join(keptDefault, 'unpushed.md'), 'utf8')).toBe('the only copy');
+    expect(await fs.readFile(path.join(keptDefault, 'marker.txt'), 'utf8')).toBe('seeded');
+    // The draft's clone too, under its own workspace's name.
+    await expect(fs.access(path.join(kept, encodeURIComponent('someone/draft'), '.git'))).resolves.toBeUndefined();
+    // And the probe that compared the histories left no refs behind in it.
+    expect((await git(keptDefault, ['for-each-ref', 'refs/hexis-probe/'])).trim()).toBe('');
+  });
+
+  /**
+   * The shipped compose files mount the backups root as a volume of its own,
+   * where a rename across to it is refused. That is the path production
+   * takes: a copy, and the original removed only once the copy is whole.
+   */
+  it('sets a clone aside across volumes, by copying it whole', async () => {
+    await bootedOnTheOldRepository();
+    const old = cloneDir(DEFAULT_BRANCH);
+    await fs.writeFile(path.join(old, 'unpushed.md'), 'the only copy', 'utf8');
+    await git(old, ['add', '-A']);
+    await git(old, ['commit', '-m', 'never pushed']);
+    const head = (await git(old, ['rev-parse', 'HEAD'])).trim();
+    const replacement = await replacementUpstream();
+    await fs.rm(upstream, { recursive: true, force: true });
+    const crossDevice = Object.assign(new Error('EXDEV: cross-device link not permitted'), { code: 'EXDEV' });
+    const rename = vi.spyOn(fs, 'rename').mockRejectedValue(crossDevice);
+    try {
+      await makeRunner([touchDefault], { kbRepoUrl: () => replacement }).runAll();
+    } finally {
+      rename.mockRestore();
+    }
+
+    const keptDefault = path.join(await setAside(), encodeURIComponent(DEFAULT_BRANCH));
+    expect((await git(keptDefault, ['rev-parse', 'HEAD'])).trim()).toBe(head);
+    expect(await fs.readFile(path.join(keptDefault, 'unpushed.md'), 'utf8')).toBe('the only copy');
+    expect(await fs.readFile(path.join(cloneDir(DEFAULT_BRANCH), 'marker.txt'), 'utf8')).toBe('replacement');
+  });
+
+  /**
+   * A clone that cannot be set aside stays exactly where it is, and the boot
+   * stops saying why: deleting it to get past would be the one outcome this
+   * whole path exists to rule out.
+   */
+  it('deletes nothing when a clone cannot be set aside, and says why', async () => {
+    await bootedOnTheOldRepository();
+    const old = cloneDir(DEFAULT_BRANCH);
+    const head = (await git(old, ['rev-parse', 'HEAD'])).trim();
+    const replacement = await replacementUpstream();
+    await fs.rm(upstream, { recursive: true, force: true });
+    const rename = vi.spyOn(fs, 'rename').mockRejectedValue(Object.assign(new Error('EXDEV'), { code: 'EXDEV' }));
+    const cp = vi.spyOn(fs, 'cp').mockRejectedValue(Object.assign(new Error('ENOSPC: no space left on device'), { code: 'ENOSPC' }));
+    try {
+      await expect(makeRunner([touchDefault], { kbRepoUrl: () => replacement }).runAll()).rejects.toThrow(
+        /Could not set aside the working copy.*no space left.*Nothing was deleted/s,
+      );
+    } finally {
+      rename.mockRestore();
+      cp.mockRestore();
+    }
+    expect((await git(old, ['rev-parse', 'HEAD'])).trim()).toBe(head);
+  });
+
+  /**
+   * The one change the setup screen tells an admin to make: the same
+   * repository, moved. The clone is pointed at the new address and kept, and
+   * the commit that was never pushed goes on to be pushed there.
+   */
+  it('keeps a clone of the same repository at a new address, and points it there', async () => {
+    await bootedOnTheOldRepository();
+    const repo = cloneDir(DEFAULT_BRANCH);
+    await fs.writeFile(path.join(repo, 'unpushed.md'), 'local work', 'utf8');
+    await git(repo, ['add', '-A']);
+    await git(repo, ['commit', '-m', 'local work']);
+    const head = (await git(repo, ['rev-parse', 'HEAD'])).trim();
+    // Moved: everything the old address held is at the new one, and the old
+    // one answers nothing any more.
+    const moved = path.join(root, 'moved.git');
+    await git(root, ['clone', '--bare', upstream, moved]);
+    await fs.rm(upstream, { recursive: true, force: true });
+
+    await makeRunner([touchDefault], { kbRepoUrl: () => moved }).runAll();
+
+    expect((await git(repo, ['config', '--get', 'remote.origin.url'])).trim()).toBe(moved);
+    expect((await git(repo, ['rev-parse', 'HEAD'])).trim()).toBe(head);
+    expect((await git(cloneDir('someone/draft'), ['config', '--get', 'remote.origin.url'])).trim()).toBe(moved);
+    expect((await git(repo, ['for-each-ref', 'refs/hexis-probe/'])).trim()).toBe('');
+    // Nothing was another repository's, so nothing was set aside.
+    await expect(fs.access(path.join(root, 'set-aside'))).rejects.toThrow();
+  });
+
+  it('leaves a clone of the configured repository alone, unpushed work included', async () => {
+    await bootedOnTheOldRepository();
+    const repo = cloneDir(DEFAULT_BRANCH);
+    await fs.writeFile(path.join(repo, 'unpushed.md'), 'local work', 'utf8');
+    await git(repo, ['add', '-A']);
+    await git(repo, ['commit', '-m', 'local work']);
+    const head = (await git(repo, ['rev-parse', 'HEAD'])).trim();
+
+    await makeRunner([touchDefault]).runAll();
+
+    expect((await git(repo, ['rev-parse', 'HEAD'])).trim()).toBe(head);
+    await expect(fs.access(cloneDir('someone/draft'))).resolves.toBeUndefined();
+  });
+
+  it('does not take a different spelling of the same address for another repository', async () => {
+    await bootedOnTheOldRepository();
+    const repo = cloneDir(DEFAULT_BRANCH);
+    await fs.writeFile(path.join(repo, 'unpushed.md'), 'local work', 'utf8');
+    await git(repo, ['add', '-A']);
+    await git(repo, ['commit', '-m', 'local work']);
+    const head = (await git(repo, ['rev-parse', 'HEAD'])).trim();
+
+    // `upstream` ends in `.git`; the same repository without it, and with a
+    // trailing slash.
+    await makeRunner([touchDefault], { kbRepoUrl: () => `${upstream.replace(/\.git$/, '')}/` }).runAll().catch(() => {});
+
+    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.
+    await bootedOnTheOldRepository();
+    await expect(
+      makeRunner([touchDefault], { kbRepoUrl: () => path.join(root, 'no-such-repository.git') }).runAll(),
+    ).rejects.toThrow();
+    await expect(fs.access(path.join(cloneDir(DEFAULT_BRANCH), '.git'))).resolves.toBeUndefined();
+    await expect(fs.access(cloneDir('someone/draft'))).resolves.toBeUndefined();
+  });
+});
+
 describe('KbStartupRunner', () => {
   it('seeds an empty remote with every protected branch before any step runs', async () => {
     const seen: string[] = [];