@cloudcli-ai/cloudcli 1.37.2 → 1.37.4

package/server/modules/git/git.routes.ts

@@ -4,11 +4,12 @@ import path from 'path';
 import express from 'express';
 
 import type { ProviderRunFunction } from '@/shared/types.js';
-import { AppError } from '@/shared/utils.js';
+import { AppError, getGitErrorDetails } from '@/shared/utils.js';
 
 // cross-spawn: drop-in spawn with Windows .cmd/PATHEXT resolution.
 import { parseGitLogWithStats, parseGitStatusOutput } from './git-parsing.service.js';
 import { deleteLocalBranch } from './git-branch.service.js';
+import { getBranchDiffForFile, listBranchDiffFiles } from './git-branch-diff.service.js';
 
 type GitRouterDependencies = {
   fileSystem: typeof import('node:fs/promises');
@@ -207,10 +208,6 @@ async function validateGitRepository(projectPath) {
   }
 }
 
-function getGitErrorDetails(error) {
-  return `${error?.message || ''} ${error?.stderr || ''} ${error?.stdout || ''}`;
-}
-
 function isMissingHeadRevisionError(error) {
   const errorDetails = getGitErrorDetails(error).toLowerCase();
   return errorDetails.includes('unknown revision')
@@ -787,13 +784,110 @@ router.get('/branches', async (req, res) => {
     const branches = [...localBranches, ...remoteBranches]
       .filter((b, i, arr) => arr.indexOf(b) === i);
 
-    res.json({ branches, localBranches, remoteBranches });
+    // Full remote-tracking names (`origin/main`) for callers that need an
+    // unambiguous ref, e.g. the Compare tab's base selector.
+    const remoteRefs = rawLines
+      .filter(b => b.startsWith('remotes/'))
+      .map(b => b.replace(/^remotes\//, ''));
+
+    res.json({ branches, localBranches, remoteBranches, remoteRefs });
   } catch (error) {
     console.error('Git branches error:', error);
     res.json({ error: error.message });
   }
 });
 
+// Shared error shaping for the two compare routes: service AppErrors (unknown
+// ref, no merge base) keep their status/code; anything else follows the
+// module's GET convention of a 200 with `error`/`details`.
+function sendBranchDiffError(res, error, context) {
+  if (error instanceof AppError) {
+    return res.status(error.statusCode).json({ error: error.message, code: error.code, details: error.details });
+  }
+  console.error(`Git ${context} error:`, error);
+  res.json({ error: 'Git operation failed', details: error.message });
+}
+
+// List files the working copy changed relative to the merge base with `base`
+router.get('/branch-diff', async (req, res) => {
+  const { project, base } = req.query;
+
+  if (!project || !base) {
+    return res.status(400).json({ error: 'Project id and base branch are required' });
+  }
+
+  try {
+    validateBranchName(base);
+  } catch (error) {
+    return res.status(400).json({ error: error.message });
+  }
+
+  try {
+    const projectPath = await getActualProjectPath(project);
+    await validateGitRepository(projectPath);
+    // Run from the repository root so untracked paths are root-relative like
+    // everything else the panel shows, even for projects nested in a repo.
+    const repositoryRootPath = await getRepositoryRootPath(projectPath);
+    const result = await listBranchDiffFiles({
+      projectPath: repositoryRootPath,
+      base,
+      runCommand: spawnAsync,
+    });
+    res.json(result);
+  } catch (error) {
+    sendBranchDiffError(res, error, 'branch diff');
+  }
+});
+
+// Diff of one file between the merge base with `base` and the working copy.
+// `oldPath` is the pre-rename path of an `R` entry from `/branch-diff`.
+router.get('/branch-diff/file', async (req, res) => {
+  const { project, base, file, oldPath } = req.query;
+
+  if (!project || !base || !file) {
+    return res.status(400).json({ error: 'Project id, base branch and file path are required' });
+  }
+
+  try {
+    validateBranchName(base);
+    validateFilePath(file);
+    if (oldPath !== undefined) {
+      validateFilePath(oldPath);
+    }
+  } catch (error) {
+    return res.status(400).json({ error: error.message });
+  }
+
+  try {
+    const projectPath = await getActualProjectPath(project);
+    await validateGitRepository(projectPath);
+
+    // `/branch-diff` already reports repository-root-relative paths, and
+    // compare files need not appear in `git status` (committed-only changes),
+    // so the status-based resolver is skipped: its bare-filename fallback
+    // could remap e.g. `README.md` onto a changed `docs/README.md`.
+    const repositoryRootPath = await getRepositoryRootPath(projectPath);
+    const repositoryRelativeFilePath = normalizeRepositoryRelativeFilePath(file);
+    validateFilePath(repositoryRelativeFilePath, repositoryRootPath);
+    const repositoryRelativeOldPath = oldPath === undefined ? undefined : normalizeRepositoryRelativeFilePath(oldPath);
+    if (repositoryRelativeOldPath !== undefined) {
+      validateFilePath(repositoryRelativeOldPath, repositoryRootPath);
+    }
+
+    const diff = await getBranchDiffForFile({
+      projectPath: repositoryRootPath,
+      base,
+      file: repositoryRelativeFilePath,
+      oldPath: repositoryRelativeOldPath,
+      runCommand: spawnAsync,
+      readFile: (absolutePath) => fs.readFile(absolutePath, 'utf-8'),
+    });
+    res.json({ diff: stripDiffHeaders(diff) });
+  } catch (error) {
+    sendBranchDiffError(res, error, 'branch diff file');
+  }
+});
+
 // Checkout branch
 router.post('/checkout', async (req, res) => {
   const { project, branch } = req.body;

package/server/modules/git/tests/git-branch-diff.service.test.ts

@@ -0,0 +1,210 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import type { GitCommandResult } from '@/shared/types.js';
+
+import { getBranchDiffForFile, listBranchDiffFiles } from '../git-branch-diff.service.js';
+
+const MERGE_BASE = 'ad449053aa935934160725092c5ce8d63d336894';
+
+// Joins NUL-separated tokens with a trailing NUL, exactly as `-z` output looks.
+const nul = (...tokens: string[]) => tokens.join('\0') + '\0';
+
+type FakeRunnerOptions = {
+  nameStatus?: string;
+  untracked?: string;
+  diff?: string;
+  failRevParse?: boolean;
+  failMergeBase?: boolean;
+};
+
+/**
+ * Fake `spawnAsync`: records every git invocation and answers the handful of
+ * commands the service issues from canned output.
+ */
+function createRunner(options: FakeRunnerOptions = {}) {
+  const calls: string[][] = [];
+  const runCommand = async (_command: string, args: string[]): Promise<GitCommandResult> => {
+    calls.push(args);
+    const subcommand = args[0];
+
+    if (subcommand === 'rev-parse') {
+      if (options.failRevParse) {
+        throw Object.assign(new Error('Command failed'), { stderr: '' });
+      }
+      return { stdout: `${MERGE_BASE}\n`, stderr: '' };
+    }
+    if (subcommand === 'merge-base') {
+      if (options.failMergeBase) {
+        throw Object.assign(new Error('Command failed'), { stderr: 'fatal: no merge base' });
+      }
+      return { stdout: `${MERGE_BASE}\n`, stderr: '' };
+    }
+    if (subcommand === 'diff') {
+      return { stdout: args.includes('--name-status') ? options.nameStatus ?? '' : options.diff ?? '', stderr: '' };
+    }
+    if (subcommand === 'ls-files') {
+      return { stdout: options.untracked ?? '', stderr: '' };
+    }
+    throw new Error(`Unexpected git command: ${args.join(' ')}`);
+  };
+  return { calls, runCommand };
+}
+
+test('listBranchDiffFiles verifies the ref before asking git for the merge base', async () => {
+  const { calls, runCommand } = createRunner();
+
+  const result = await listBranchDiffFiles({ projectPath: '/repo', base: 'origin/main', runCommand });
+
+  assert.equal(result.mergeBase, MERGE_BASE);
+  assert.deepEqual(calls.slice(0, 2), [
+    ['rev-parse', '--verify', '--quiet', '--end-of-options', 'origin/main^{commit}'],
+    ['merge-base', '--', 'origin/main', 'HEAD'],
+  ]);
+});
+
+test('listBranchDiffFiles rejects a base that would be parsed as a git option without running git', async () => {
+  const { calls, runCommand } = createRunner();
+
+  await assert.rejects(
+    listBranchDiffFiles({ projectPath: '/repo', base: '--output=/tmp/x', runCommand }),
+    (error: unknown) => {
+      assert.equal((error as { code?: string }).code, 'GIT_INVALID_BASE_REF');
+      assert.equal((error as { statusCode?: number }).statusCode, 400);
+      return true;
+    },
+  );
+  assert.deepEqual(calls, []);
+});
+
+test('listBranchDiffFiles reports an unknown ref with a stable code', async () => {
+  const { runCommand } = createRunner({ failRevParse: true });
+
+  await assert.rejects(
+    listBranchDiffFiles({ projectPath: '/repo', base: 'origin/nope', runCommand }),
+    (error: unknown) => {
+      assert.equal((error as { code?: string }).code, 'GIT_UNKNOWN_BASE_REF');
+      assert.equal((error as { statusCode?: number }).statusCode, 400);
+      return true;
+    },
+  );
+});
+
+test('getBranchDiffForFile reports branches without common history as a 400 AppError', async () => {
+  const { runCommand } = createRunner({ failMergeBase: true });
+
+  await assert.rejects(
+    getBranchDiffForFile({ projectPath: '/repo', base: 'orphan', file: 'a.txt', runCommand, readFile: async () => '' }),
+    (error: unknown) => {
+      assert.equal((error as { name?: string }).name, 'AppError');
+      assert.equal((error as { code?: string }).code, 'GIT_NO_MERGE_BASE');
+      assert.equal((error as { statusCode?: number }).statusCode, 400);
+      return true;
+    },
+  );
+});
+
+test('listBranchDiffFiles parses NUL-separated name-status output including renames', async () => {
+  const { calls, runCommand } = createRunner({
+    nameStatus: nul('M', 'src/a.txt', 'R100', 'old name.txt', 'new name.txt', 'A', 'b.txt', 'D', 'gone.txt', 'C75', 'base.txt', 'copy.txt'),
+  });
+
+  const result = await listBranchDiffFiles({ projectPath: '/repo', base: 'main', runCommand });
+
+  assert.equal(result.base, 'main');
+  assert.equal(result.mergeBase, MERGE_BASE);
+  assert.deepEqual(result.files, [
+    { path: 'b.txt', status: 'A' },
+    { path: 'copy.txt', status: 'A' },
+    { path: 'gone.txt', status: 'D' },
+    { path: 'new name.txt', oldPath: 'old name.txt', status: 'R' },
+    { path: 'src/a.txt', status: 'M' },
+  ]);
+  // The working tree is diffed against the merge base, never the base tip.
+  assert.deepEqual(calls[2], ['diff', '--name-status', '-M', '-z', MERGE_BASE, '--']);
+  assert.deepEqual(calls[3], ['ls-files', '--others', '--exclude-standard', '-z']);
+});
+
+test('listBranchDiffFiles merges untracked files as U and sorts everything by path', async () => {
+  const { runCommand } = createRunner({
+    nameStatus: nul('M', 'a.txt', 'A', 'b.txt'),
+    untracked: nul('c.txt', 'aa.txt'),
+  });
+
+  const result = await listBranchDiffFiles({ projectPath: '/repo', base: 'main', runCommand });
+
+  assert.deepEqual(result.files, [
+    { path: 'a.txt', status: 'M' },
+    { path: 'aa.txt', status: 'U' },
+    { path: 'b.txt', status: 'A' },
+    { path: 'c.txt', status: 'U' },
+  ]);
+});
+
+test('listBranchDiffFiles returns an empty list when nothing differs', async () => {
+  const { runCommand } = createRunner();
+
+  const result = await listBranchDiffFiles({ projectPath: '/repo', base: 'main', runCommand });
+
+  assert.deepEqual(result.files, []);
+});
+
+test('getBranchDiffForFile diffs a tracked file against the merge base with the path after --', async () => {
+  const diff = 'diff --git a/a.txt b/a.txt\n--- a/a.txt\n+++ b/a.txt\n@@ -1,2 +1,3 @@\n line1\n-line2\n+line2 changed\n+line3\n';
+  const { calls, runCommand } = createRunner({ diff });
+  let readFileCalls = 0;
+
+  const result = await getBranchDiffForFile({
+    projectPath: '/repo',
+    base: 'main',
+    file: 'a.txt',
+    runCommand,
+    readFile: async () => {
+      readFileCalls += 1;
+      return '';
+    },
+  });
+
+  assert.equal(result, diff);
+  assert.equal(readFileCalls, 0);
+  assert.deepEqual(calls[2], ['ls-files', '--others', '--exclude-standard', '-z', '--', 'a.txt']);
+  assert.deepEqual(calls[3], ['diff', '-M', MERGE_BASE, '--', 'a.txt']);
+});
+
+test('getBranchDiffForFile hands both paths of a rename to git so it diffs the rename, not a new file', async () => {
+  const diff = 'diff --git a/keep.txt b/kept.txt\nsimilarity index 90%\nrename from keep.txt\nrename to kept.txt\n@@ -1 +1 @@\n-x\n+y\n';
+  const { calls, runCommand } = createRunner({ diff });
+
+  const result = await getBranchDiffForFile({
+    projectPath: '/repo',
+    base: 'main',
+    file: 'kept.txt',
+    oldPath: 'keep.txt',
+    runCommand,
+    readFile: async () => '',
+  });
+
+  assert.equal(result, diff);
+  assert.deepEqual(calls[3], ['diff', '-M', MERGE_BASE, '--', 'keep.txt', 'kept.txt']);
+});
+
+test('getBranchDiffForFile synthesizes an all-additions diff for an untracked file', async () => {
+  const { calls, runCommand } = createRunner({ untracked: nul('c.txt') });
+  const readPaths: string[] = [];
+
+  const result = await getBranchDiffForFile({
+    projectPath: '/repo',
+    base: 'main',
+    file: 'c.txt',
+    runCommand,
+    readFile: async (absolutePath) => {
+      readPaths.push(absolutePath);
+      return 'first\nsecond';
+    },
+  });
+
+  assert.deepEqual(readPaths, ['/repo/c.txt']);
+  assert.equal(result, '--- /dev/null\n+++ b/c.txt\n@@ -0,0 +1,2 @@\n+first\n+second');
+  // No `git diff` is run for untracked files.
+  assert.equal(calls.some((args) => args[0] === 'diff'), false);
+});

package/server/modules/projects/project-clone.routes.ts

@@ -0,0 +1,142 @@
+import express, { type Request } from 'express';
+
+import type { PendingCloneRequests } from '@/modules/projects/services/project-clone-request.service.js';
+import type { startCloneProject } from '@/modules/projects/services/project-clone.service.js';
+import { AppError, asyncHandler } from '@/shared/utils.js';
+
+type ProjectCloneRouterDependencies = {
+  startCloneProject: typeof startCloneProject;
+  pendingCloneRequests: PendingCloneRequests;
+};
+
+type AuthenticatedUser = {
+  id?: number | string;
+};
+
+function requireAuthenticatedUserId(req: Request): number | string {
+  const authenticatedUser = (req as Request & { user?: AuthenticatedUser }).user;
+  const userId = authenticatedUser?.id;
+  if (userId === undefined || userId === null) {
+    throw new AppError('Authenticated user is required', {
+      code: 'AUTHENTICATION_REQUIRED',
+      statusCode: 401,
+    });
+  }
+
+  return userId;
+}
+
+function resolveRouteErrorMessage(error: unknown): string {
+  if (error instanceof AppError) {
+    return error.message;
+  }
+
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+
+  return 'Failed to clone repository';
+}
+
+/**
+ * Creates the two halves of a repository clone. The browser's EventSource can
+ * only issue a bare GET, and a GET's URL is written to access logs, proxy logs
+ * and browser history — so the request that carries the GitHub token is a
+ * POST, and the stream's URL names it by an opaque id.
+ */
+export function createProjectCloneRouter(dependencies: ProjectCloneRouterDependencies): express.Router {
+  const router = express.Router();
+
+  /**
+   * Parks the request under a fresh id for `/clone-progress` to pick up.
+   * Nothing is spawned here; the stream that follows runs and reports it.
+   */
+  router.post(
+    '/clone',
+    asyncHandler(async (req, res) => {
+      const userId = requireAuthenticatedUserId(req);
+      const requestBody = req.body as Record<string, unknown>;
+      const cloneId = dependencies.pendingCloneRequests.add(userId, {
+        workspacePath: typeof requestBody.path === 'string' ? requestBody.path : '',
+        githubUrl: typeof requestBody.githubUrl === 'string' ? requestBody.githubUrl : '',
+        githubTokenId: typeof requestBody.githubTokenId === 'number' ? requestBody.githubTokenId : null,
+        newGithubToken: typeof requestBody.newGithubToken === 'string' ? requestBody.newGithubToken : null,
+      });
+
+      res.json({ cloneId });
+    }),
+  );
+
+  /**
+   * Claims the request the id names before any stream headers go out, so a
+   * stale or foreign id gets an ordinary 404 instead of an empty stream.
+   */
+  router.get(
+    '/clone-progress',
+    asyncHandler(async (req, res) => {
+      const userId = requireAuthenticatedUserId(req);
+      const cloneId = typeof req.query.cloneId === 'string' ? req.query.cloneId : '';
+      const cloneRequest = dependencies.pendingCloneRequests.claim(cloneId, userId);
+      if (!cloneRequest) {
+        throw new AppError('Clone request not found or expired', {
+          code: 'CLONE_REQUEST_NOT_FOUND',
+          statusCode: 404,
+        });
+      }
+
+      res.setHeader('Content-Type', 'text/event-stream');
+      res.setHeader('Cache-Control', 'no-cache');
+      res.setHeader('Connection', 'keep-alive');
+      res.flushHeaders();
+
+      const sendEvent = (type: string, data: Record<string, unknown>) => {
+        if (res.writableEnded) {
+          return;
+        }
+
+        res.write(`data: ${JSON.stringify({ type, ...data })}\n\n`);
+      };
+
+      // The client can go away while the clone is still validating its
+      // input and preparing the directory — before there is an operation to
+      // cancel. Remember that it did, so the git process is cancelled the
+      // moment it exists rather than left cloning for nobody: the id was
+      // claimed above, so no reconnect can ever reach this run.
+      let cloneOperation: Awaited<ReturnType<typeof startCloneProject>> | null = null;
+      let clientGone = false;
+      const closeListener = () => {
+        clientGone = true;
+        cloneOperation?.cancel();
+      };
+      req.on('close', closeListener);
+
+      try {
+        cloneOperation = await dependencies.startCloneProject(
+          { ...cloneRequest, userId },
+          {
+            onProgress: (message) => {
+              sendEvent('progress', { message });
+            },
+            onComplete: ({ project, message }) => {
+              sendEvent('complete', { project, message });
+            },
+          },
+        );
+        if (clientGone) {
+          cloneOperation.cancel();
+        }
+
+        await cloneOperation.waitForCompletion;
+      } catch (error) {
+        sendEvent('error', { message: resolveRouteErrorMessage(error) });
+      } finally {
+        req.off('close', closeListener);
+        if (!res.writableEnded) {
+          res.end();
+        }
+      }
+    }),
+  );
+
+  return router;
+}

package/server/modules/projects/projects.routes.ts

@@ -1,6 +1,8 @@
 import express from 'express';
 
 import { createProject, updateProjectDisplayName } from '@/modules/projects/services/project-management.service.js';
+import { createProjectCloneRouter } from '@/modules/projects/project-clone.routes.js';
+import { createPendingCloneRequests } from '@/modules/projects/services/project-clone-request.service.js';
 import { startCloneProject } from '@/modules/projects/services/project-clone.service.js';
 import { getProjectTaskMaster } from '@/modules/projects/services/projects-has-taskmaster.service.js';
 import { AppError, asyncHandler, createApiSuccessResponse } from '@/shared/utils.js';
@@ -8,11 +10,14 @@ import { getArchivedProjectsWithSessions, getProjectSessionsPage, getProjectsWit
 import { deleteOrArchiveProject, restoreArchivedProject } from '@/modules/projects/services/project-delete.service.js';
 import { applyLegacyStarredProjectIds, toggleProjectStar } from '@/modules/projects/services/project-star.service.js';
 
-const router = express.Router();
+/**
+ * How long a posted clone request waits for its progress stream to be opened.
+ * The client opens the stream as soon as the POST resolves, so this only has
+ * to outlast a slow round trip.
+ */
+const PENDING_CLONE_REQUEST_TTL_MS = 60_000;
 
-type AuthenticatedUser = {
-  id?: number | string;
-};
+const router = express.Router();
 
 function readQueryStringValue(value: unknown): string {
   if (typeof value === 'string') {
@@ -53,18 +58,6 @@ function parseNonNegativeIntQuery(value: unknown, name: string, fallback: number
   return parsedValue;
 }
 
-function resolveRouteErrorMessage(error: unknown): string {
-  if (error instanceof AppError) {
-    return error.message;
-  }
-
-  if (error instanceof Error && error.message) {
-    return error.message;
-  }
-
-  return 'Failed to clone repository';
-}
-
 router.get(
   '/',
   asyncHandler(async (req, res) => {
@@ -119,7 +112,7 @@ router.post(
       throw new AppError('Repository cloning is not supported on create-project', {
         code: 'CLONE_NOT_SUPPORTED_ON_CREATE_PROJECT',
         statusCode: 400,
-        details: 'Use /api/projects/clone-progress for cloning workflows',
+        details: 'Use /api/projects/clone for cloning workflows',
       });
     }
 
@@ -153,70 +146,12 @@ router.post(
   }),
 );
 
-router.get('/clone-progress', async (req, res) => {
-  res.setHeader('Content-Type', 'text/event-stream');
-  res.setHeader('Cache-Control', 'no-cache');
-  res.setHeader('Connection', 'keep-alive');
-  res.flushHeaders();
-
-  const sendEvent = (type: string, data: Record<string, unknown>) => {
-    if (res.writableEnded) {
-      return;
-    }
-
-    res.write(`data: ${JSON.stringify({ type, ...data })}\n\n`);
-  };
-
-  let cloneOperation: Awaited<ReturnType<typeof startCloneProject>> | null = null;
-  const closeListener = () => {
-    cloneOperation?.cancel();
-  };
-  req.on('close', closeListener);
-
-  try {
-    const queryParams = req.query as Record<string, unknown>;
-    const workspacePath = readQueryStringValue(queryParams.path);
-    const githubUrl = readQueryStringValue(queryParams.githubUrl);
-    const githubTokenId = readOptionalNumericQueryValue(queryParams.githubTokenId);
-    const newGithubToken = readQueryStringValue(queryParams.newGithubToken) || null;
-
-    const authenticatedUser = (req as typeof req & { user?: AuthenticatedUser }).user;
-    const userId = authenticatedUser?.id;
-    if (userId === undefined || userId === null) {
-      throw new AppError('Authenticated user is required', {
-        code: 'AUTHENTICATION_REQUIRED',
-        statusCode: 401,
-      });
-    }
-
-    cloneOperation = await startCloneProject(
-      {
-        workspacePath,
-        githubUrl,
-        githubTokenId,
-        newGithubToken,
-        userId,
-      },
-      {
-        onProgress: (message) => {
-          sendEvent('progress', { message });
-        },
-        onComplete: ({ project, message }) => {
-          sendEvent('complete', { project, message });
-        },
-      },
-    );
-
-    await cloneOperation.waitForCompletion;
-  } catch (error) {
-    sendEvent('error', { message: resolveRouteErrorMessage(error) });
-  } finally {
-    req.off('close', closeListener);
-    if (!res.writableEnded) {
-      res.end();
-    }
-  }
-});
+router.use(
+  createProjectCloneRouter({
+    startCloneProject,
+    pendingCloneRequests: createPendingCloneRequests(PENDING_CLONE_REQUEST_TTL_MS),
+  }),
+);
 
 router.get(
   '/:projectId/taskmaster',

package/server/modules/projects/services/project-clone-request.service.ts

@@ -0,0 +1,56 @@
+import { randomUUID } from 'node:crypto';
+
+export type PendingCloneRequest = {
+  workspacePath: string;
+  githubUrl: string;
+  githubTokenId: number | null;
+  newGithubToken: string | null;
+};
+
+export type PendingCloneRequests = {
+  add: (userId: number | string, request: PendingCloneRequest) => string;
+  claim: (cloneId: string, userId: number | string) => PendingCloneRequest | null;
+};
+
+type PendingCloneEntry = {
+  userId: number | string;
+  request: PendingCloneRequest;
+  expiry: NodeJS.Timeout;
+};
+
+/**
+ * Holds clone requests between the POST that submits them and the EventSource
+ * GET that runs them. The browser's EventSource can only issue a bare GET, so
+ * whatever it needs has to travel in the URL — and a URL is written to access
+ * logs, proxy logs and browser history. The token therefore arrives in a POST
+ * body and waits here, and the GET carries nothing but the opaque id.
+ *
+ * Every entry is bound to the user who posted it, is handed out once, and is
+ * dropped after `ttlMs` whether or not it was claimed.
+ */
+export function createPendingCloneRequests(ttlMs: number): PendingCloneRequests {
+  const pending = new Map<string, PendingCloneEntry>();
+
+  return {
+    add(userId, request) {
+      const cloneId = randomUUID();
+      const expiry = setTimeout(() => {
+        pending.delete(cloneId);
+      }, ttlMs);
+      // An abandoned request must not keep the process alive on shutdown.
+      expiry.unref();
+      pending.set(cloneId, { userId, request, expiry });
+      return cloneId;
+    },
+    claim(cloneId, userId) {
+      const entry = pending.get(cloneId);
+      if (!entry || entry.userId !== userId) {
+        return null;
+      }
+
+      clearTimeout(entry.expiry);
+      pending.delete(cloneId);
+      return entry.request;
+    },
+  };
+}