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

package/src/modules/workspace/__tests__/workspace.tools.branch-errors.test.ts

@@ -1,11 +1,15 @@
 import type { Server as HttpServer } from 'node:http';
 import { execFile } from 'node:child_process';
-import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { mkdir, mkdtemp, readdir, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
 import express from 'express';
 import { afterEach, describe, expect, it } from 'vitest';
+import '@utcp/http'; // registers the http CallTemplate serializer + protocol
+import { UtcpManualSerializer } from '@utcp/sdk';
+import { HttpCallTemplateSerializer } from '@utcp/http';
+import { CodeModeUtcpClient } from '../../code-mode/index.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
@@ -86,7 +90,12 @@ describe('workspace tools — a branch that cannot be opened', () => {
    * real tool-context resolver — so a tool call clones (or fails to clone)
    * exactly as it does in production.
    */
-  async function start(opts: { repoUrl?: 'origin' | 'unreachable' } = {}): Promise<string> {
+  /** The tool defs the mounted registry serves, kept for the sweep below. */
+  let internalTools: { name: string; inputs: unknown }[] = [];
+
+  async function start(
+    opts: { repoUrl?: 'origin' | 'unreachable'; scope?: 'read' | 'write'; source?: 'internal' | 'external' } = {},
+  ): Promise<string> {
     root = await mkdtemp(join(tmpdir(), 'ws-tools-branch-'));
     spillRoot = await mkdtemp(join(tmpdir(), 'ws-tools-spill-'));
     docCacheDir = await mkdtemp(join(tmpdir(), 'ws-tools-doc-'));
@@ -128,11 +137,33 @@ describe('workspace tools — a branch that cannot be opened', () => {
     const app = express();
     app.use(express.json());
     const router = express.Router();
+    const registry = new ToolRegistry();
+    // The internal discovery endpoint, exactly as `manual.routes` serves it —
+    // what a real `CodeModeUtcpClient` reads to learn the tools it can call
+    // from inside a chain. Served here so the chain test below drives the SAME
+    // routes as every direct call in this file.
+    router.get('/agent/internal/utcp', async (_req, res) => {
+      res.json(
+        new UtcpManualSerializer().validateDict({
+          utcp_version: '1.1.0',
+          manual_version: '1.0.0',
+          tools: await registry.listInternal(),
+        }),
+      );
+    });
     registerWorkspaceTools(
-      new ToolRegistry(),
+      registry,
       router,
       (req: express.Request, _res: express.Response, next: express.NextFunction) => {
-        req.toolAuth = { source: 'external', userId: 'u', scope: 'read' } as ToolAuth;
+        req.toolAuth = {
+          // The sweep below asks for `internal` + `write`, which is what reaches
+          // the internal-only tools and gets past the write-scope refusal that
+          // sits in FRONT of every handler. Everything else in this file stays
+          // on the external read surface the bug was reported from.
+          source: opts.source ?? 'external',
+          userId: 'u',
+          scope: opts.scope ?? 'read',
+        } as ToolAuth;
         next();
       },
       createToolHandlerFactory(resolve),
@@ -151,21 +182,34 @@ describe('workspace tools — a branch that cannot be opened', () => {
       {} as never,
     );
     app.use('/api', router);
+    internalTools = (await registry.listInternal()) as unknown as { name: string; inputs: unknown }[];
     httpServer = await new Promise<HttpServer>((r) => {
       const s = app.listen(0, () => r(s));
     });
     return `http://127.0.0.1:${(httpServer.address() as { port: number }).port}`;
   }
 
-  const listFiles = async (base: string, branch: string): Promise<{ status: number; body: Record<string, unknown> }> => {
-    const res = await fetch(`${base}/api/agent/tools/list_files`, {
+  /** Call a tool with an arbitrary body — including one that omits `branch`. */
+  const callTool = async (
+    base: string,
+    tool: string,
+    body: unknown,
+  ): Promise<{ status: number; body: Record<string, unknown> }> => {
+    const res = await fetch(`${base}/api/agent/tools/${tool}`, {
       method: 'POST',
       headers: { 'content-type': 'application/json', authorization: 'Bearer x' },
-      body: JSON.stringify({ branch, path: '' }),
+      body: JSON.stringify(body),
     });
     return { status: res.status, body: (await res.json()) as Record<string, unknown> };
   };
 
+  const listFiles = async (base: string, branch: string): Promise<{ status: number; body: Record<string, unknown> }> =>
+    callTool(base, 'list_files', { branch, path: '' });
+
+  /** Every entry currently under the workspaces root. */
+  const workspaceDirs = async (): Promise<string[]> =>
+    (await readdir(join(root, 'workspaces'))).sort();
+
   const deleteOnHost = (branch: string): Promise<void> =>
     runGit(join(root, 'upstream.git'), ['branch', '-D', branch]);
 
@@ -182,6 +226,188 @@ describe('workspace tools — a branch that cannot be opened', () => {
     });
   });
 
+  /**
+   * The reported bug, from the outside: every tool call made without a
+   * `branch` answered `Branch "undefined" no longer exists on the remote.` —
+   * the missing input was carried all the way down, turned into a workspace
+   * directory named `undefined`, and the failed clone of that "branch" was
+   * then explained as a branch that had been deleted.
+   *
+   * The input is refused BY NAME instead, at the boundary, before any of that
+   * can happen. `list_files` stands in for every knowledge-base tool here
+   * because they share the one choke point (`getFilesystem`) — the refusal is
+   * the context resolver's, not this tool's.
+   */
+  describe('a call that names no branch', () => {
+    // Every shape of "the caller sent no branch". The literals are in here
+    // because a client that interpolates a variable it never set sends the
+    // STRING "undefined" — indistinguishable, in intent, from omitting it, and
+    // the one value that must never reach a clone.
+    const absent: Array<[label: string, body: Record<string, unknown>]> = [
+      ['the field is missing entirely', { path: '' }],
+      ['the field is empty', { branch: '', path: '' }],
+      ['the field is null', { branch: null, path: '' }],
+      ['the field is a number', { branch: 42, path: '' }],
+      ['the field is an object', { branch: { name: 'main' }, path: '' }],
+      ['the field is an array', { branch: ['main'], path: '' }],
+      ['the field is the literal "undefined"', { branch: 'undefined', path: '' }],
+      ['the field is the literal "null"', { branch: 'null', path: '' }],
+    ];
+
+    for (const [label, body] of absent) {
+      it(`400s branch-required when ${label}`, async () => {
+        const base = await start();
+
+        const res = await callTool(base, 'list_files', body);
+
+        expect(res.status).toBe(400);
+        expect(res.body).toEqual({
+          kind: 'branch-required',
+          error: '`branch` is required: pass the branch (draft) you are working on.',
+        });
+        // The refusal is the whole story: nothing was created and nothing was
+        // cloned. An empty workspaces root is the strongest form of that
+        // claim — there is no directory named for any branch, least of all one
+        // named `undefined`.
+        expect(await workspaceDirs()).toEqual([]);
+      });
+    }
+
+    it('never writes `undefined` or `null` as a branch name into the answer', async () => {
+      const base = await start();
+
+      const res = await callTool(base, 'list_files', { path: '' });
+
+      // AC3, checked against the whole response rather than one field: the
+      // message names the INPUT and what to pass, never a stringified value of
+      // what was missing. `Branch "undefined" no longer exists` is exactly the
+      // sentence this must never produce again.
+      const serialized = JSON.stringify(res.body);
+      expect(serialized).not.toContain('undefined');
+      expect(serialized).not.toContain('null');
+    });
+
+    /**
+     * `call_tool_chain` is the other way every one of these tools gets called,
+     * and it is where the bug was reported from just as often. It is not a
+     * second implementation to guard: the chain's UTCP http transport POSTs to
+     * the SAME `/agent/tools/...` route this file has been calling directly, so
+     * the one refusal covers both. This test is what proves that claim rather
+     * than assuming it — with a real `CodeModeUtcpClient` reading a real
+     * manual and running real JavaScript.
+     */
+    it('400s branch-required from inside call_tool_chain, and creates no workspace', async () => {
+      const base = await start();
+      const client = await CodeModeUtcpClient.create(process.cwd(), {
+        variables: { bevel_API_URL: base, bevel_CONNECTION_KEY: 'internal-token' },
+      } as never);
+      await client.registerManual(
+        new HttpCallTemplateSerializer().validateDict({
+          name: 'bevel',
+          call_template_type: 'http',
+          http_method: 'GET',
+          url: '${API_URL}/api/agent/internal/utcp',
+          content_type: 'application/json',
+          headers: { Authorization: 'Bearer ${CONNECTION_KEY}' },
+        }),
+      );
+
+      // The exact call from the specification: a chain that names the path and
+      // forgets the branch. The tool THROWS inside the chain, so the failure is
+      // caught and its message returned — the runtime's own contract for
+      // surfacing a tool error to the model.
+      const { result } = await client.callToolChain(
+        `try { return { ok: bevel.list_files({ body: { path: 'knowledge-base' } }) }; }
+         catch (err) { return { failed: err.message }; }`,
+        30_000,
+      );
+
+      // The tool did not run.
+      expect(result.ok).toBeUndefined();
+      // The message the chain hands the model carries the whole refusal: the
+      // status, the sentence, and the `kind` the direct caller switches on.
+      // (The status and payload are IN the message rather than on the thrown
+      // object — the sandboxed error exposes no own properties — which is why
+      // this asserts on the text the model actually reads.)
+      expect(result.failed).toContain('HTTP 400');
+      expect(result.failed).toContain('`branch` is required: pass the branch (draft) you are working on.');
+      expect(result.failed).toContain('"kind":"branch-required"');
+      // Not the sentence the bug produced — and no invented branch name in it.
+      expect(result.failed).not.toContain('no longer exists');
+      expect(result.failed).not.toContain('undefined');
+      // And the chain path refuses just as early: nothing was cloned.
+      expect(await workspaceDirs()).toEqual([]);
+    });
+
+    /**
+     * AC1 says "any knowledge-base tool", so this asserts it of EVERY tool the
+     * module mounts rather than of the one this file otherwise drives. The list
+     * comes from the registry, so a tool added later is swept in automatically
+     * and cannot quietly reintroduce the bug on its own route. The guard runs
+     * ahead of every other check, which is what lets one empty body stand in
+     * for a valid call to each of them.
+     */
+    it('400s branch-required on every mounted tool that declares `branch`', async () => {
+      const base = await start({ source: 'internal', scope: 'write' });
+      const declaresBranch = internalTools
+        .filter((t) => {
+          const body = (t.inputs as { properties?: { body?: { required?: string[] } } }).properties?.body;
+          return (body?.required ?? []).includes('branch');
+        })
+        .map((t) => t.name);
+
+      // The whole branch-taking surface, not a sample of it.
+      expect(declaresBranch.length).toBeGreaterThan(10);
+
+      for (const tool of declaresBranch) {
+        const res = await callTool(base, tool, {});
+        expect(res.status, `${tool} must 400 on a branch-less call`).toBe(400);
+        expect(res.body.kind, `${tool} must answer kind branch-required`).toBe('branch-required');
+        // No tool's refusal may name the value it did not get.
+        expect(JSON.stringify(res.body), `${tool} must not echo an absent value`).not.toContain('undefined');
+      }
+      expect(await workspaceDirs()).toEqual([]);
+    });
+
+    it('still serves the same tool once a branch is named', async () => {
+      const base = await start();
+      // The guard refuses an absent input, not the tool: the same call with a
+      // real branch works, so the refusal cannot be a tool that simply broke.
+      expect((await callTool(base, 'list_files', { path: '' })).status).toBe(400);
+
+      const { status, body } = await listFiles(base, 'alice/draft');
+
+      expect(status).toBe(200);
+      expect((body.entries as { name: string }[]).map((e) => e.name)).toContain(KB_DIR);
+    });
+  });
+
+  /**
+   * The second half of the bug: a bootstrap that failed to clone used to leave
+   * a directory behind, and a directory named after a branch is how the
+   * platform remembers having known one. The first attempt's leftovers turned
+   * the second attempt's honest "no such branch" into "it was deleted".
+   */
+  it('answers 404 again on a second attempt at a name that never existed', async () => {
+    const base = await start();
+
+    const first = await listFiles(base, 'nobody/never-made-this');
+    expect(first.status).toBe(404);
+    // Nothing survived the failed clone — not the repo directory, not the
+    // workspace shell around it. This is what keeps the next attempt honest.
+    expect(await workspaceDirs()).toEqual([]);
+
+    const second = await listFiles(base, 'nobody/never-made-this');
+
+    expect(second.status).toBe(404);
+    expect(second.body).toEqual({
+      kind: 'branch-not-found',
+      branch: 'nobody/never-made-this',
+      error: 'There is no branch named nobody/never-made-this.',
+    });
+    expect(await workspaceDirs()).toEqual([]);
+  });
+
   it('410s a branch a listing showed us and origin no longer has', async () => {
     const base = await start();
     workspaces!.noteBranchesListed(['target-company-state', 'alice/draft']);

package/src/modules/workspace/__tests__/workspace.tools.test.ts

@@ -233,9 +233,24 @@ async function start(
   return `http://127.0.0.1:${(httpServer.address() as { port: number }).port}`;
 }
 
-const post = (url: string, body: unknown = {}) =>
+/** POST a body EXACTLY as given — for the tests about a malformed call. */
+const postRaw = (url: string, body: unknown = {}) =>
   fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', authorization: 'Bearer x' }, body: JSON.stringify(body) });
 
+/**
+ * POST a well-formed call. Every KB tool requires `branch` — a call that names
+ * none is refused at the mount with 400 `branch-required` — so this names one
+ * unless the test already did. A test ABOUT the missing input uses `postRaw`,
+ * so the thing under test is never papered over by the helper.
+ */
+const post = (url: string, body: unknown = {}) =>
+  postRaw(
+    url,
+    body !== null && typeof body === 'object' && !Array.isArray(body) && !('branch' in body)
+      ? { branch: 'main', ...body }
+      : body,
+  );
+
 beforeEach(() => {
   /* fresh per test via start() */
 });
@@ -456,7 +471,8 @@ describe('workspace file primitives', () => {
     // named "undefined" — it fails closed with a clear 4xx naming the missing
     // branch context, BEFORE any workspace resolve.
     expect(focusedBranch).toBeUndefined();
-    const res = await post(`${base}/api/agent/tools/execute_command`, { command: 'echo should-not-run' });
+    // `postRaw`: the absent field IS the test here, so the body goes as written.
+    const res = await postRaw(`${base}/api/agent/tools/execute_command`, { command: 'echo should-not-run' });
     expect(res.status).toBe(400);
     expect((await res.json()).error).toMatch(/branch/i);
     // The guard runs before `getOrCreateForBranch`, so no workspace (least of all
@@ -471,7 +487,7 @@ describe('workspace file primitives', () => {
     // against that branch's workspace and returns output end to end (AC2) —
     // rather than failing closed the way a context-less external call does.
     focusedBranch = 'main';
-    const res = (await (await post(`${base}/api/agent/tools/execute_command`, { command: 'echo hello-exec' })).json()) as { stdout: string; exitCode: number };
+    const res = (await (await postRaw(`${base}/api/agent/tools/execute_command`, { command: 'echo hello-exec' })).json()) as { stdout: string; exitCode: number };
     expect(res.exitCode).toBe(0);
     expect(res.stdout).toContain('hello-exec');
     // Resolved against the focused branch — never an "undefined" workspace.
@@ -555,6 +571,20 @@ describe('workspace file primitives', () => {
     expect(workspacePathCalls).toEqual([]);
   });
 
+  it('answers a branch-less call with the same kind every other KB tool uses', async () => {
+    const base = await start();
+    // The MESSAGE here is this tool's own — only `execute_command` has a
+    // focused-branch fallback to explain. The DISCRIMINATOR is shared, so a
+    // client switches on one kind across the whole surface instead of matching
+    // prose per tool.
+    for (const body of [{ command: 'x' }, { branch: '', command: 'x' }, { branch: 'undefined', command: 'x' }]) {
+      const res = await postRaw(`${base}/api/agent/tools/execute_command`, body);
+      expect(res.status).toBe(400);
+      expect((await res.json()).kind).toBe('branch-required');
+    }
+    expect(workspacePathCalls).toEqual([]);
+  });
+
   it('execute_command validates the branch BEFORE the write-policy gate', async () => {
     const base = await start();
     // A routine-restricted session is refused by `assertUnrestricted` with 403.
@@ -2266,6 +2296,8 @@ describe('the tools place an unprefixed path inside the repository', () => {
 describe('folders never vanish', () => {
   const KB = (p: string) => `${KB_DIR}/${p}`;
   const tool = async (base: string, name: string, body: Record<string, unknown>) => {
+    // `post` names the branch every KB tool requires; these tests are about
+    // folders, not about the branch input.
     const res = await post(`${base}/api/agent/tools/${name}`, body);
     return { status: res.status, body: (await res.json()) as Record<string, unknown> };
   };

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,216 @@ 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('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[] = [];