@vantran-se/openchamber-web 2.1.1 → 2.2.0

package/server/lib/git/service.test.js

@@ -33,6 +33,7 @@ import {
   getTrackingBranch,
   getWorktrees,
   isGitRepository,
+  isPatchEquivalentOfHead,
   observeWorktreeTopology,
   populateWorktreeWithLockRecovery,
   previewWorktreeCreate,
@@ -49,6 +50,7 @@ import {
   getGlobalIdentity,
   stageFiles,
   subscribeWorktreeTopologyChanges,
+  renameBranch,
   unstageFiles,
   applyHunk,
   getDiff,
@@ -56,7 +58,6 @@ import {
   revertFile,
   getUntrackedDiffs,
   getFileDiff,
-  commit,
   hasLocalIdentity,
   validateWorktreeCreate,
   parseBranchCreationSource,
@@ -905,6 +906,28 @@ describe('getStatus', () => {
     await expect(getStatus(repo)).resolves.toMatchObject({ current: 'main' });
   });
 
+  it('never rewrites the index, so a terminal commit does not meet its lock (#2229)', async () => {
+    if (!canRunGit()) return;
+
+    const repo = createTempDir();
+    runGit(repo, ['init', '-b', 'main']);
+    runGit(repo, ['config', 'user.email', 'test@example.com']);
+    runGit(repo, ['config', 'user.name', 'Test User']);
+    fs.writeFileSync(path.join(repo, 'README.md'), '# Test\n');
+    runGit(repo, ['add', 'README.md']);
+    runGit(repo, ['commit', '-m', 'Initial commit']);
+    // Same content under an older timestamp: the index entry is stale, and a
+    // status that takes the optional lock rewrites the index to refresh it.
+    const older = new Date(Date.now() - 60_000);
+    fs.utimesSync(path.join(repo, 'README.md'), older, older);
+    const indexPath = path.join(repo, '.git', 'index');
+    const indexBefore = fs.readFileSync(indexPath);
+
+    await expect(getStatus(repo)).resolves.toMatchObject({ isClean: true });
+
+    expect(fs.readFileSync(indexPath).equals(indexBefore)).toBe(true);
+  });
+
   it('names the base an upstream-less branch was counted against, and only then', async () => {
     if (!canRunGit()) return;
 
@@ -1149,6 +1172,48 @@ describe('worktree root resolution', () => {
     }
   });
 
+  it('creates and removes a managed worktree from a bare repository project directory', async () => {
+    if (!canRunGit()) return;
+    const previousDataHome = process.env.XDG_DATA_HOME;
+    const parent = createTempDir();
+    process.env.XDG_DATA_HOME = path.join(parent, 'data');
+    try {
+      const source = path.join(parent, 'source');
+      fs.mkdirSync(source);
+      runGit(source, ['init', '-b', 'main']);
+      runGit(source, ['config', 'user.email', 'test@example.com']);
+      runGit(source, ['config', 'user.name', 'Test User']);
+      fs.writeFileSync(path.join(source, 'README.md'), 'initial\n');
+      runGit(source, ['add', 'README.md']);
+      runGit(source, ['commit', '-m', 'Initial commit']);
+
+      // The layout this covers: a bare git dir at <project>/.git with linked
+      // worktrees as siblings, the project directory itself being bare.
+      const bareRoot = path.join(parent, 'project');
+      fs.mkdirSync(bareRoot);
+      runGit(source, ['clone', '--bare', source, path.join(bareRoot, '.git')]);
+
+      const created = await createWorktree(bareRoot, {
+        mode: 'new', branchName: 'feature/from-bare', worktreeName: 'from-bare',
+      });
+      await expect.poll(
+        async () => (await getWorktreeBootstrapStatus(created.path)).status,
+        { timeout: 20_000 },
+      ).not.toBe('pending');
+      expect(await getWorktreeBootstrapStatus(created.path)).toMatchObject({ status: 'ready', error: null });
+      expect(fs.readFileSync(path.join(created.path, 'README.md'), 'utf8')).toBe('initial\n');
+      // The bare root lists only real checkouts: the created worktree, not itself.
+      const entries = await getWorktrees(bareRoot);
+      expect(entries.map((entry) => fs.realpathSync(entry.path))).toEqual([fs.realpathSync(created.path)]);
+      await removeWorktree(bareRoot, { directory: created.path });
+      expect(fs.existsSync(created.path)).toBe(false);
+      expect(await getWorktrees(bareRoot)).toHaveLength(0);
+    } finally {
+      if (previousDataHome === undefined) delete process.env.XDG_DATA_HOME;
+      else process.env.XDG_DATA_HOME = previousDataHome;
+    }
+  });
+
   it('resolves the git toplevel for a repository subdirectory', async () => {
     if (!canRunGit()) return;
 
@@ -1178,6 +1243,56 @@ describe('worktree root resolution', () => {
   });
 });
 
+describe.runIf(canRunGit())('isPatchEquivalentOfHead', () => {
+  it('finds a rebased commit patch in HEAD history', async () => {
+    const repo = createTempDir();
+    runGit(repo, ['init', '-b', 'main']);
+    runGit(repo, ['config', 'user.email', 'test@example.com']);
+    runGit(repo, ['config', 'user.name', 'Test User']);
+    fs.writeFileSync(path.join(repo, 'file.txt'), 'base\n');
+    runGit(repo, ['add', 'file.txt']);
+    runGit(repo, ['commit', '-m', 'base']);
+    const root = runGit(repo, ['rev-parse', 'HEAD']).trim();
+    runGit(repo, ['checkout', '-b', 'feature']);
+    fs.appendFileSync(path.join(repo, 'file.txt'), 'feature\n');
+    runGit(repo, ['commit', '-am', 'feature change']);
+    const original = runGit(repo, ['rev-parse', 'HEAD']).trim();
+    runGit(repo, ['tag', 'before-rebase', original]);
+    runGit(repo, ['checkout', 'main']);
+    fs.writeFileSync(path.join(repo, 'main.txt'), 'main\n');
+    runGit(repo, ['add', 'main.txt']);
+    runGit(repo, ['commit', '-m', 'main change']);
+    runGit(repo, ['checkout', 'feature']);
+    runGit(repo, ['rebase', 'main']);
+
+    await expect(isPatchEquivalentOfHead(repo, original)).resolves.toBe(true);
+    await expect(isPatchEquivalentOfHead(repo, root)).resolves.toBe(false);
+  });
+
+  it('rejects an unrelated commit with a different patch', async () => {
+    const repo = createTempDir();
+    runGit(repo, ['init', '-b', 'main']);
+    runGit(repo, ['config', 'user.email', 'test@example.com']);
+    runGit(repo, ['config', 'user.name', 'Test User']);
+    runGit(repo, ['commit', '--allow-empty', '-m', 'base']);
+    runGit(repo, ['checkout', '-b', 'old-feature']);
+    fs.writeFileSync(path.join(repo, 'old.txt'), 'old\n');
+    runGit(repo, ['add', 'old.txt']);
+    runGit(repo, ['commit', '-m', 'old change']);
+    const oldCommit = runGit(repo, ['rev-parse', 'HEAD']).trim();
+    runGit(repo, ['commit', '--allow-empty', '-m', 'empty change']);
+    const emptyCommit = runGit(repo, ['rev-parse', 'HEAD']).trim();
+    runGit(repo, ['checkout', 'main']);
+    fs.writeFileSync(path.join(repo, 'new.txt'), 'new\n');
+    runGit(repo, ['add', 'new.txt']);
+    runGit(repo, ['commit', '-m', 'new change']);
+
+    await expect(isPatchEquivalentOfHead(repo, oldCommit)).resolves.toBe(false);
+    await expect(isPatchEquivalentOfHead(repo, emptyCommit)).resolves.toBe(false);
+    await expect(isPatchEquivalentOfHead(repo, 'missing')).resolves.toBe(false);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // getWorktrees
 // ---------------------------------------------------------------------------
@@ -1221,6 +1336,36 @@ describe('getWorktrees', () => {
     expect(Array.isArray(result)).toBe(true);
     expect(warnSpy).not.toHaveBeenCalled();
   });
+
+  it('lists the linked worktrees of a bare repository used as the project directory', async () => {
+    if (!canRunGit()) return;
+
+    const source = createTempDir();
+    runGit(source, ['init', '-b', 'main']);
+    runGit(source, ['config', 'user.email', 'test@example.com']);
+    runGit(source, ['config', 'user.name', 'Test User']);
+    runGit(source, ['commit', '--allow-empty', '-m', 'init']);
+
+    // Two bare layouts in the wild: a `clone --bare` directory whose git dir
+    // is the directory itself, and one whose git dir is a `.git` child.
+    for (const bareRoot of [path.join(createTempDir(), 'repo.git'), path.join(createTempDir(), 'repo')]) {
+      const gitDir = bareRoot.endsWith('.git') ? bareRoot : path.join(bareRoot, '.git');
+      fs.mkdirSync(path.dirname(gitDir), { recursive: true });
+      runGit(source, ['clone', '--bare', source, gitDir]);
+      const linked = path.join(createTempDir(), 'linked');
+      runGit(gitDir, ['worktree', 'add', linked, 'main']);
+
+      for (const directory of [bareRoot, gitDir, linked]) {
+        expect(await isGitRepository(directory)).toBe(true);
+        const entries = await getWorktrees(directory);
+        // The bare repository lists itself as a worktree; it has no working
+        // tree, so only the linked checkout is a worktree anyone can open.
+        expect(entries.map((entry) => fs.realpathSync(entry.path))).toEqual([fs.realpathSync(linked)]);
+        expect(entries[0].branch).toBe('main');
+      }
+    }
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
   it('notifies subscribers only when another git process changes the worktree set', async () => {
     if (!canRunGit()) return;
 
@@ -1254,6 +1399,37 @@ describe('getWorktrees', () => {
     }
   });
 
+  it('renames a worktree branch, tells subscribers, and names the worktree that holds a taken name', async () => {
+    if (!canRunGit()) return;
+
+    const repo = createTempDir();
+    runGit(repo, ['init', '-b', 'main']);
+    runGit(repo, ['config', 'user.email', 'test@example.com']);
+    runGit(repo, ['config', 'user.name', 'Test User']);
+    runGit(repo, ['commit', '--allow-empty', '-m', 'init']);
+    const first = path.join(createTempDir(), 'first');
+    const second = path.join(createTempDir(), 'second');
+    runGit(repo, ['worktree', 'add', first, '-b', 'feature-one']);
+    runGit(repo, ['worktree', 'add', second, '-b', 'feature-two']);
+    runGit(repo, ['branch', 'parked']);
+
+    const events = [];
+    const unsubscribe = subscribeWorktreeTopologyChanges((event) => events.push(event));
+    try {
+      await expect(renameBranch(first, 'feature-one', 'feature-two'))
+        .rejects.toMatchObject({ statusCode: 409, message: expect.stringContaining(second) });
+      await expect(renameBranch(first, 'feature-one', 'parked'))
+        .rejects.toMatchObject({ statusCode: 409, message: 'A branch named parked already exists' });
+      expect(events).toHaveLength(0);
+
+      await renameBranch(first, 'feature-one', 'login-form');
+      expect(runGit(first, ['branch', '--show-current']).trim()).toBe('login-form');
+      expect(events).toHaveLength(1);
+    } finally {
+      unsubscribe();
+    }
+  });
+
   it('publishes worktrees this server creates and removes', async () => {
     if (!canRunGit()) return;
 
@@ -4613,6 +4789,28 @@ describe('parseRemoteListing', () => {
       { name: 'origin', fetchUrl: 'git@github.com:owner/repo.git', pushUrl: 'git@github.com:owner/push.git' },
     ]);
   });
+
+  it('ignores decoration after the listing kind, recognized or not (#4479)', () => {
+    // Git only annotates the fetch line in practice; the parser ignores
+    // whatever follows the marker so it does not depend on the annotation's
+    // exact shape.
+    const listing = [
+      'origin\tgit@github.com:owner/repo.git (fetch) [blob:none]',
+      'origin\tgit@github.com:owner/repo.git (push)',
+      'mirror\thttps://example.com/repo.git (fetch) [blob:limit=1m] [tree:1]',
+      'mirror\thttps://example.com/repo.git (push) [blob:none]',
+      'future\thttps://example.com/f.git (fetch) [blob:none] (extra)',
+      'future\thttps://example.com/f.git (push)',
+      'bare\t',
+      '',
+    ].join('\n');
+    expect(parseRemoteListing(['bare', 'future', 'mirror', 'origin'], listing)).toEqual([
+      { name: 'bare', fetchUrl: 'bare', pushUrl: 'bare' },
+      { name: 'future', fetchUrl: 'https://example.com/f.git', pushUrl: 'https://example.com/f.git' },
+      { name: 'mirror', fetchUrl: 'https://example.com/repo.git', pushUrl: 'https://example.com/repo.git' },
+      { name: 'origin', fetchUrl: 'git@github.com:owner/repo.git', pushUrl: 'git@github.com:owner/repo.git' },
+    ]);
+  });
 });
 
 describe.runIf(canRunGit())('getRepositoryRemoteUrls', () => {
@@ -4636,6 +4834,22 @@ describe.runIf(canRunGit())('getRepositoryRemoteUrls', () => {
     expect(remotes.find((remote) => remote.name === 'rewritten')?.fetchUrl).toBe('https://github.com/other/repo.git');
     expect(remotes.find((remote) => remote.name === 'origin')?.pushUrl).toBe('git@github.com:owner/push.git');
   });
+
+  it('reads a partial-clone remote as `git remote get-url` reports it, without the 2.54 listing annotation (#4479)', async () => {
+    const repository = createTempDir();
+    runGit(repository, ['init', '-b', 'main']);
+    runGit(repository, ['remote', 'add', 'origin', 'git@github.com:owner/repo.git']);
+    // Git 2.54+ annotates the fetch line of `git remote -v` with the filter:
+    // `... (fetch) [blob:none]`. Setting just the config key is enough.
+    runGit(repository, ['config', 'remote.origin.partialclonefilter', 'blob:none']);
+
+    const [origin] = await getRepositoryRemoteUrls(repository);
+    expect(origin).toEqual({
+      name: 'origin',
+      fetchUrl: 'git@github.com:owner/repo.git',
+      pushUrl: 'git@github.com:owner/repo.git',
+    });
+  });
 });
 
 describe.runIf(canRunGit())('getUnpushedBranchCounts', () => {

package/server/lib/git/ssh-credential-storage.js

@@ -1,13 +1,10 @@
+import { isPlainObject, isString } from '../shared/guards.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { constants as fsConstants } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { withSourceControlFileLock } from '../source-control/file-lock.js';
 
-const isPlainObject = (value) => value === Object(value)
-  && !Array.isArray(value)
-  && Object.getPrototypeOf(value) === Object.prototype;
-const isString = (value) => Object.prototype.toString.call(value) === '[object String]';
 const hasExactKeys = (value, keys) => {
   const actual = Object.keys(value);
   return actual.length === keys.length && actual.every((key) => keys.includes(key));

package/server/lib/git/submodule-discovery.js

@@ -1,3 +1,4 @@
+import { isString } from '../shared/guards.js';
 import { normalizeDiscoveryEndpoint } from './discovery-endpoint.js';
 
 export const SUBMODULE_DISCOVERY_LIMITS = Object.freeze({
@@ -13,7 +14,6 @@ const CONFIG_KEY_PATTERN = /^submodule\.(.+)\.(path|url|update)$/i;
 const GITLINK_PATTERN = /^160000 (?:(?:commit )?([0-9a-f]{40}|[0-9a-f]{64})|([0-9a-f]{40}|[0-9a-f]{64}) 0)\t(.+)$/i;
 const CONTROL_PATTERN = /[\0-\x1f\x7f]/;
 const UPDATE_MODES = new Set(['checkout', 'merge', 'rebase', 'none']);
-const isString = (value) => Object.prototype.toString.call(value) === '[object String]';
 
 const manifestError = (message, code = 'INVALID_SUBMODULE_MANIFEST') => Object.assign(new Error(message), { code });
 

package/server/lib/git/worktree-bootstrap-storage.js

@@ -1,3 +1,4 @@
+import { isPlainObject } from '../shared/guards.js';
 import crypto, { randomUUID } from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
@@ -13,7 +14,7 @@ const ERROR_CODES = new Set([
   'INVALID_REQUEST', 'NOT_FOUND', 'STALE_REPOSITORY', 'STALE_BINDING', 'STALE_CONFIG',
   'REMOTE_CHANGED', 'AUTHENTICATION_REQUIRED', 'AUTHENTICATION_FAILED', 'TRANSPORT_FAILED',
   'CONFLICT', 'CANCELLED', 'TIMEOUT', 'OUTCOME_UNKNOWN', 'RUNTIME_UNSUPPORTED', 'UNKNOWN',
-  'GIT_LFS_CLIENT_MISSING', 'PATH_LENGTH_LIMIT',
+  'GIT_LFS_CLIENT_MISSING', 'PATH_LENGTH_LIMIT', 'CHECKOUT_TOO_LARGE',
 ]);
 const HYDRATION_STATUSES = new Set([
   'succeeded', 'authorization-required', 'invalid', 'client-missing', 'failed', 'cancelled', 'not-needed',
@@ -35,12 +36,10 @@ const SAFE_ERROR_MESSAGES = Object.freeze({
   RUNTIME_UNSUPPORTED: 'Worktree checkout hydration is unsupported by this runtime',
   UNKNOWN: 'Worktree bootstrap completion is unknown. Inspect the checkout and repair setup before use.',
   GIT_LFS_CLIENT_MISSING: 'Git LFS is required but unavailable',
+  CHECKOUT_TOO_LARGE: 'Worktree checkout has too many files to inspect',
   PATH_LENGTH_LIMIT: 'Git reported "File name too long". The worktree checkout path exceeds this system\'s path-length limit. Enable OS long paths or use a shorter repository path.',
 });
 
-const isPlainObject = (value) => value === Object(value)
-  && !Array.isArray(value)
-  && Object.getPrototypeOf(value) === Object.prototype;
 const exactKeys = (value, required, optional = []) => {
   const keys = Object.keys(value);
   return required.every((key) => keys.includes(key))

package/server/lib/git/worktree-bootstrap-storage.test.js

@@ -88,6 +88,21 @@ describe('worktree bootstrap storage', () => {
     expect(encoded).not.toContain('process output');
   });
 
+  it('round-trips a checkout with too many files to inspect with its own public message', async () => {
+    const dataDirectory = await temporaryDirectory('worktree-bootstrap-too-large-');
+    const filePath = path.join(dataDirectory, 'bootstrap.json');
+    const failure = { code: 'CHECKOUT_TOO_LARGE', message: 'Checkout has too many files to inspect' };
+    await createWorktreeBootstrapStore({ filePath }).write('/worktrees/large', {
+      status: 'failed', phase: 'directory-created', error: failure.message, errorCode: failure.code, updatedAt: 12,
+      hydration: { status: 'invalid', submodules: [], lfs: [{ path: '.', status: 'invalid', error: failure }] },
+    });
+
+    await expect(createWorktreeBootstrapStore({ filePath }).read('/worktrees/large')).resolves.toMatchObject({
+      status: 'failed', errorCode: 'CHECKOUT_TOO_LARGE', error: 'Worktree checkout has too many files to inspect',
+      hydration: { lfs: [{ status: 'invalid', error: { code: 'CHECKOUT_TOO_LARGE' } }] },
+    });
+  });
+
   it('turns a restarted pending bootstrap into a git-ready repair blocker without resuming it', async () => {
     if (!gitAvailable()) return;
     const dataDirectory = await temporaryDirectory('worktree-bootstrap-restart-');

package/server/lib/git/worktree-creation.js

@@ -0,0 +1,194 @@
+/**
+ * Worktree creation with the server's authority checks, shared by
+ * `POST /api/git/worktrees` (the New worktree dialog) and the session service
+ * (`session.create` with a pull or merge request). One implementation, so a
+ * worktree made from a change request is the same kind whichever way it was
+ * asked for: the head is resolved and transferred here, never taken from the
+ * caller, and a contributor fork gets its named remote, provenance and no
+ * upstream.
+ */
+
+/** A refusal with the HTTP status and body fields the route answers with. */
+export class WorktreeCreationError extends Error {
+  constructor(message, status, code, details = {}) {
+    super(message);
+    this.name = 'WorktreeCreationError';
+    this.status = status;
+    this.code = code;
+    Object.assign(this, details);
+  }
+}
+
+/**
+ * Contributor authority is the server's to derive. A request carrying any of
+ * these fields itself is refused before anything else happens.
+ */
+export const hasClientContributorAuthority = (body) => body?.contributorFork !== undefined
+  || body?.changeRequestTransfer !== undefined || body?.contributorTransferComplete !== undefined
+  || (body?.changeRequestSource && body?.ensureRemoteUrl !== undefined);
+
+// A change request from this repository itself is fetched onto the primary
+// remote it already has, under that remote's own URL, so the checkout adds no
+// second remote for the same project. Only a fork gets a remote of its own.
+// A fork's remote is named after its owner, which the provider just said; the
+// picker cannot always know it (GitLab lists merge requests without it).
+const forkRemoteName = (owner) => `pr-${String(owner || '').trim().toLowerCase()
+  .replace(/[^a-z0-9._-]+/g, '-').replace(/-+/g, '-').replace(/^-+|-+$/g, '') || 'head'}`;
+
+const worktreeInputForSource = (input, source) => ({
+  ...input,
+  changeRequestSource: undefined,
+  contributorFork: source.classification === 'contributor-fork',
+  changeRequestTransfer: true,
+  ensureRemoteName: source.requestedRemoteName,
+  ensureRemoteUrl: source.remoteUrl ?? source.endpoint,
+  expectedRevision: source.headSha,
+});
+
+export const createWorktreeCreation = ({
+  getGitLibraries,
+  networkOperations,
+  getSourceControlBinding,
+  contributorProvenance,
+  resolveChangeRequestSource,
+  createHttpsCredentialReference,
+  resolveSourceControlAccount,
+  worktreeBootstrapStore,
+}) => {
+  const changeRequestSourceOnRepository = async (directory, source) => {
+    if (source.classification !== 'same-repository') {
+      return source.sourceProject?.owner
+        ? Object.freeze({ ...source, requestedRemoteName: forkRemoteName(source.sourceProject.owner) })
+        : source;
+    }
+    const { getRepositoryRemoteUrls } = await getGitLibraries();
+    const primary = (await getRepositoryRemoteUrls(directory)).find((remote) => remote.name === source.context.primaryRemote);
+    if (!primary?.fetchUrl) return source;
+    return Object.freeze({ ...source, requestedRemoteName: primary.name, remoteUrl: primary.fetchUrl });
+  };
+
+  /** The input `validateWorktreeCreate` checks: a change request becomes the server-resolved remote and head. */
+  const validationInput = async (directory, input) => {
+    if (!input.changeRequestSource) return input;
+    if (!(resolveChangeRequestSource instanceof Function)) {
+      throw new WorktreeCreationError('Contributor worktrees are unavailable', 501, 'RUNTIME_UNSUPPORTED');
+    }
+    const source = await changeRequestSourceOnRepository(directory, await resolveChangeRequestSource(input.changeRequestSource));
+    return worktreeInputForSource(input, source);
+  };
+
+  /**
+   * Resolves the change request, checks the account that will fetch it, and
+   * transfers its head into the repository. Nothing is created on disk before
+   * the transfer succeeds.
+   */
+  const transferChangeRequestHead = async (directory, input) => {
+    const { validateWorktreeCreate } = await getGitLibraries();
+    if (!(resolveChangeRequestSource instanceof Function)
+      || !(createHttpsCredentialReference instanceof Function)
+      || !(resolveSourceControlAccount instanceof Function)
+      || !(networkOperations?.transferContributorHead instanceof Function)) {
+      throw new WorktreeCreationError('Contributor worktrees are unavailable', 501, 'RUNTIME_UNSUPPORTED');
+    }
+    const source = await changeRequestSourceOnRepository(directory, await resolveChangeRequestSource(input.changeRequestSource));
+    const headBranch = source.headRef.slice('refs/heads/'.length);
+    const destinationRef = `refs/remotes/${source.requestedRemoteName}/${headBranch}`;
+    const transferInput = {
+      ...worktreeInputForSource(input, source),
+      existingBranch: destinationRef.slice('refs/'.length),
+      setUpstream: false,
+    };
+    const validation = await validateWorktreeCreate(directory, transferInput);
+    if (!validation.ok && !validation.errors.every((entry) => entry.code === 'contributor_transfer_unavailable')) {
+      const collision = validation.errors.find((entry) => entry.code === 'remote_name_collision');
+      if (collision) {
+        throw new WorktreeCreationError(collision.message, 409, 'CONTRIBUTOR_REMOTE_COLLISION', { remoteName: transferInput.ensureRemoteName });
+      }
+      throw new WorktreeCreationError(
+        validation.errors.map((entry) => entry.message).filter(Boolean).join('\n') || 'Failed to validate worktree creation',
+        409,
+        'INVALID_REQUEST',
+      );
+    }
+    const account = await resolveSourceControlAccount(source.context);
+    if (account?.credentialId !== source.context.accountId || account?.status !== 'valid'
+      || !Number.isSafeInteger(account?.credentialRevision) || account.credentialRevision < 1
+      || Object.prototype.toString.call(account?.providerUserId) !== '[object String]' || !account.providerUserId) {
+      throw new WorktreeCreationError('Contributor credential is unavailable', 409, 'AUTHENTICATION_REQUIRED');
+    }
+    const credentialId = createHttpsCredentialReference({
+      provider: source.context.provider,
+      instance: source.context.instance,
+      credentialId: account.credentialId,
+      credentialRevision: account.credentialRevision,
+      providerUserId: account.providerUserId,
+    });
+    const transfer = await networkOperations.transferContributorHead({
+      directory,
+      sourceRequest: input.changeRequestSource,
+      source,
+      destinationRef,
+      credentialId,
+    });
+    if (transfer.state !== 'succeeded') {
+      throw new WorktreeCreationError(
+        transfer.error?.message || 'Contributor head transfer failed',
+        transfer.error?.code === 'AUTHENTICATION_REQUIRED' ? 401 : 409,
+        transfer.error?.code || 'UNKNOWN',
+      );
+    }
+    return { source, input: { ...transferInput, contributorTransferComplete: true } };
+  };
+
+  /** Creates a worktree; with `input.changeRequestSource`, from that change request's head. */
+  const create = async (directory, requestInput) => {
+    const { createWorktree, validateWorktreeCreate } = await getGitLibraries();
+    if (!(createWorktree instanceof Function) || !(validateWorktreeCreate instanceof Function)) {
+      throw new WorktreeCreationError('Worktree creation is not available', 501);
+    }
+    if (hasClientContributorAuthority(requestInput)) {
+      throw new WorktreeCreationError('Invalid contributor worktree request', 400, 'INVALID_CONTRIBUTOR_WORKTREE');
+    }
+    if (!(networkOperations?.hydrateBoundCheckout instanceof Function)
+      || !(worktreeBootstrapStore?.read instanceof Function)
+      || !(worktreeBootstrapStore?.write instanceof Function)) {
+      throw new WorktreeCreationError('Worktree checkout bootstrap is not available', 501);
+    }
+    let input = requestInput || {};
+    let source = null;
+    if (input.changeRequestSource) {
+      ({ source, input } = await transferChangeRequestHead(directory, input));
+    }
+    const bindingRead = getSourceControlBinding instanceof Function
+      ? await getSourceControlBinding(directory)
+      : null;
+    // An unbound repository hydrates through the machine's own Git for every
+    // remote, the same way it pushes; its authority is the unbound revision.
+    const repositoryAuthority = bindingRead ? {
+      repositoryId: bindingRead.repository.repositoryId,
+      bindingRevision: bindingRead.revision,
+      configRevision: bindingRead.repository.configRevision,
+    } : null;
+    const hydrateCheckout = ({ directory: checkoutDirectory, parentRemoteName }) => networkOperations.hydrateBoundCheckout({
+      directory: checkoutDirectory,
+      parentRemoteName,
+      parentEndpoint: source?.endpoint,
+      repositoryAuthority,
+    });
+    try {
+      return await createWorktree(directory, input, {
+        contributorProvenance,
+        contributorSource: source,
+        hydrateCheckout,
+        bootstrapStore: worktreeBootstrapStore,
+      });
+    } catch (error) {
+      if (error?.code === 'CONTRIBUTOR_REMOTE_COLLISION') {
+        throw new WorktreeCreationError('Contributor remote name is already used by a different endpoint', 409, 'CONTRIBUTOR_REMOTE_COLLISION', { remoteName: error.remoteName });
+      }
+      throw error;
+    }
+  };
+
+  return { validationInput, create };
+};