mixdog 1.1.1 → 1.2.0

package/src/runtime/shared/worktrees/merge.mjs

@@ -0,0 +1,182 @@
+/**
+ * Unified merge backend: fold a branch into the branch checked out in a
+ * project folder. Shared by the managed worktree merge and the desktop
+ * Source Control dock, so both have one semantics:
+ *   - explicit confirmation is required;
+ *   - the folder must be on `target` (when given), with no operation in
+ *     progress and no uncommitted or untracked changes;
+ *   - `git merge-tree --write-tree` previews the exact commits first, and a
+ *     conflicting merge returns its files WITHOUT touching the folder;
+ *   - a clean preview merges with --no-ff --no-edit; if that merge still
+ *     fails (hook, interruption) only the merge this call started is aborted
+ *     and the failure is thrown, never reported as success.
+ * The caller holds the repository lock (lock.mjs) around the whole call.
+ *
+ * `git(cwd, args)` resolves to { code, stdout, stderr } and never throws on a
+ * non-zero exit.
+ */
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { worktreeError } from './contract.mjs';
+import { firstLine, parseStatusPaths } from './git.mjs';
+
+function failure(args, result) {
+  const detail = String(result?.stderr || result?.stdout || '').trim() || 'no diagnostic';
+  const error = new Error(`git ${args[0]} failed (exit ${result?.code}): ${detail}`);
+  error.code = 'GIT_FAILED';
+  return error;
+}
+
+/** The sequencer operation in progress in `cwd`, or ''. */
+export async function operationInProgress(git, cwd) {
+  for (const [ref, name] of [
+    ['MERGE_HEAD', 'merge'],
+    ['CHERRY_PICK_HEAD', 'cherry-pick'],
+    ['REVERT_HEAD', 'revert'],
+  ]) {
+    if ((await git(cwd, ['rev-parse', '--verify', '--quiet', ref])).code === 0) return name;
+  }
+  const paths = await git(cwd, [
+    'rev-parse',
+    '--path-format=absolute',
+    '--git-path',
+    'rebase-merge',
+    '--git-path',
+    'rebase-apply',
+  ]);
+  if (paths.code === 0) {
+    for (const path of String(paths.stdout)
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean)) {
+      if (existsSync(resolve(cwd, path))) return 'rebase';
+    }
+  }
+  return '';
+}
+
+/** Changed and untracked paths in `cwd` (porcelain v1, -z). */
+export async function uncommittedPaths(git, cwd) {
+  const args = ['status', '--porcelain=v1', '-z', '--untracked-files=normal'];
+  const result = await git(cwd, args);
+  if (result.code !== 0) throw failure(args, result);
+  return parseStatusPaths(result.stdout);
+}
+
+async function revParse(git, cwd, rev) {
+  const result = await git(cwd, ['rev-parse', '--verify', '--quiet', rev]);
+  return result.code === 0 ? firstLine(result.stdout) : null;
+}
+
+async function checkedOutBranch(git, cwd) {
+  const result = await git(cwd, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+  return result.code === 0 ? firstLine(result.stdout) || null : null;
+}
+
+/**
+ * @typedef {{ merged: boolean, commit: string|null, target: string, conflicts?: string[], upToDate?: boolean }} MergeResult
+ */
+
+/**
+ * @param {{
+ *   git: (cwd: string, args: string[]) => Promise<{ code: number, stdout: string, stderr: string }>,
+ *   cwd: string,
+ *   source: string,
+ *   target?: string|null,
+ *   confirmed: boolean,
+ *   message?: string,
+ * }} input
+ * @returns {Promise<MergeResult>}
+ */
+export async function mergeBranchIntoCheckout({ git, cwd, source, target = null, confirmed, message }) {
+  if (confirmed !== true) throw worktreeError('WORKTREE_CONFIRM_REQUIRED');
+  const sourceName = String(source || '').trim();
+  if (!sourceName || sourceName.startsWith('-')) {
+    throw worktreeError('MERGE_FAILED', 'A merge source branch is required.', { reason: 'source-invalid' });
+  }
+  const current = await checkedOutBranch(git, cwd);
+  if (target !== null && target !== undefined && target !== current) {
+    throw worktreeError(
+      'WORKTREE_TARGET_MISMATCH',
+      `The project folder is on ${current ?? 'a detached HEAD'}, not ${target}; reload and try again.`,
+      { expected: target, actual: current }
+    );
+  }
+  if (!current) {
+    throw worktreeError('MERGE_FAILED', 'Check out a branch in the project folder before merging.', {
+      reason: 'detached-head',
+    });
+  }
+  const operation = await operationInProgress(git, cwd);
+  if (operation) {
+    throw worktreeError('MERGE_TARGET_DIRTY', `A ${operation} is already in progress in the project folder.`, {
+      operation,
+      files: [],
+    });
+  }
+  const dirty = await uncommittedPaths(git, cwd);
+  if (dirty.length) {
+    throw worktreeError('MERGE_TARGET_DIRTY', undefined, {
+      operation: '',
+      files: dirty.slice(0, 50),
+      count: dirty.length,
+    });
+  }
+  const head = await revParse(git, cwd, 'HEAD^{commit}');
+  if (!head) throw worktreeError('MERGE_FAILED', 'The merge target has no commits.', { reason: 'target-empty' });
+  const sourceCommit = await revParse(git, cwd, `${sourceName}^{commit}`);
+  if (!sourceCommit) {
+    throw worktreeError('MERGE_FAILED', `No branch or commit named ${sourceName}.`, {
+      reason: 'source-missing',
+      source: sourceName,
+    });
+  }
+
+  if ((await git(cwd, ['merge-base', '--is-ancestor', sourceCommit, head])).code === 0) {
+    return { merged: true, commit: head, target: current, upToDate: true };
+  }
+  const previewArgs = ['merge-tree', '--write-tree', '--name-only', '--no-messages', '-z', head, sourceCommit];
+  const preview = await git(cwd, previewArgs);
+  if (preview.code === 1) {
+    const conflicts = [...new Set(String(preview.stdout).split('\0').slice(1).filter(Boolean))];
+    return { merged: false, commit: null, target: current, conflicts };
+  }
+  if (preview.code !== 0) throw failure(previewArgs, preview);
+
+  // Nothing Mixdog runs can move the folder while the caller holds the
+  // repository lock; an outside process still could, so re-verify.
+  if ((await revParse(git, cwd, 'HEAD^{commit}')) !== head || (await checkedOutBranch(git, cwd)) !== current) {
+    throw worktreeError('WORKTREE_TARGET_MISMATCH', 'The project folder changed during the merge; try again.', {
+      expected: current,
+    });
+  }
+  const mergeArgs = [
+    'merge',
+    '--no-ff',
+    '--no-edit',
+    '-m',
+    message || `Merge branch '${sourceName}' into ${current}`,
+    sourceCommit,
+  ];
+  const merged = await git(cwd, mergeArgs);
+  if (merged.code !== 0) {
+    // No operation was in progress before this call, so a MERGE_HEAD now is
+    // the merge this call started.
+    let aborted = false;
+    if (await revParse(git, cwd, 'MERGE_HEAD')) aborted = (await git(cwd, ['merge', '--abort'])).code === 0;
+    const outcome = aborted ? ' (the merge was aborted; the project folder is unchanged)' : '';
+    const error = worktreeError('MERGE_FAILED', `${failure(mergeArgs, merged).message}${outcome}`, {
+      reason: 'merge-failed',
+      aborted,
+    });
+    error.aborted = aborted;
+    throw error;
+  }
+  const commit = await revParse(git, cwd, 'HEAD^{commit}');
+  if (!commit || commit === head || (await revParse(git, cwd, 'HEAD^2')) !== sourceCommit) {
+    throw worktreeError('MERGE_FAILED', 'git merge reported success but HEAD is not the expected merge commit.', {
+      reason: 'unexpected-head',
+    });
+  }
+  return { merged: true, commit, target: current };
+}

package/src/runtime/shared/worktrees/owner.mjs

@@ -0,0 +1,46 @@
+/**
+ * Live owner leases. Durable ownership is the registry record's
+ * `ownerSessionId` (the session retains the worktree across restarts); the
+ * lease says which runtime of that session holds it right now. A lease is
+ * matched on the exact owner (sessionId + runtimeToken); the pid is a
+ * diagnostic hint only, never the identity.
+ *
+ * Leases live at <root>/.owners/<id>.json (outside the worktree checkout, so
+ * they never show up as untracked files in it).
+ */
+import { readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseJsonText, writeJsonAtomicAsync } from '../atomic-file.mjs';
+import { managedWorktreeRoot, normalizeWorktreeOwner } from './contract.mjs';
+
+function ownerLeasePath(record) {
+  return join(managedWorktreeRoot(record.repoCommonDir), '.owners', `${record.id}.json`);
+}
+
+export async function readOwnerLease(record) {
+  try {
+    const value = parseJsonText(await readFile(ownerLeasePath(record), 'utf8'));
+    return {
+      ...normalizeWorktreeOwner(value),
+      entryId: value.entryId ?? record.id,
+      claimedAt: value.claimedAt ?? null,
+    };
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error instanceof SyntaxError || error instanceof TypeError) return null;
+    throw error;
+  }
+}
+
+export async function writeOwnerLease(record, owner) {
+  const lease = { ...normalizeWorktreeOwner(owner), entryId: record.id, claimedAt: Date.now() };
+  await writeJsonAtomicAsync(ownerLeasePath(record), lease);
+  return lease;
+}
+
+export function sameOwner(left, right) {
+  return !!left && !!right && left.sessionId === right.sessionId && left.runtimeToken === right.runtimeToken;
+}
+
+export async function removeOwnerLease(record) {
+  await rm(ownerLeasePath(record), { force: true });
+}

package/src/runtime/shared/worktrees/paths.mjs

@@ -0,0 +1,62 @@
+/**
+ * Canonical path helpers for managed worktrees. Git reports paths with forward
+ * slashes, long names and resolved symlinks while callers may hold 8.3 short
+ * names, other casing (Windows) or symlinked parents (macOS /var). Every
+ * comparison and every lock key goes through these.
+ */
+import { existsSync, realpathSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+/** `resolve` plus the real path of the nearest existing ancestor. */
+export function canonicalPath(value) {
+  const full = resolve(String(value || '.'));
+  let head = full;
+  while (!existsSync(head)) {
+    const parent = dirname(head);
+    if (parent === head) return full;
+    head = parent;
+  }
+  let real;
+  try {
+    real = realpathSync.native(head);
+  } catch {
+    return full;
+  }
+  const rest = relative(head, full);
+  return rest ? join(real, rest) : real;
+}
+
+/** Comparison key: canonical, case-insensitive on Windows. */
+export function pathKey(value, platform = process.platform) {
+  const path = canonicalPath(value).replace(/[\\/]+$/, '') || sep;
+  return platform === 'win32' ? path.toLowerCase() : path;
+}
+
+export function samePath(left, right) {
+  return pathKey(left) === pathKey(right);
+}
+
+/** True when `child` is `parent` itself or lies inside it (canonical). */
+export function isWithin(parent, child) {
+  const base = pathKey(parent);
+  const target = pathKey(child);
+  return target === base || target.startsWith(base.endsWith(sep) ? base : base + sep);
+}
+
+/**
+ * Repository-relative folder of a Project registered below the repository
+ * root ('' for the root itself or anything outside it), with forward slashes.
+ * A session of that Project executes in the same folder of its worktree.
+ * @param {string|null|undefined} topLevel
+ * @param {string|null|undefined} projectPath
+ */
+export function projectSubdirOf(topLevel, projectPath) {
+  if (!topLevel || !projectPath || !isWithin(topLevel, projectPath)) return '';
+  const rel = relative(canonicalPath(topLevel), canonicalPath(projectPath));
+  return !rel || rel.startsWith('..') || isAbsolute(rel) ? '' : rel.split(sep).join('/');
+}
+
+/** `subdir` (forward slashes, from projectSubdirOf) inside `root`. */
+export function checkoutFolder(root, subdir) {
+  return subdir ? join(root, ...subdir.split('/')) : root;
+}

package/src/runtime/shared/worktrees/registry.mjs

@@ -0,0 +1,110 @@
+/**
+ * Durable registry of managed worktrees: <dataDir>/worktrees-v1/registry.json.
+ *
+ * One record per worktree, keyed by its slug (globally unique, so an entry id
+ * alone addresses it). A record carries the public entry fields plus the
+ * transaction ledger that makes creation rollback and deletion resumable:
+ * which resources this transaction created ('pending' is written before a
+ * resource is made, 'created' after), the deletion decision and any recovery
+ * diagnostics. Writes are atomic (temp file + rename) under a file lock; an
+ * unreadable registry is an error, never silently replaced.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseJsonText, withFileLock, writeJsonAtomicAsync } from '../atomic-file.mjs';
+import { isPlainObject } from '../object.mjs';
+import { resolvePluginData } from '../plugin-paths.mjs';
+import { normalizeWorktreeEntry, WORKTREE_STORE_DIR } from './contract.mjs';
+
+const REGISTRY_VERSION = 1;
+
+function worktreeStoreDir() {
+  return join(resolvePluginData(), WORKTREE_STORE_DIR);
+}
+
+export function registryPath() {
+  return join(worktreeStoreDir(), 'registry.json');
+}
+
+function emptyDoc() {
+  return { version: REGISTRY_VERSION, entries: {} };
+}
+
+async function readDoc(path) {
+  let text;
+  try {
+    text = await readFile(path, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return emptyDoc();
+    throw error;
+  }
+  const value = parseJsonText(text);
+  if (!isPlainObject(value) || !isPlainObject(value.entries)) {
+    throw new Error(`Worktree registry ${path} is malformed.`);
+  }
+  return value;
+}
+
+/** Snapshot of every record (plain clones). */
+export async function readRegistry() {
+  return readDoc(registryPath());
+}
+
+/**
+ * Locked read-modify-write. `mutate(doc)` edits doc.entries in place; its
+ * return value is returned.
+ * @template T
+ * @param {(doc: { version: number, entries: Record<string, any> }) => T} mutate
+ * @returns {Promise<T>}
+ */
+export async function mutateRegistry(mutate) {
+  const path = registryPath();
+  return withFileLock(
+    `${path}.lock`,
+    async () => {
+      const doc = await readDoc(path);
+      const result = mutate(doc);
+      await writeJsonAtomicAsync(path, doc, { lock: false });
+      return result;
+    },
+    { timeoutMs: 15_000 }
+  );
+}
+
+export async function getRecord(id) {
+  const doc = await readRegistry();
+  return Object.hasOwn(doc.entries, id) ? doc.entries[id] : null;
+}
+
+/** Insert a new record; false when the id is already taken. */
+export function insertRecord(record) {
+  return mutateRegistry((doc) => {
+    if (Object.hasOwn(doc.entries, record.id)) return false;
+    doc.entries[record.id] = { ...record, updatedAt: Date.now() };
+    return true;
+  });
+}
+
+export function putRecord(record) {
+  return mutateRegistry((doc) => {
+    doc.entries[record.id] = { ...record, updatedAt: Date.now() };
+  });
+}
+
+export function deleteRecord(id) {
+  return mutateRegistry((doc) => {
+    delete doc.entries[id];
+  });
+}
+
+/** Public shape: the contract entry plus the merge target and warnings. */
+export function entryView(record) {
+  return {
+    ...normalizeWorktreeEntry(record),
+    // Repository-relative folder of a subfolder Project ('' at the root).
+    projectSubdir: typeof record.projectSubdir === 'string' ? record.projectSubdir : '',
+    mergeTarget: record.mergeTarget ?? null,
+    warnings: Array.isArray(record.warnings) ? [...record.warnings] : [],
+    disposable: record.disposable === true,
+  };
+}

package/src/runtime/shared/worktrees/settings.mjs

@@ -0,0 +1,84 @@
+/**
+ * Worktree settings, persisted at agent config `worktree`. Defaults live in
+ * code; the stored section holds only what the user changed.
+ */
+import { isPlainObject } from '../object.mjs';
+import { DEFAULT_WORKTREE_BRANCH_PREFIX } from './contract.mjs';
+
+/** `branch`: new tasks use the project folder's current branch (worktree off). */
+export const WORKTREE_NEW_TASK_DEFAULTS = Object.freeze(['branch', 'worktree']);
+
+/**
+ * @typedef {object} WorktreeSettings
+ * @property {'branch'|'worktree'} newTaskDefault
+ * @property {string} branchPrefix Ref prefix for created branches; ends with "/".
+ * @property {number} sizeWarnBytes Repository size that asks for confirmation; 0 never asks.
+ * @property {boolean} autoCleanup Remove clean, merged worktrees when their session ends.
+ */
+
+/** @type {Readonly<WorktreeSettings>} */
+export const WORKTREE_SETTINGS_DEFAULTS = Object.freeze({
+  newTaskDefault: 'branch',
+  branchPrefix: DEFAULT_WORKTREE_BRANCH_PREFIX,
+  sizeWarnBytes: 2 * 1024 ** 3,
+  autoCleanup: true,
+});
+
+const KEYS = Object.keys(WORKTREE_SETTINGS_DEFAULTS);
+const PREFIX_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*(\/[A-Za-z0-9][A-Za-z0-9._-]*)*\/$/;
+
+/** Why `value` cannot be stored for `key`, or null. */
+function fieldError(key, value) {
+  switch (key) {
+    case 'newTaskDefault':
+      return WORKTREE_NEW_TASK_DEFAULTS.includes(value)
+        ? null
+        : `must be one of ${WORKTREE_NEW_TASK_DEFAULTS.join(', ')}`;
+    case 'branchPrefix':
+      return typeof value === 'string' &&
+        value.length <= 64 &&
+        PREFIX_PATTERN.test(value) &&
+        !value.includes('..') &&
+        !/\.lock\//i.test(value)
+        ? null
+        : 'must be a ref path ending with "/", e.g. "mixdog/"';
+    case 'sizeWarnBytes':
+      return Number.isSafeInteger(value) && value >= 0 ? null : 'must be a non-negative integer';
+    case 'autoCleanup':
+      return typeof value === 'boolean' ? null : 'must be a boolean';
+    default:
+      return 'is not a worktree setting';
+  }
+}
+
+/**
+ * Effective settings from the stored section. Invalid stored values fall back
+ * to their default so a hand edit never breaks boot.
+ * @param {unknown} stored
+ * @returns {WorktreeSettings}
+ */
+export function normalizeWorktreeSettings(stored) {
+  const source = isPlainObject(stored) ? stored : {};
+  const settings = { ...WORKTREE_SETTINGS_DEFAULTS };
+  for (const key of KEYS) {
+    if (Object.hasOwn(source, key) && fieldError(key, source[key]) === null) settings[key] = source[key];
+  }
+  return settings;
+}
+
+/**
+ * Apply a user patch strictly: unknown keys and invalid values throw.
+ * @param {unknown} current Stored or effective settings.
+ * @param {Partial<WorktreeSettings>} patch
+ * @returns {WorktreeSettings}
+ */
+export function applyWorktreeSettingsPatch(current, patch) {
+  if (!isPlainObject(patch) || !Object.keys(patch).length) {
+    throw new TypeError('worktree settings require at least one setting.');
+  }
+  for (const [key, value] of Object.entries(patch)) {
+    const error = fieldError(key, value);
+    if (error) throw new TypeError(`worktree.${key} ${error}.`);
+  }
+  return { ...normalizeWorktreeSettings(current), ...patch };
+}

package/src/runtime/shared/worktrees/slug.mjs

@@ -0,0 +1,62 @@
+/**
+ * Local worktree slug generator: a short, Windows-safe folder name and branch
+ * suffix derived from the task's first message, made unique on demand.
+ */
+import { randomBytes } from 'node:crypto';
+import { worktreeNameError } from './contract.mjs';
+
+export const SLUG_MAX_LENGTH = 40;
+const FALLBACK_SLUG = 'task';
+// DOS device names stay reserved on Windows, even with an extension.
+const WINDOWS_RESERVED = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])$/i;
+
+function trimSlug(value, max) {
+  return value.slice(0, max).replace(/-+$/, '');
+}
+
+/**
+ * @param {unknown} hint Free text, typically the first user message.
+ * @returns {string} Lowercase [a-z0-9-], at most SLUG_MAX_LENGTH characters.
+ */
+export function slugFromHint(hint) {
+  const words = String(hint ?? '')
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+  let slug = '';
+  for (const word of words) {
+    const next = slug ? `${slug}-${word}` : word;
+    if (next.length > SLUG_MAX_LENGTH) {
+      if (!slug) slug = trimSlug(word, SLUG_MAX_LENGTH);
+      break;
+    }
+    slug = next;
+  }
+  if (!slug) slug = FALLBACK_SLUG;
+  if (WINDOWS_RESERVED.test(slug)) slug = `${slug}-${FALLBACK_SLUG}`;
+  return slug;
+}
+
+/**
+ * First of base, base-2, base-3, … that `isTaken` rejects, then a random
+ * suffix. Every candidate passes worktreeNameError.
+ * @param {string} base
+ * @param {(slug: string) => boolean} isTaken
+ */
+export function uniqueSlug(base, isTaken) {
+  const root = worktreeNameError(base) ? FALLBACK_SLUG : base;
+  for (let attempt = 1; attempt <= 50; attempt++) {
+    const suffix = attempt === 1 ? '' : `-${attempt}`;
+    const candidate = `${trimSlug(root, SLUG_MAX_LENGTH - suffix.length)}${suffix}`;
+    if (!worktreeNameError(candidate) && !isTaken(candidate)) return candidate;
+  }
+  for (;;) {
+    const suffix = `-${randomBytes(4).toString('hex')}`;
+    const candidate = `${trimSlug(root, SLUG_MAX_LENGTH - suffix.length)}${suffix}`;
+    if (!isTaken(candidate)) return candidate;
+  }
+}

package/src/runtime/shared/worktrees/test-support.mjs

@@ -0,0 +1,96 @@
+// Temporary git repositories and data dirs for the worktree suites.
+import { execFileSync } from 'node:child_process';
+import { chmodSync, mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+const created = [];
+
+export function tempDir(prefix = 'mixdog-wt-') {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  created.push(dir);
+  return dir;
+}
+
+export function cleanupTempDirs() {
+  for (const dir of created.splice(0)) {
+    try {
+      rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
+    } catch {
+      /* best effort */
+    }
+  }
+}
+
+const GIT_ENV = { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_EDITOR: 'true' };
+for (const name of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE']) delete GIT_ENV[name];
+
+export function git(cwd, ...args) {
+  return execFileSync('git', args, {
+    cwd,
+    env: GIT_ENV,
+    encoding: 'utf8',
+    windowsHide: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+}
+
+export function writeFile(root, rel, content) {
+  const path = join(root, ...rel.split('/'));
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content);
+  return path;
+}
+
+/** A git hook script; outside Windows git skips a hook without the executable bit. */
+export function writeHook(root, name, script) {
+  const path = writeFile(root, `.git/hooks/${name}`, script);
+  chmodSync(path, 0o755);
+  return path;
+}
+
+export function commitFile(cwd, rel, content, message = `edit ${rel}`) {
+  writeFile(cwd, rel, content);
+  git(cwd, 'add', '--', rel);
+  git(cwd, 'commit', '-q', '-m', message);
+  return git(cwd, 'rev-parse', 'HEAD');
+}
+
+/** A repository on `main` with one commit. */
+export function makeRepo({ commit = true } = {}) {
+  const dir = tempDir('mixdog-wt-repo-');
+  git(dir, 'init', '-q', '-b', 'main');
+  git(dir, 'config', 'user.name', 'Mixdog Test');
+  git(dir, 'config', 'user.email', 'mixdog@example.com');
+  git(dir, 'config', 'core.autocrlf', 'false');
+  if (commit) commitFile(dir, 'README.md', 'hello\n', 'initial');
+  return dir;
+}
+
+/** Point the data dir at a fresh temp dir; returns it. */
+export function useTempDataDir() {
+  const dir = tempDir('mixdog-wt-data-');
+  process.env.MIXDOG_DATA_DIR = dir;
+  return dir;
+}
+
+let idCounter = 0;
+
+/** Fresh session/runtime/transaction ids for one managed worktree. */
+export function nextIds() {
+  idCounter += 1;
+  return { sessionId: `session-${idCounter}`, runtimeToken: `token-${idCounter}`, txId: `tx-${idCounter}` };
+}
+
+/** createManagedWorktree with fresh ids; resolves { entry, sessionId, runtimeToken, txId, ...extra }. */
+export async function createTestWorktree(projectPath, extra = {}) {
+  const { createManagedWorktree } = await import('./manager.mjs');
+  const id = nextIds();
+  const entry = await createManagedWorktree({ projectPath, nameHint: 'Fix the login page', ...id, ...extra });
+  return { entry, ...id, ...extra };
+}
+
+/** The repository's branches under the default managed prefix. */
+export function prefixedBranches(repo) {
+  return git(repo, 'for-each-ref', '--format=%(refname:short)', 'refs/heads/mixdog/').split('\n').filter(Boolean);
+}