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

package/src/modules/tool-manuals/__tests__/tool-manuals.service.test.ts

@@ -183,6 +183,157 @@ describe('ToolManualService', () => {
     expect(manual).toBeNull();
   });
 
+  test('resolves an inline tool that calls Google as a service account, and surfaces the key variable', async () => {
+    // The auth block is what makes the call; the key it names has to reach the
+    // secrets UI as a shared variable or nobody can store it.
+    await writeFile(
+      join(root, wsId, KB_DIR, 'Plugins', 'google_ads.tool'),
+      JSON.stringify({
+        id: 'google_ads',
+        type: 'inline',
+        tools: [
+          {
+            name: 'list_accessible_customers',
+            description: 'List the customers the service account can reach.',
+            inputs: { type: 'object', properties: {} },
+            outputs: { type: 'object', properties: {} },
+            tool_call_template: {
+              call_template_type: 'http',
+              http_method: 'GET',
+              url: 'https://googleads.googleapis.com/v22/customers:listAccessibleCustomers',
+              headers: { 'developer-token': '${DEVELOPER_TOKEN}' },
+              auth: {
+                auth_type: 'google_service_account',
+                credentials: '${GOOGLE_SA_KEY}',
+                scopes: 'https://www.googleapis.com/auth/adwords',
+              },
+            },
+          },
+        ],
+      }),
+    );
+
+    const manual = await svc().resolveInlineManual('user@x.eu', 'google_ads');
+    const tools = (manual as { tools?: { name?: string; tool_call_template?: { auth?: unknown } }[] } | null)?.tools ?? [];
+    expect(tools.map((t) => t.name)).toEqual(['list_accessible_customers']);
+    // The auth block is what makes the call, so resolving must carry it through intact.
+    expect(tools[0]?.tool_call_template?.auth).toEqual({
+      auth_type: 'google_service_account',
+      credentials: '${GOOGLE_SA_KEY}',
+      scopes: 'https://www.googleapis.com/auth/adwords',
+    });
+
+    const summary = (await svc().listAccessible('user@x.eu')).find((m) => m.name === 'google_ads')!;
+    expect(summary.variables?.find((v) => v.name === 'GOOGLE_SA_KEY')?.scope).toBe('admin');
+  });
+
+  test('refuses a Google service-account auth block where no token would be sent, and says where', async () => {
+    // Only the `http` protocol mints the token. On any other template the
+    // block validates and is then sent as no credentials at all, so the file
+    // is refused when it is read rather than left to fail at Google.
+    const serviceAccount = {
+      auth_type: 'google_service_account',
+      credentials: '${GOOGLE_SA_KEY}',
+      scopes: 'https://www.googleapis.com/auth/adwords',
+    };
+    const inlineOver = (callTemplateType: string) =>
+      JSON.stringify({
+        type: 'inline',
+        tools: [
+          {
+            name: 'events',
+            description: 'Stream events.',
+            inputs: { type: 'object', properties: {} },
+            outputs: { type: 'object', properties: {} },
+            tool_call_template: { call_template_type: callTemplateType, url: 'https://api.example.com/events', auth: serviceAccount },
+          },
+        ],
+      });
+    const plugins = join(root, wsId, KB_DIR, 'Plugins');
+    await writeFile(join(plugins, 'over_sse.tool'), inlineOver('sse'));
+    await writeFile(join(plugins, 'over_streamable.tool'), inlineOver('streamable_http'));
+    // Not on a call template at all: a discovered manual takes only a url and headers.
+    await writeFile(
+      join(plugins, 'discovered.tool'),
+      JSON.stringify({ type: 'http', url: 'https://api.example.com/utcp', auth: serviceAccount }),
+    );
+    // Looking like an `http` call template is not enough: a discovered manual
+    // reads neither a block at its root nor a `tools` list, whatever they say.
+    await writeFile(
+      join(plugins, 'dressed_root.tool'),
+      JSON.stringify({ type: 'http', url: 'https://api.example.com/utcp', call_template_type: 'http', auth: serviceAccount }),
+    );
+    await writeFile(
+      join(plugins, 'unread_tools.tool'),
+      JSON.stringify({ ...JSON.parse(inlineOver('http')), type: 'http', url: 'https://api.example.com/utcp' }),
+    );
+    await writeFile(join(plugins, 'over_http.tool'), inlineOver('http'));
+
+    const catalog = await svc().listAccessibleCatalog('user@x.eu');
+
+    const reasonFor = (file: string) => catalog.invalid.find((i) => i.path === `Plugins/${file}`)?.reason ?? '';
+    expect(reasonFor('over_sse.tool')).toContain('a `sse` call template');
+    expect(reasonFor('over_streamable.tool')).toContain('a `streamable_http` call template');
+    expect(reasonFor('discovered.tool')).toContain("not a call template's `auth`");
+    expect(reasonFor('dressed_root.tool')).toContain('no tool is called through');
+    expect(reasonFor('unread_tools.tool')).toContain('no tool is called through');
+    for (const file of ['over_sse.tool', 'over_streamable.tool', 'discovered.tool', 'dressed_root.tool', 'unread_tools.tool']) {
+      expect(reasonFor(file)).toContain('`call_template_type: http`');
+    }
+    // The one place it works is left alone.
+    expect(reasonFor('over_http.tool')).toBe('');
+    expect(catalog.tools.map((m) => m.name)).toContain('overhttp');
+  });
+
+  test('refuses a `.tool` that holds a service-account key itself, wherever the block sits, and never repeats it', async () => {
+    // A `.tool` is committed and read by everyone who can read the knowledge
+    // base, so the key lives in the vault and the file only names it.
+    const key = JSON.stringify({ type: 'service_account', client_email: 'ads@proj.iam.gserviceaccount.com', private_key: 'MIIEvQIBADANBgkq-NOT-A-REAL-KEY' });
+    const withCredentials = (credentials: unknown, callTemplateType = 'http') =>
+      JSON.stringify({
+        type: 'inline',
+        tools: [
+          {
+            name: 'list',
+            description: 'List.',
+            inputs: { type: 'object', properties: {} },
+            outputs: { type: 'object', properties: {} },
+            tool_call_template: {
+              call_template_type: callTemplateType,
+              http_method: 'GET',
+              url: 'https://googleads.googleapis.com/v22/customers',
+              auth: { auth_type: 'google_service_account', credentials, scopes: 'https://www.googleapis.com/auth/adwords' },
+            },
+          },
+        ],
+      });
+    const plugins = join(root, wsId, KB_DIR, 'Plugins');
+    await writeFile(join(plugins, 'pasted_key.tool'), withCredentials(key));
+    await writeFile(join(plugins, 'pasted_base64.tool'), withCredentials(Buffer.from(key).toString('base64')));
+    // A variable with the key, or anything else, written around it is still text in the file.
+    await writeFile(join(plugins, 'beside_a_variable.tool'), withCredentials('${GOOGLE_SA_KEY}' + key));
+    // In a block nothing acts on, the key is just as readable: that it is there is said first.
+    await writeFile(join(plugins, 'key_over_sse.tool'), withCredentials(key, 'sse'));
+    await writeFile(join(plugins, 'braced.tool'), withCredentials('${GOOGLE_SA_KEY}'));
+    await writeFile(join(plugins, 'bare.tool'), withCredentials(' $GOOGLE_SA_KEY '));
+
+    const catalog = await svc().listAccessibleCatalog('user@x.eu');
+
+    const reasonFor = (file: string) => catalog.invalid.find((i) => i.path === `Plugins/${file}`)?.reason ?? '';
+    for (const file of ['pasted_key.tool', 'pasted_base64.tool', 'beside_a_variable.tool', 'key_over_sse.tool']) {
+      expect(reasonFor(file), file).toContain('something other than a vault variable as its `credentials`');
+      expect(reasonFor(file), file).toContain('Secrets Vault');
+    }
+    // Nothing of what was pasted comes back in the answer, in either spelling.
+    const answer = JSON.stringify(catalog);
+    expect(answer).not.toMatch(/NOT-A-REAL-KEY|iam\.gserviceaccount/);
+    expect(answer).not.toContain(Buffer.from(key).toString('base64').slice(0, 40));
+    // Either spelling of one variable is what the field is for.
+    expect(reasonFor('braced.tool')).toBe('');
+    expect(reasonFor('bare.tool')).toBe('');
+    expect(catalog.tools.map((m) => m.name)).toEqual(expect.arrayContaining(['braced', 'bare']));
+  });
+
   test('manual names are alphanumeric (no underscores) for variable namespacing', async () => {
     root = await mkdtemp(join(tmpdir(), 'tools2-'));
     const tools = join(root, wsId, KB_DIR, 'Plugins');

package/src/modules/tool-manuals/tool-manuals.service.ts

@@ -16,6 +16,9 @@ import {
   DefaultVariableSubstitutor,
   type CallTemplate,
 } from '@utcp/sdk';
+// Also a side effect: loading the package registers the 'google_service_account'
+// auth type, so a `.tool` naming it validates here.
+import { findUnservedGoogleServiceAccountAuth, holdsLiteralGoogleServiceAccountKey } from '@bevel-software/platform-mcp-core';
 import { descriptorsFromMcpJson } from './mcp-json-discovery.js';
 import type { PluginSource } from '../plugins/discovery/plugin-source.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
@@ -1196,6 +1199,40 @@ export function normalizeToolManual(
     descriptor.remote = false;
   }
 
+  // A service account's KEY IS NEVER WRITTEN IN A `.tool`. The file is
+  // knowledge-base content: committed, and read by everyone and every agent
+  // that can read the knowledge base. So `credentials` names the vault
+  // variable and nothing else, and a file that holds anything else there is
+  // refused before the block's placement is even looked at: a key in a block
+  // nothing acts on is just as readable. The refusal does not quote the value.
+  if (holdsLiteralGoogleServiceAccountKey(obj)) {
+    throw new Error(
+      '`auth_type: google_service_account` has something other than a vault variable as its `credentials`. ' +
+        'Write `credentials: ${GOOGLE_SA_KEY}` and store the key in the Secrets Vault under that name: a `.tool` is ' +
+        'read by everyone who can read the knowledge base. If a real key was saved in this file, treat it as ' +
+        'exposed and replace it at Google; removing it here does not take it out of the history.',
+    );
+  }
+
+  // A Google service-account `auth` block works on one thing: an inline tool's
+  // `http` call template. Anywhere else it validates and is then sent as no
+  // credentials at all, so the tool would save cleanly and call Google
+  // unauthenticated, with Google's 401 the only hint. Refused here instead,
+  // naming where the block was found. The templates below are the only ones
+  // this file's tools are called through: a `tools` list on a file that is not
+  // `inline` is never read, so nothing in it counts.
+  const toolCallTemplates =
+    type === 'inline' && Array.isArray(obj.tools)
+      ? obj.tools.map((tool: unknown) => (tool && typeof tool === 'object' ? (tool as Record<string, unknown>).tool_call_template : undefined))
+      : [];
+  const unserved = findUnservedGoogleServiceAccountAuth(obj, toolCallTemplates);
+  if (unserved) {
+    throw new Error(
+      `\`auth_type: google_service_account\` is on ${unserved}, where no token would be sent. ` +
+        "It works only as the `auth` of an inline tool's `tool_call_template` with `call_template_type: http`.",
+    );
+  }
+
   if (type === 'inline') {
     const tools = Array.isArray(obj.tools) ? obj.tools : undefined;
     if (!tools) throw new Error('inline `.tool` must have a `tools` array');

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

@@ -183,6 +183,25 @@ async function start(
     await check?.();
     return plainWriteFile(path, content, options as never);
   };
+  // `LockingFilesystem.rewriteFile`: read, compute and write with the path
+  // "locked". The other writer runs first — where the real filesystem would be
+  // acquiring the lock — so `rewrite` reads what that writer left.
+  (fs as unknown as Record<string, unknown>).rewriteFile = async (
+    path: string,
+    rewrite: (current: Buffer | null) => string | Promise<string>,
+  ) => {
+    await runRaceHook();
+    // Absent is null; any other read failure is a failure, as in the real one.
+    const current = await fs.readFile(path).then(
+      (c) => (Buffer.isBuffer(c) ? c : Buffer.from(String(c), 'utf8')),
+      (err: unknown) => {
+        const code = (err as NodeJS.ErrnoException).code;
+        if (code === 'ENOENT' || code === 'ENOTDIR') return null;
+        throw err;
+      },
+    );
+    return plainWriteFile(path, await rewrite(current));
+  };
   (fs as unknown as Record<string, unknown>).writeFiles = async (
     writes: { path: string; content: string }[],
     _summary: string,
@@ -363,6 +382,98 @@ describe('workspace file primitives', () => {
     expect((await post(`${base}/api/agent/tools/edit_file`, { path: `${KB_DIR}/a.md`, old_string: 'nope', new_string: 'x' })).status).toBe(400);
   });
 
+  it('edit_file writes new_string exactly as sent, `$` patterns included', async () => {
+    const base = await start();
+    const res = await post(`${base}/api/agent/tools/edit_file`, { path: `${KB_DIR}/a.md`, old_string: 'world', new_string: "cost: $& $1 $' $$" });
+    expect(res.status).toBe(200);
+    expect(String(await fs.readFile(`${KB_DIR}/a.md`))).toBe("hello\ncost: $& $1 $' $$\n");
+  });
+
+  /**
+   * An edit is a promise about the text it replaces, so that text has to be
+   * found in the file as it is when the write lands — read with the path's
+   * lock held, not at a preflight anybody may invalidate. `raceHook` is the
+   * other writer, running exactly where the real filesystem acquires the lock.
+   */
+  describe('edit_file looks for old_string in the file the write actually lands on', () => {
+    const EMPTY_OWNER = '# Assignee\n\n# Log';
+    const claim = (base: string, who: string) =>
+      post(`${base}/api/agent/tools/edit_file`, {
+        path: `${KB_DIR}/ticket.md`,
+        old_string: EMPTY_OWNER,
+        new_string: `# Assignee\n${who}\n\n# Log`,
+      });
+
+    it('refuses when another writer replaced that text after the preflight, and keeps their write', async () => {
+      const base = await start();
+      await fs.writeFile(`${KB_DIR}/ticket.md`, '# Assignee\n\n# Log\n- filed\n');
+      raceHook = async () => { await fs.writeFile(`${KB_DIR}/ticket.md`, '# Assignee\ncoder1\n\n# Log\n- filed\n'); };
+      const res = await claim(base, 'coder2');
+      expect(res.status).toBe(400);
+      expect(((await res.json()) as { error: string }).error).toContain('old_string not found');
+      expect(String(await fs.readFile(`${KB_DIR}/ticket.md`))).toBe('# Assignee\ncoder1\n\n# Log\n- filed\n');
+    });
+
+    it('applies the edit to what the other writer left when the text is still there', async () => {
+      const base = await start();
+      await fs.writeFile(`${KB_DIR}/ticket.md`, '# Assignee\n\n# Log\n- filed\n');
+      raceHook = async () => { await fs.writeFile(`${KB_DIR}/ticket.md`, '# Assignee\n\n# Log\n- filed\n- a line added meanwhile\n'); };
+      const res = await claim(base, 'coder2');
+      expect(res.status).toBe(200);
+      // Their line is kept: the new content was computed from the file as it was under the lock.
+      expect(String(await fs.readFile(`${KB_DIR}/ticket.md`))).toBe('# Assignee\ncoder2\n\n# Log\n- filed\n- a line added meanwhile\n');
+    });
+
+    it('refuses when the text became ambiguous after the preflight', async () => {
+      const base = await start();
+      await fs.writeFile(`${KB_DIR}/ticket.md`, '# Assignee\n\n# Log\n- filed\n');
+      raceHook = async () => { await fs.writeFile(`${KB_DIR}/ticket.md`, `${EMPTY_OWNER}\n${EMPTY_OWNER}\n`); };
+      const res = await claim(base, 'coder2');
+      expect(res.status).toBe(400);
+      expect(((await res.json()) as { error: string }).error).toContain('appears 2 times');
+      expect(String(await fs.readFile(`${KB_DIR}/ticket.md`))).toBe(`${EMPTY_OWNER}\n${EMPTY_OWNER}\n`);
+    });
+
+    it('answers not found when the file was deleted after the preflight, and does not recreate it', async () => {
+      const base = await start();
+      await fs.writeFile(`${KB_DIR}/ticket.md`, '# Assignee\n\n# Log\n- filed\n');
+      raceHook = async () => { await fs.deleteFile(`${KB_DIR}/ticket.md`); };
+      const res = await claim(base, 'coder2');
+      expect(res.status).toBe(404);
+      await expect(fs.readFile(`${KB_DIR}/ticket.md`)).rejects.toThrow();
+    });
+
+    // Every question the tool asks of the file is asked of the bytes it is
+    // about to replace. An extensionless file may hold anything, and the app's
+    // own upload can swap it for a binary between the preflight and the lock.
+    // The binary still CONTAINS `old_string` here, so nothing but the
+    // "may these bytes be edited as text" question can refuse it.
+    it('refuses when the file became binary after the preflight, and leaves those bytes alone', async () => {
+      const base = await start();
+      await fs.writeFile(`${KB_DIR}/TICKET`, '# Assignee\n\n# Log\n- filed\n');
+      const binary = Buffer.concat([Buffer.from([0x00, 0xff, 0xfe, 0x00]), Buffer.from(`${EMPTY_OWNER}\n`, 'utf8')]);
+      raceHook = async () => { await fs.writeFile(`${KB_DIR}/TICKET`, binary); };
+      const res = await post(`${base}/api/agent/tools/edit_file`, {
+        path: `${KB_DIR}/TICKET`,
+        old_string: EMPTY_OWNER,
+        new_string: '# Assignee\ncoder2\n\n# Log',
+      });
+      expect(res.status).toBe(415);
+      expect(await res.json()).toMatchObject({ kind: 'binary_not_writable' });
+      const after = await fs.readFile(`${KB_DIR}/TICKET`);
+      expect(Buffer.from(after as Buffer).equals(binary)).toBe(true);
+    });
+
+    it('counts replace_all over the file as it is under the lock', async () => {
+      const base = await start();
+      await fs.writeFile(`${KB_DIR}/ticket.md`, 'x x\n');
+      raceHook = async () => { await fs.writeFile(`${KB_DIR}/ticket.md`, 'x x x\n'); };
+      const res = await post(`${base}/api/agent/tools/edit_file`, { path: `${KB_DIR}/ticket.md`, old_string: 'x', new_string: 'y', replace_all: true });
+      expect(await res.json()).toMatchObject({ replaced: 3 });
+      expect(String(await fs.readFile(`${KB_DIR}/ticket.md`))).toBe('y y y\n');
+    });
+  });
+
   it('list_files + file_stat', async () => {
     const base = await start();
     const root = (await (await post(`${base}/api/agent/tools/list_files`, {})).json()) as { entries: { name: string }[] };
@@ -3445,7 +3556,7 @@ describe('a write refused for permissions says whether and how to propose it', (
       throw err;
     };
     const target = fs as unknown as Record<string, unknown>;
-    for (const m of ['writeFile', 'deleteFile', 'moveFile', 'mkdir']) target[m] = refuse;
+    for (const m of ['writeFile', 'rewriteFile', 'deleteFile', 'moveFile', 'mkdir']) target[m] = refuse;
     target.copyFile = async (_src: string, dest: string) => refuse(dest);
     // `delete_folder` lands through the same batch with NO writes and the
     // folder's files as `deletes` — in production the refusal comes from the

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

@@ -10,7 +10,7 @@ import { KbStartupRunner } from '../kb-startup-runner.js';
 import { WorkspaceService } from '../../workspace.service.js';
 import { NodeGitRunner } from '../../../workflow/git/node-git-runner.js';
 import { ClassifiedFailure, classifyGitFailure, failureOf } from '../../../../shared/git-failure.js';
-import { gitCredentials } from '../../../../shared/git.contract.js';
+import { GitRunError, gitCredentials } from '../../../../shared/git.contract.js';
 import type { OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
 
 /**
@@ -85,6 +85,8 @@ function runnerOpts(steps: OnServerStart[], overrides: Record<string, unknown> =
     defaultBranch: () => DEFAULT_BRANCH,
     protectedBranches: () => PROTECTED,
     seedAdminEmails: ['admin@example.com'],
+    // An unfinished clone made by a suite is abandoned the moment it exists.
+    unfinishedCloneQuietMs: 0,
     steps,
     buildSeedTree: async (dir: string) => {
       await fs.writeFile(path.join(dir, 'seeded.md'), 'from template', 'utf8');
@@ -784,6 +786,234 @@ describe('KbStartupRunner', () => {
   });
 });
 
+/**
+ * A clone that was cut short leaves a `.git` folder and no commit. Every
+ * start found it again, could do nothing with a branch that has no commit,
+ * and stopped: one such folder kept a whole deployment from starting.
+ */
+describe('KbStartupRunner — a working copy whose clone was never finished', () => {
+  const touchDefault = step('touch', async (ctx) => {
+    await (await ctx.defaultBranch()).repoDir();
+    return { outcome: 'ok' };
+  });
+  const local = () => path.join(workspacesRoot, DEFAULT_BRANCH, 'knowledge-base');
+
+  /** What an interrupted clone leaves: the repository made, its remote set, nothing checked out. */
+  async function halfMadeClone(): Promise<void> {
+    await fs.mkdir(local(), { recursive: true });
+    await git(local(), ['init', '-b', DEFAULT_BRANCH]);
+    await git(local(), ['remote', 'add', 'origin', upstream]);
+    await fs.writeFile(path.join(local(), 'left-here.txt'), 'somebody put this here', 'utf8');
+  }
+
+  it('is set aside, files and all, and cloned again, so the start goes through', async () => {
+    await populatedUpstream();
+    await halfMadeClone();
+    const discarded: string[] = [];
+
+    await makeRunner([touchDefault], { onCloneDiscarded: (id: string) => void discarded.push(id) }).runAll();
+
+    // A real clone stands in its place.
+    expect(await fs.readFile(path.join(local(), 'marker.txt'), 'utf8')).toBe('seeded');
+    expect((await git(local(), ['rev-parse', '--abbrev-ref', 'HEAD'])).trim()).toBe(DEFAULT_BRANCH);
+    // Nothing was deleted: what was in the folder is where set-aside copies go.
+    const runs = await fs.readdir(path.join(root, 'set-aside'));
+    expect(runs).toHaveLength(1);
+    const kept = path.join(root, 'set-aside', runs[0]!, DEFAULT_BRANCH);
+    expect(await fs.readFile(path.join(kept, 'left-here.txt'), 'utf8')).toBe('somebody put this here');
+    expect(discarded).toEqual([DEFAULT_BRANCH]);
+
+    // And the next start finds an ordinary clone: nothing more is set aside.
+    await makeRunner([touchDefault]).runAll();
+    expect(await fs.readdir(path.join(root, 'set-aside'))).toHaveLength(1);
+  });
+
+  it('leaves a working copy that has a commit exactly where it is', async () => {
+    await populatedUpstream();
+    await makeRunner([touchDefault]).runAll();
+    await fs.writeFile(path.join(local(), 'unpushed.md'), 'precious', 'utf8');
+    await git(local(), ['add', '-A']);
+    await git(local(), ['commit', '-m', 'committed but unpushed']);
+
+    await makeRunner([touchDefault]).runAll();
+
+    expect(await fs.readFile(path.join(local(), 'unpushed.md'), 'utf8')).toBe('precious');
+    expect(await fs.access(path.join(root, 'set-aside')).then(() => true, () => false)).toBe(false);
+  });
+
+  it('leaves a working copy alone when git could not say whether it has a commit', async () => {
+    await populatedUpstream();
+    await makeRunner([touchDefault]).runAll();
+    await fs.writeFile(path.join(local(), 'unpushed.md'), 'precious', 'utf8');
+    await git(local(), ['add', '-A']);
+    await git(local(), ['commit', '-m', 'committed but unpushed']);
+    // Git gives no answer to the one question: the deadline passes, as it
+    // does on a host under load. Everything else runs for real.
+    const real = new NodeGitRunner(undefined, credentials);
+    const gitRunner = {
+      defaultTimeoutMs: real.defaultTimeoutMs,
+      credentials: real.credentials,
+      run: (cwd: string, args: string[], opts?: object) =>
+        args.includes('--verify')
+          ? Promise.reject(new GitRunError('git rev-parse timed out', { timedOut: true }))
+          : real.run(cwd, args, opts),
+    };
+
+    const err = await makeRunner([touchDefault], { gitRunner })
+      .runAll()
+      .then(
+        () => null,
+        (e: unknown) => e as Error,
+      );
+
+    // "Could not tell" is not "has no commit": the start stops, the branch is
+    // named, and the work is where it was.
+    expect(err?.message).toContain(`the working copy of branch "${DEFAULT_BRANCH}" could not be prepared`);
+    expect(await fs.readFile(path.join(local(), 'unpushed.md'), 'utf8')).toBe('precious');
+    expect(await fs.access(path.join(root, 'set-aside')).then(() => true, () => false)).toBe(false);
+  });
+
+  // On a redeploy two processes share the volume for a few seconds. What the
+  // other one did while this one waited is what decides.
+  it('does not move a clone another process put in its place while this one waited', async () => {
+    await populatedUpstream();
+    await halfMadeClone();
+    const beforeCloneSetAside = async () => {
+      await fs.rm(local(), { recursive: true, force: true });
+      await git(root, ['clone', '-b', DEFAULT_BRANCH, upstream, local()]);
+      await fs.writeFile(path.join(local(), 'theirs.txt'), 'the other process wrote this', 'utf8');
+    };
+
+    await makeRunner([touchDefault], { beforeCloneSetAside }).runAll();
+
+    expect(await fs.readFile(path.join(local(), 'theirs.txt'), 'utf8')).toBe('the other process wrote this');
+    expect(await fs.access(path.join(root, 'set-aside')).then(() => true, () => false)).toBe(false);
+  });
+
+  it('clones when another process moved the half-made clone away while this one waited', async () => {
+    await populatedUpstream();
+    await halfMadeClone();
+    const beforeCloneSetAside = () => fs.rm(local(), { recursive: true, force: true });
+
+    await makeRunner([touchDefault], { beforeCloneSetAside }).runAll();
+
+    expect(await fs.readFile(path.join(local(), 'marker.txt'), 'utf8')).toBe('seeded');
+    expect(await fs.access(path.join(root, 'set-aside')).then(() => true, () => false)).toBe(false);
+  });
+
+  it('carries on when the half-made clone is taken away in the instant before the move', async () => {
+    await populatedUpstream();
+    await halfMadeClone();
+    // The folder goes right after git has answered, for the last time before
+    // the move, that it holds no commit.
+    const real = new NodeGitRunner(undefined, credentials);
+    let asked = 0;
+    const gitRunner = {
+      defaultTimeoutMs: real.defaultTimeoutMs,
+      credentials: real.credentials,
+      run: async (cwd: string, args: string[], opts?: object) => {
+        if (!args.includes('--verify') || ++asked !== 3) return real.run(cwd, args, opts);
+        try {
+          return await real.run(cwd, args, opts);
+        } finally {
+          await fs.rm(local(), { recursive: true, force: true });
+        }
+      },
+    };
+    const discarded: string[] = [];
+
+    await makeRunner([touchDefault], { gitRunner, onCloneDiscarded: (id: string) => void discarded.push(id) }).runAll();
+
+    expect(await fs.readFile(path.join(local(), 'marker.txt'), 'utf8')).toBe('seeded');
+    // This start moved nothing, so it says nothing was moved.
+    expect(discarded).toEqual([]);
+    expect(await fs.readdir(path.join(root, 'set-aside'))).toEqual([]);
+  });
+
+  it('tells the listener a second time when the first telling fails', async () => {
+    await populatedUpstream();
+    await halfMadeClone();
+    let told = 0;
+    const onCloneDiscarded = async () => {
+      if (++told === 1) throw new Error('the queue could not be reached');
+    };
+
+    await makeRunner([touchDefault], { onCloneDiscarded }).runAll();
+
+    expect(told).toBe(2);
+    expect(await fs.readFile(path.join(local(), 'marker.txt'), 'utf8')).toBe('seeded');
+  });
+
+  it('does not remove a clone somebody started at the path once it was announced empty', async () => {
+    await populatedUpstream();
+    await halfMadeClone();
+    // Told the copy is gone, the rest of the process may clone there at once.
+    const onCloneDiscarded = async () => {
+      await git(root, ['clone', '-b', DEFAULT_BRANCH, upstream, local()]);
+      await fs.writeFile(path.join(local(), 'theirs.txt'), 'a branch being opened wrote this', 'utf8');
+    };
+
+    await makeRunner([touchDefault], { onCloneDiscarded }).runAll();
+
+    expect(await fs.readFile(path.join(local(), 'theirs.txt'), 'utf8')).toBe('a branch being opened wrote this');
+    expect(await fs.readdir(path.join(root, 'set-aside'))).toHaveLength(1);
+  });
+
+  it('leaves a clone that is still being written, and uses it once it is finished', async () => {
+    await populatedUpstream();
+    await halfMadeClone();
+    // Somebody is still cloning: it finishes while this start waits for quiet.
+    const finishing = (async () => {
+      await new Promise((resolve) => setTimeout(resolve, 300));
+      await git(local(), ['fetch', 'origin']);
+      await git(local(), ['checkout', DEFAULT_BRANCH]);
+    })();
+
+    await makeRunner([touchDefault], { unfinishedCloneQuietMs: 5_000 }).runAll();
+    await finishing;
+
+    // Theirs, where it was, with what was in it: nothing was set aside.
+    expect(await fs.readFile(path.join(local(), 'left-here.txt'), 'utf8')).toBe('somebody put this here');
+    expect(await fs.readFile(path.join(local(), 'marker.txt'), 'utf8')).toBe('seeded');
+    expect(await fs.access(path.join(root, 'set-aside')).then(() => true, () => false)).toBe(false);
+  });
+
+  it('sets an unfinished clone aside only once nothing has written to it for the quiet time', async () => {
+    await populatedUpstream();
+    await halfMadeClone();
+    const started = Date.now();
+
+    await makeRunner([touchDefault], { unfinishedCloneQuietMs: 1_500 }).runAll();
+
+    expect(Date.now() - started).toBeGreaterThanOrEqual(1_350);
+    expect(await fs.readFile(path.join(local(), 'marker.txt'), 'utf8')).toBe('seeded');
+    expect(await fs.readdir(path.join(root, 'set-aside'))).toHaveLength(1);
+  });
+
+  it('names the branch when a working copy cannot be prepared', async () => {
+    await populatedUpstream();
+    await makeRunner([touchDefault]).runAll();
+    // The clone is sound and has a commit, but git cannot read the branch it
+    // is to follow: the ref the fetch updates is damaged. Not a state this
+    // phase repairs, so the start stops, and says which working copy.
+    const refs = path.join(local(), '.git', 'refs', 'remotes', 'origin');
+    await fs.rm(path.join(local(), '.git', 'packed-refs'), { force: true });
+    await fs.mkdir(refs, { recursive: true });
+    await fs.writeFile(path.join(refs, DEFAULT_BRANCH), 'not a commit id\n', 'utf8');
+
+    const err = await makeRunner([touchDefault])
+      .runAll()
+      .then(
+        () => null,
+        (e: unknown) => e as Error,
+      );
+    expect(err).toBeInstanceOf(ClassifiedFailure);
+    expect(err?.message).toContain(`the working copy of branch "${DEFAULT_BRANCH}" could not be prepared`);
+    // Nothing was set aside for it: it has a commit, so it is somebody's work.
+    expect(await fs.access(path.join(root, 'set-aside')).then(() => true, () => false)).toBe(false);
+  });
+});
+
 describe('KbStartupRunner — what a failed phase throws', () => {
   it('a scrubbed message (tokens, a presigned query) that still carries what git said', async () => {
     const prev = process.env.GITHUB_TOKEN;