fix(clone): harden per review: symlink-safe scaffolding, race-safe cleanup, decode guard, bounded git queue

Addresses all four findings from the #251 review:

- Scaffolding no longer writes through repository-controlled symlinks.
  The guard lives in hooks-config.ts (settingsWriteBlocker) so it also
  covers quick-start/docker/ralph writers, not just the clone route:
  refuses a symlinked .claude or settings.local.json, a .claude that is
  a file, or one resolving outside the case. The clone route surfaces
  the refusal as a user-visible warning, and the CLAUDE.md write checks
  presence via lstat so a BROKEN repo-shipped symlink counts as present
  (existsSync follows links and would have created the outside target).

- Failed-clone cleanup can no longer delete a concurrent winner's tree:
  git clones into an attempt-owned temp sibling (.<name>.cloning-<rand>)
  which is atomically renamed into place; the loser reports
  DESTINATION_EXISTS and only ever removes its own temp dir.

- decodeURIComponent(url.pathname) is guarded: malformed percent-escapes
  now come back as BAD_SYNTAX instead of an uncaught URIError 500.

- The git pool's waiter queue is bounded (CODEMAN_MAX_GIT_QUEUE, default
  16): overflow answers BUSY immediately (HTTP 429 via RATE_LIMITED),
  and queue time counts against the operation's own deadline.

Tests: hostile symlink fixture repo (route level), settingsWriteBlocker
units, concurrent same-destination race, temp-dir leak assertions,
percent-escape rejection, and a fake-git pool-bounds suite.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

test/git-clone.test.ts

@@ -14,9 +14,9 @@
  * Port: N/A (no server).
  */
 
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
 import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import {
@@ -134,6 +134,13 @@ describe('parseGitRepositoryUrl', () => {
   it('REFUSES a URL with no repository name', () => {
     expect(rejected('https://github.com/').code).toBe('NO_REPOSITORY_NAME');
   });
+
+  it('REFUSES a malformed percent-escape as BAD_SYNTAX instead of throwing', () => {
+    // `new URL` tolerates "%zz" in a path; decodeURIComponent throws on it,
+    // and uncaught that URIError surfaced as a 500 from the route.
+    expect(rejected('https://github.com/%zz/repo.git').code).toBe('BAD_SYNTAX');
+    expect(rejected('https://github.com/owner/repo%').code).toBe('BAD_SYNTAX');
+  });
 });
 
 describe('suggestCaseNameFromRepo', () => {
@@ -377,8 +384,29 @@ describe.skipIf(!gitPresent)('cloneRepository / probeGitRemote (real git)', () =
     const result = await cloneRepository({ repository: origin, destination: dest, ref: 'no-such-branch' });
     expect(result.ok).toBe(false);
     if (!result.ok) expect(result.failure.code).toBe('REF_NOT_FOUND');
-    // The half-written tree must not survive as a phantom case directory.
+    // The half-written tree must not survive as a phantom case directory,
+    // and neither may the attempt-owned temp directory it cloned into.
     expect(existsSync(dest)).toBe(false);
+    expect(readdirSync(root).filter((n) => n.includes('.cloning-'))).toEqual([]);
+  });
+
+  it('lets two concurrent clones of the SAME destination race safely', async () => {
+    // Both used to pass the existence check; the loser's cleanup then DELETED
+    // the winner's finished tree. Now each attempt clones into its own temp
+    // sibling and an atomic rename decides the winner.
+    const dest = join(root, 'clone-race');
+    const results = await Promise.all([
+      cloneRepository({ repository: origin, destination: dest }),
+      cloneRepository({ repository: origin, destination: dest }),
+    ]);
+    expect(results.filter((r) => r.ok)).toHaveLength(1);
+    const loser = results.find((r) => !r.ok);
+    if (loser && !loser.ok) expect(loser.failure.code).toBe('DESTINATION_EXISTS');
+    // The winner's tree survives the loser's cleanup intact...
+    expect(existsSync(join(dest, 'README.md'))).toBe(true);
+    expect(existsSync(join(dest, '.git'))).toBe(true);
+    // ...and neither attempt leaves its temp directory behind.
+    expect(readdirSync(root).filter((n) => n.includes('.cloning-'))).toEqual([]);
   });
 
   it('refuses a destination that already exists instead of cloning into it', async () => {
@@ -418,6 +446,70 @@ describe.skipIf(!gitPresent)('cloneRepository / probeGitRemote (real git)', () =
     expect(result.ok).toBe(false);
     if (!result.ok) expect(result.failure.code).toBe('TIMEOUT');
     expect(existsSync(join(root, 'clone-timeout'))).toBe(false);
+    expect(readdirSync(root).filter((n) => n.includes('.cloning-'))).toEqual([]);
+  });
+});
+
+// ─── Pool bounds, driven with a fake `git` that sleeps ──────────────────────
+//
+// A fresh module instance (vi.resetModules + dynamic import) picks up the
+// 1-slot/1-waiter env config, and a PATH-shimmed `git` that answers --version
+// then sleeps lets one operation HOLD the slot deterministically with no
+// network. Placed after the real-git suite so the PATH shim never leaks into it.
+describe('git pool queue bounds (fake git)', () => {
+  let fakeDir: string;
+  let savedPath: string | undefined;
+  let mod: typeof import('../src/git-clone.js');
+
+  beforeAll(async () => {
+    fakeDir = mkdtempSync(join(tmpdir(), 'codeman-fake-git-'));
+    writeFileSync(
+      join(fakeDir, 'git'),
+      '#!/bin/sh\nif [ "$1" = "--version" ]; then echo "git version 2.43.0"; exit 0; fi\nsleep 30\n',
+      { mode: 0o755 }
+    );
+    savedPath = process.env.PATH;
+    process.env.PATH = `${fakeDir}:${savedPath}`;
+    process.env.CODEMAN_MAX_GIT_OPERATIONS = '1';
+    process.env.CODEMAN_MAX_GIT_QUEUE = '1';
+    vi.resetModules();
+    mod = await import('../src/git-clone.js');
+  });
+
+  afterAll(() => {
+    process.env.PATH = savedPath;
+    delete process.env.CODEMAN_MAX_GIT_OPERATIONS;
+    delete process.env.CODEMAN_MAX_GIT_QUEUE;
+    rmSync(fakeDir, { recursive: true, force: true });
+    vi.resetModules();
+  });
+
+  it('bounds the queue with BUSY and counts queue time against the deadline', async () => {
+    // Occupies the single slot: the fake git sleeps far past its 3s budget.
+    const holder = mod.probeGitRemote('https://pool.invalid/repo.git', 3_000);
+    await new Promise((r) => setTimeout(r, 100));
+
+    // Fills the single queue seat; its 300ms deadline must elapse IN the queue.
+    const queued = mod.probeGitRemote('https://pool.invalid/repo.git', 300);
+    await new Promise((r) => setTimeout(r, 50));
+
+    // Queue full: answered BUSY immediately, without waiting out its own 5s budget.
+    const before = Date.now();
+    const overflow = await mod.probeGitRemote('https://pool.invalid/repo.git', 5_000);
+    expect(Date.now() - before).toBeLessThan(1_000);
+    expect(overflow.reachable).toBe(false);
+    expect(overflow.failure?.code).toBe('BUSY');
+
+    // The queued waiter timed out WITHOUT ever spawning git (slot never freed).
+    const queuedResult = await queued;
+    expect(queuedResult.reachable).toBe(false);
+    expect(queuedResult.failure?.code).toBe('TIMEOUT');
+
+    // The slot holder is killed by its own deadline, and nothing leaks.
+    const holderResult = await holder;
+    expect(holderResult.failure?.code).toBe('TIMEOUT');
+    expect(mod.getActiveGitOperationCount()).toBe(0);
+    expect(mod.getQueuedGitOperationCount()).toBe(0);
   });
 });
 

test/hooks-config.test.ts

@@ -6,7 +6,7 @@
  */
 
 import { describe, it, expect, beforeAll, beforeEach, afterAll, afterEach } from 'vitest';
-import { closeSync, existsSync, openSync, readFileSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { closeSync, existsSync, openSync, readFileSync, writeFileSync, mkdirSync, rmSync, symlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { spawn } from 'node:child_process';
@@ -16,6 +16,7 @@ import {
   generateHooksConfig,
   generateSubagentStopGuardScript,
   refreshStaleCodemanHooks,
+  settingsWriteBlocker,
   writeHooksConfig,
 } from '../src/hooks-config.js';
 
@@ -198,6 +199,37 @@ describe('writeHooksConfig', () => {
     expect(parsed.hooks.Stop).toHaveLength(1);
   });
 
+  it('refuses to write through a symlinked .claude directory (#251 review)', async () => {
+    // Case contents can be foreign (a freshly cloned repository): a symlinked
+    // .claude would redirect the scaffold write outside the case.
+    const outside = join(testDir, 'outside-target');
+    mkdirSync(outside);
+    const caseDir = join(testDir, 'case');
+    mkdirSync(caseDir);
+    symlinkSync(outside, join(caseDir, '.claude'));
+    expect(await settingsWriteBlocker(caseDir)).toMatch(/symlink/);
+    await writeHooksConfig(caseDir);
+    expect(existsSync(join(outside, 'settings.local.json'))).toBe(false);
+  });
+
+  it('refuses to write through a symlinked settings.local.json (#251 review)', async () => {
+    const outsideFile = join(testDir, 'victim-settings.json');
+    writeFileSync(outsideFile, '{"model":"precious"}\n');
+    const caseDir = join(testDir, 'case2');
+    mkdirSync(join(caseDir, '.claude'), { recursive: true });
+    symlinkSync(outsideFile, join(caseDir, '.claude', 'settings.local.json'));
+    expect(await settingsWriteBlocker(caseDir)).toMatch(/symlink/);
+    await writeHooksConfig(caseDir);
+    // The link target is untouched: no hooks were merged into it.
+    expect(readFileSync(outsideFile, 'utf-8')).toBe('{"model":"precious"}\n');
+  });
+
+  it('reports a real, confined .claude as safe', async () => {
+    const caseDir = join(testDir, 'case3');
+    mkdirSync(join(caseDir, '.claude'), { recursive: true });
+    expect(await settingsWriteBlocker(caseDir)).toBeNull();
+  });
+
   it('should merge with existing settings.local.json', async () => {
     const claudeDir = join(testDir, '.claude');
     mkdirSync(claudeDir, { recursive: true });

test/routes/case-clone-routes.test.ts

@@ -19,7 +19,16 @@ import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach } from
 import Fastify, { type FastifyInstance } from 'fastify';
 import fastifyCookie from '@fastify/cookie';
 import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createMockRouteContext, type MockRouteContext } from '../mocks/index.js';
@@ -146,6 +155,9 @@ describe('POST /api/cases/clone — input rejection', () => {
 describe.skipIf(!gitPresent)('POST /api/cases/clone — real clone', () => {
   let root: string;
   let origin: string;
+  let hostileOrigin: string;
+  let victimDir: string;
+  let victimFile: string;
   const created: string[] = [];
 
   const git = (args: string[], cwd: string) =>
@@ -174,6 +186,33 @@ describe.skipIf(!gitPresent)('POST /api/cases/clone — real clone', () => {
     git(['remote', 'add', 'origin', origin], work);
     git(['push', '--quiet', 'origin', 'main', '--tags'], work);
     git(['symbolic-ref', 'HEAD', 'refs/heads/main'], origin);
+
+    // A HOSTILE repository: it ships the scaffold paths as symlinks aimed
+    // outside the case, so a scaffolder that follows them writes onto this
+    // machine's own files. victimFile deliberately does NOT exist, because a
+    // BROKEN CLAUDE.md link is the case existsSync gets wrong (it follows the
+    // link, reports "absent", and the scaffold write would then CREATE the
+    // outside file).
+    victimDir = join(root, 'victim-claude');
+    mkdirSync(victimDir);
+    victimFile = join(root, 'victim-file.md');
+    hostileOrigin = join(root, 'hostile.git');
+    mkdirSync(hostileOrigin);
+    git(['init', '--bare', '--quiet'], hostileOrigin);
+    const hostileWork = join(root, 'hostile-work');
+    mkdirSync(hostileWork);
+    git(['init', '--quiet'], hostileWork);
+    git(['config', 'user.email', 'test@example.com'], hostileWork);
+    git(['config', 'user.name', 'Codeman Test'], hostileWork);
+    writeFileSync(join(hostileWork, 'README.md'), '# hostile fixture\n');
+    symlinkSync(victimFile, join(hostileWork, 'CLAUDE.md'));
+    symlinkSync(victimDir, join(hostileWork, '.claude'));
+    git(['add', '.'], hostileWork);
+    git(['commit', '--quiet', '-m', 'hostile'], hostileWork);
+    git(['branch', '-M', 'main'], hostileWork);
+    git(['remote', 'add', 'origin', hostileOrigin], hostileWork);
+    git(['push', '--quiet', 'origin', 'main'], hostileWork);
+    git(['symbolic-ref', 'HEAD', 'refs/heads/main'], hostileOrigin);
   });
 
   afterAll(() => {
@@ -249,6 +288,24 @@ describe.skipIf(!gitPresent)('POST /api/cases/clone — real clone', () => {
     expect(error).toMatch(/branch or tag/i);
   });
 
+  it('refuses to scaffold through repository-shipped symlinks (keeps the clone, warns)', async () => {
+    created.push('hostile');
+    const res = await clone({ name: 'hostile', repository: hostileOrigin });
+    expect(res.statusCode).toBe(200);
+    const body = JSON.parse(res.body);
+    expect(body.success).toBe(true);
+    const casePath = join(CASES_DIR, 'hostile');
+    // The repo's symlinks are still symlinks: nothing wrote through them.
+    expect(lstatSync(join(casePath, 'CLAUDE.md')).isSymbolicLink()).toBe(true);
+    expect(lstatSync(join(casePath, '.claude')).isSymbolicLink()).toBe(true);
+    // The outside targets were neither created nor written.
+    expect(existsSync(victimFile)).toBe(false);
+    expect(existsSync(join(victimDir, 'settings.local.json'))).toBe(false);
+    // And the response says the hooks scaffold was skipped, and why.
+    expect(body.data.warnings.join(' ')).toMatch(/hooks were NOT installed/i);
+    expect(body.data.warnings.join(' ')).toMatch(/symlink/i);
+  });
+
   it('preflights the local fixture for its branches and tags', async () => {
     const res = await preflight(origin);
     const body = JSON.parse(res.body);