create-walle 0.9.21 → 0.9.23

package/template/claude-task-manager/git-utils.js

@@ -1,7 +1,276 @@
 'use strict';
-const { execFile } = require('child_process');
+const { execFile, spawn } = require('child_process');
 const path = require('path');
 
+const DEFAULT_GIT_TIMEOUT_MS = _positiveInt(process.env.CTM_GIT_TIMEOUT_MS, 15000);
+const DEFAULT_WORKTREE_CREATE_TIMEOUT_MS = Math.max(
+  DEFAULT_GIT_TIMEOUT_MS,
+  _positiveInt(process.env.CTM_WORKTREE_CREATE_TIMEOUT_MS, 120000)
+);
+const WORKTREE_CLEANUP_TIMEOUT_MS = Math.max(
+  DEFAULT_GIT_TIMEOUT_MS,
+  _positiveInt(process.env.CTM_WORKTREE_CLEANUP_TIMEOUT_MS, 60000)
+);
+const GIT_FORCE_KILL_DELAY_MS = 2500;
+
+function _positiveInt(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+}
+
+function _normalizeGitOptions(maxBuffer, options) {
+  if (maxBuffer && typeof maxBuffer === 'object') {
+    options = options || {};
+    return {
+      maxBuffer: maxBuffer.maxBuffer || 1024 * 1024 * 5,
+      timeoutMs: _positiveInt(maxBuffer.timeoutMs ?? options.timeoutMs, DEFAULT_GIT_TIMEOUT_MS),
+      operation: maxBuffer.operation || options.operation || '',
+      timeoutCode: maxBuffer.timeoutCode || options.timeoutCode || 'GIT_COMMAND_TIMEOUT',
+      cancelCode: maxBuffer.cancelCode || options.cancelCode || 'GIT_COMMAND_CANCELLED',
+      allowStdoutOnError: !!(maxBuffer.allowStdoutOnError || options.allowStdoutOnError),
+      signal: maxBuffer.signal || options.signal || null,
+      onProgress: typeof maxBuffer.onProgress === 'function' ? maxBuffer.onProgress : options.onProgress,
+      heartbeatMs: _positiveInt(maxBuffer.heartbeatMs ?? options.heartbeatMs, 1000),
+    };
+  }
+  options = options || {};
+  return {
+    maxBuffer: maxBuffer || 1024 * 1024 * 5,
+    timeoutMs: _positiveInt(options.timeoutMs, DEFAULT_GIT_TIMEOUT_MS),
+    operation: options.operation || '',
+    timeoutCode: options.timeoutCode || 'GIT_COMMAND_TIMEOUT',
+    cancelCode: options.cancelCode || 'GIT_COMMAND_CANCELLED',
+    allowStdoutOnError: !!options.allowStdoutOnError,
+    signal: options.signal || null,
+    onProgress: typeof options.onProgress === 'function' ? options.onProgress : null,
+    heartbeatMs: _positiveInt(options.heartbeatMs, 1000),
+  };
+}
+
+function _isExecTimeout(err) {
+  if (!err) return false;
+  if (err.timedOut === true) return true;
+  return err.killed === true
+    || err.code === 'ETIMEDOUT'
+    || err.signal === 'SIGTERM';
+}
+
+function _isExecCancelled(err) {
+  if (!err) return false;
+  return err.cancelled === true || err.name === 'AbortError';
+}
+
+function _gitCommandForMessage(args) {
+  return `git ${args.map(String).join(' ')}`;
+}
+
+function _wrapGitError(err, args, opts, stdout, stderr) {
+  const cancelled = _isExecCancelled(err);
+  const timedOut = !cancelled && _isExecTimeout(err);
+  const command = _gitCommandForMessage(args);
+  const rawMessage = String(stderr || stdout || err?.message || 'git command failed').trim();
+  const message = cancelled
+    ? `${opts.operation || command} was cancelled`
+    : timedOut
+    ? `${opts.operation || command} timed out after ${opts.timeoutMs}ms`
+    : (rawMessage || `${command} failed`);
+  const wrapped = new Error(message);
+  wrapped.code = cancelled ? opts.cancelCode : timedOut ? opts.timeoutCode : err?.code;
+  wrapped.originalCode = err?.code;
+  wrapped.signal = err?.signal;
+  wrapped.killed = err?.killed === true;
+  wrapped.timedOut = timedOut;
+  wrapped.cancelled = cancelled;
+  wrapped.timeoutMs = opts.timeoutMs;
+  wrapped.gitArgs = args.slice();
+  wrapped.gitCommand = command;
+  wrapped.stdout = stdout || '';
+  wrapped.stderr = stderr || '';
+  return wrapped;
+}
+
+function _emitGitProgress(onProgress, event) {
+  if (typeof onProgress !== 'function') return;
+  try {
+    onProgress(event);
+  } catch (_) {}
+}
+
+function _runGitSpawn(cwd, args, maxBuffer, options) {
+  const opts = _normalizeGitOptions(maxBuffer, options);
+  const command = _gitCommandForMessage(args);
+  return new Promise((resolve, reject) => {
+    const startedAt = Date.now();
+    let child = null;
+    let stdout = '';
+    let stderr = '';
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let lastOutput = '';
+    let lastOutputAt = startedAt;
+    let settled = false;
+    let timedOut = false;
+    let cancelled = false;
+    let bufferOverflow = false;
+    let timeoutTimer = null;
+    let heartbeatTimer = null;
+    let forceKillTimer = null;
+
+    function elapsedMs() {
+      return Date.now() - startedAt;
+    }
+
+    function progress(extra) {
+      _emitGitProgress(opts.onProgress, {
+        type: 'heartbeat',
+        status: cancelled ? 'cancelling' : 'running',
+        operation: opts.operation || command,
+        gitCommand: command,
+        gitArgs: args.slice(),
+        pid: child && child.pid,
+        startedAt,
+        elapsedMs: elapsedMs(),
+        quietMs: Date.now() - lastOutputAt,
+        lastOutputAt,
+        lastOutput,
+        ...(extra || {}),
+      });
+    }
+
+    function cleanupListeners() {
+      if (timeoutTimer) clearTimeout(timeoutTimer);
+      if (heartbeatTimer) clearInterval(heartbeatTimer);
+      if (forceKillTimer) clearTimeout(forceKillTimer);
+      if (opts.signal && abortListener) {
+        try { opts.signal.removeEventListener('abort', abortListener); } catch (_) {}
+      }
+    }
+
+    function finish(err) {
+      if (settled) return;
+      settled = true;
+      cleanupListeners();
+      if (err) reject(err);
+      else resolve(stdout);
+    }
+
+    function killChild(reason) {
+      if (!child || child.killed) return;
+      progress({
+        type: reason || 'kill',
+        status: cancelled ? 'cancelling' : timedOut ? 'timeout' : 'running',
+        message: cancelled ? 'Cancel requested; stopping git checkout.' : timedOut ? 'Checkout exceeded the safety timeout; stopping git.' : 'Stopping git.',
+      });
+      try { child.kill('SIGTERM'); } catch (_) {}
+      forceKillTimer = setTimeout(() => {
+        if (!settled && child && !child.killed) {
+          try { child.kill('SIGKILL'); } catch (_) {}
+        }
+      }, GIT_FORCE_KILL_DELAY_MS);
+    }
+
+    const abortListener = () => {
+      cancelled = true;
+      killChild('cancel');
+    };
+
+    if (opts.signal && opts.signal.aborted) {
+      const err = _wrapGitError({ cancelled: true }, args, opts, stdout, stderr);
+      return finish(err);
+    }
+
+    try {
+      child = spawn('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (err) {
+      return finish(_wrapGitError(err, args, opts, stdout, stderr));
+    }
+
+    if (opts.signal) {
+      try { opts.signal.addEventListener('abort', abortListener, { once: true }); } catch (_) {}
+    }
+
+    progress({ type: 'start', message: `Started ${opts.operation || command}` });
+
+    function append(stream, chunk) {
+      if (settled) return;
+      const text = Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk || '');
+      const bytes = Buffer.byteLength(text);
+      if (stream === 'stdout') {
+        stdout += text;
+        stdoutBytes += bytes;
+      } else {
+        stderr += text;
+        stderrBytes += bytes;
+      }
+      const trimmed = text.trim();
+      if (trimmed) lastOutput = trimmed.split(/\r?\n/).slice(-1)[0].slice(0, 1000);
+      lastOutputAt = Date.now();
+      progress({ type: stream, stream, text: trimmed.slice(0, 2000), lastOutput });
+      if (stdoutBytes + stderrBytes > opts.maxBuffer) {
+        bufferOverflow = true;
+        killChild('maxBuffer');
+      }
+    }
+
+    child.stdout.on('data', chunk => append('stdout', chunk));
+    child.stderr.on('data', chunk => append('stderr', chunk));
+    child.on('error', err => finish(_wrapGitError(err, args, opts, stdout, stderr)));
+    child.on('close', (code, signal) => {
+      if (bufferOverflow) {
+        const err = new Error(`${opts.operation || command} exceeded output buffer`);
+        err.code = 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER';
+        err.signal = signal;
+        finish(_wrapGitError(err, args, opts, stdout, stderr));
+        return;
+      }
+      if (cancelled) {
+        const err = _wrapGitError({ cancelled: true, signal, killed: true }, args, opts, stdout, stderr);
+        finish(err);
+        return;
+      }
+      if (timedOut) {
+        const err = _wrapGitError({ timedOut: true, signal, killed: true }, args, opts, stdout, stderr);
+        finish(err);
+        return;
+      }
+      if (code !== 0) {
+        const err = new Error(stderr || stdout || `${command} exited with code ${code}`);
+        err.code = code;
+        err.signal = signal;
+        finish(_wrapGitError(err, args, opts, stdout, stderr));
+        return;
+      }
+      progress({ type: 'complete', status: 'succeeded', message: `${opts.operation || command} completed` });
+      finish();
+    });
+
+    if (opts.timeoutMs > 0) {
+      timeoutTimer = setTimeout(() => {
+        timedOut = true;
+        killChild('timeout');
+      }, opts.timeoutMs);
+    }
+    if (opts.heartbeatMs > 0) {
+      heartbeatTimer = setInterval(() => {
+        if (!settled) progress({ type: 'heartbeat' });
+      }, opts.heartbeatMs);
+      if (heartbeatTimer.unref) heartbeatTimer.unref();
+    }
+  });
+}
+
+function _runGit(cwd, args, maxBuffer, options) {
+  const opts = _normalizeGitOptions(maxBuffer, options);
+  return new Promise((resolve, reject) => {
+    execFile('git', args, { cwd, maxBuffer: opts.maxBuffer, timeout: opts.timeoutMs }, (err, stdout, stderr) => {
+      if (!err) return resolve(stdout);
+      const wrapped = _wrapGitError(err, args, opts, stdout, stderr);
+      if (opts.allowStdoutOnError && stdout && !wrapped.timedOut) return resolve(stdout);
+      reject(wrapped);
+    });
+  });
+}
+
 function _worktreeNamespace(options) {
   const raw = typeof options === 'string'
     ? options
@@ -16,11 +285,19 @@ function _worktreeParentDir(cwd, options) {
 }
 
 // Run a git command in a given project directory
-function git(cwd, args, maxBuffer = 1024 * 1024 * 5) {
-  return new Promise((resolve, reject) => {
-    execFile('git', args, { cwd, maxBuffer, timeout: 15000 }, (err, stdout, stderr) => {
-      if (err && !stdout) return reject(err);
-      resolve(stdout);
+function git(cwd, args, maxBuffer = 1024 * 1024 * 5, options) {
+  return _runGit(cwd, args, maxBuffer, { ...(options || {}), allowStdoutOnError: true });
+}
+
+function gitStrict(cwd, args, maxBuffer = 1024 * 1024 * 5, options) {
+  return _runGit(cwd, args, maxBuffer, options);
+}
+
+function gitExitCode(cwd, args, maxBuffer = 1024 * 1024 * 5) {
+  return new Promise((resolve) => {
+    const opts = _normalizeGitOptions(maxBuffer, {});
+    execFile('git', args, { cwd, maxBuffer: opts.maxBuffer, timeout: opts.timeoutMs }, (err) => {
+      resolve(err ? (_isExecTimeout(err) ? 124 : Number(err.code || 1)) : 0);
     });
   });
 }
@@ -142,6 +419,117 @@ async function getStagedDiff(cwd) {
   return parseDiff(raw);
 }
 
+// --- Stable per-repo git fact cache --------------------------------------
+// resolveMainBranch / getDefaultReviewBase / getDefaultDiffStat each spawn
+// 3-7 git subprocesses. A CPU profile of the live primary showed ~8.4s of
+// synchronous spawn() fork/exec prefix on the main loop over ~4 min — fanned
+// out by the Review tab/chooser polling these on demand AND the 30s
+// file-change sweep calling getDefaultDiffStat per project. The underlying
+// facts (main branch, merge-base, diff stat) are stable for seconds, so a
+// short per-cwd TTL cache collapses the fan-out. The IN-FLIGHT promise is
+// cached (not just the resolved value) so a burst of concurrent callers for
+// the same repo shares ONE git invocation. Disable with CTM_GIT_CACHE=0.
+const _GIT_CACHE_ENABLED = process.env.CTM_GIT_CACHE !== '0';
+function _ttlPromiseCache(ttlMs) {
+  const m = new Map(); // key -> { at, p }
+  const get = (key, producer) => {
+    if (!_GIT_CACHE_ENABLED || ttlMs <= 0) return Promise.resolve().then(producer);
+    const now = Date.now();
+    const e = m.get(key);
+    if (e && (now - e.at) < ttlMs) return e.p;
+    const p = Promise.resolve().then(producer);
+    m.set(key, { at: now, p });
+    // Drop the entry if the producer rejects so the next call retries instead
+    // of pinning a failed result for the whole TTL window.
+    p.catch(() => { const cur = m.get(key); if (cur && cur.p === p) m.delete(key); });
+    return p;
+  };
+  get.clear = () => m.clear();
+  return get;
+}
+const _MAIN_BRANCH_TTL_MS = Math.max(0, Number(process.env.CTM_GIT_MAIN_BRANCH_TTL_MS) || 60000);
+const _REVIEW_BASE_TTL_MS = Math.max(0, Number(process.env.CTM_GIT_REVIEW_BASE_TTL_MS) || 5000);
+const _DIFF_STAT_TTL_MS = Math.max(0, Number(process.env.CTM_GIT_DIFF_STAT_TTL_MS) || 3000);
+const _mainBranchCache = _ttlPromiseCache(_MAIN_BRANCH_TTL_MS);
+const _reviewBaseCache = _ttlPromiseCache(_REVIEW_BASE_TTL_MS);
+const _diffStatCache = _ttlPromiseCache(_DIFF_STAT_TTL_MS);
+// Drop cached facts (all repos) after an operation that changes branch/HEAD/
+// working tree so the next read reflects it immediately.
+function _invalidateGitFactCache() {
+  _mainBranchCache.clear(); _reviewBaseCache.clear(); _diffStatCache.clear();
+}
+
+// Resolve the repo's main branch: origin/HEAD target, else local main, else master.
+async function resolveMainBranch(cwd) {
+  return _mainBranchCache(cwd || '', () => _resolveMainBranchUncached(cwd));
+}
+async function _resolveMainBranchUncached(cwd) {
+  const originHead = await _gitSafe(cwd, ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD']);
+  if (originHead) {
+    const b = originHead.replace(/^origin\//, '').trim();
+    if (b) return b;
+  }
+  for (const cand of ['main', 'master']) {
+    if (await _gitSafe(cwd, ['rev-parse', '--verify', '--quiet', cand])) return cand;
+  }
+  return 'main';
+}
+
+// Decide the default review base for a project (the PR-style "all branch work" model):
+//   - on a branch ahead of / diverged from main → diff working tree vs merge-base(main, HEAD)
+//   - on main / detached / no main → all uncommitted work (vs HEAD)
+// Returns { kind:'vs-main'|'uncommitted', sentinel, ref, mainBranch, mergeBase }.
+// `sentinel` is the value the client puts in crState.baseRef; `ref` is the concrete git ref.
+async function getDefaultReviewBase(cwd) {
+  return _reviewBaseCache(cwd || '', () => _getDefaultReviewBaseUncached(cwd));
+}
+async function _getDefaultReviewBaseUncached(cwd) {
+  const mainBranch = await resolveMainBranch(cwd);
+  const head = await _gitSafe(cwd, ['rev-parse', 'HEAD']);
+  const mainSha = await _gitSafe(cwd, ['rev-parse', '--verify', '--quiet', mainBranch]);
+  if (head && mainSha && head !== mainSha) {
+    const mergeBase = await _gitSafe(cwd, ['merge-base', mainBranch, 'HEAD']);
+    if (mergeBase && mergeBase !== head) {
+      return { kind: 'vs-main', sentinel: '--vs-main', ref: mergeBase, mainBranch, mergeBase };
+    }
+  }
+  return { kind: 'uncommitted', sentinel: '--uncommitted', ref: 'HEAD', mainBranch, mergeBase: null };
+}
+
+// Working tree vs an arbitrary ref (merge-base SHA or HEAD) — includes committed +
+// staged + unstaged relative to that ref. Distinct from getFullDiff's commit mode,
+// which shows a single commit's parent..commit diff.
+async function getDiffVsRef(cwd, ref) {
+  const raw = await git(cwd, ['diff', '--relative', '-U5', ref]);
+  return parseDiff(raw);
+}
+async function getDiffStatVsRef(cwd, ref) {
+  const out = await git(cwd, ['diff', '--relative', '--stat', '--numstat', ref]);
+  return parseNumstat(out);
+}
+
+// Diff-stat for the default review base (used so the chooser badge matches what opens).
+async function getDefaultDiffStat(cwd) {
+  return _diffStatCache(cwd || '', () => _getDefaultDiffStatUncached(cwd));
+}
+async function _getDefaultDiffStatUncached(cwd) {
+  const base = await getDefaultReviewBase(cwd);
+  const files = await getDiffStatVsRef(cwd, base.ref);
+  return { base, files };
+}
+
+// Read a file's full contents for the "new" side of a diff, so the UI can expand context
+// lines hidden between hunks. For a commit SHA base the new side is the file at that commit;
+// for staged it's the index version; otherwise (working tree / vs-main / uncommitted) it's
+// the current working-tree file on disk.
+async function getFileAtRef(cwd, relPath, ref) {
+  if (relPath.includes('..') || relPath.startsWith('/')) throw new Error('invalid path');
+  if (ref && /^[0-9a-f]{7,40}$/.test(ref)) return git(cwd, ['show', `${ref}:${relPath}`]);
+  if (ref === '--staged') return git(cwd, ['show', `:${relPath}`]);
+  const fs = require('fs'); const path = require('path');
+  return fs.promises.readFile(path.join(cwd, relPath), 'utf8');
+}
+
 // Parse unified diff format into structured data
 function parseDiff(raw) {
   const files = [];
@@ -305,6 +693,144 @@ async function _branchExists(cwd, branch) {
   }
 }
 
+function _formatDuration(ms) {
+  if (ms >= 1000 && ms % 1000 === 0) return `${ms / 1000}s`;
+  if (ms >= 1000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${ms}ms`;
+}
+
+async function _cleanupPartialWorktree(cwd, worktreePath, branchName, options = {}) {
+  const fs = require('fs');
+  const cleanup = {
+    attempted: true,
+    worktreeRemoved: false,
+    pathRemoved: false,
+    pathAlreadyGone: false,
+    pruned: false,
+    branchDeleted: false,
+    errors: [],
+  };
+
+  await new Promise(resolve => setTimeout(resolve, 150));
+
+  try {
+    await gitStrict(cwd, ['worktree', 'remove', '--force', worktreePath], 1024 * 1024, {
+      timeoutMs: WORKTREE_CLEANUP_TIMEOUT_MS,
+      operation: `cleanup partial worktree ${worktreePath}`,
+    });
+    cleanup.worktreeRemoved = true;
+  } catch (e) {
+    const notRegistered = /not a working tree|is not a working tree/i.test(String(e.message || ''));
+    if (fs.existsSync(worktreePath)) {
+      try {
+        fs.rmSync(worktreePath, { recursive: true, force: true });
+        cleanup.pathRemoved = true;
+      } catch (rmErr) {
+        cleanup.errors.push(`path remove: ${rmErr.message}`);
+      }
+    } else {
+      cleanup.pathAlreadyGone = true;
+    }
+    if (!notRegistered) {
+      cleanup.errors.push(`worktree remove: ${e.message}`);
+    }
+  }
+
+  try {
+    await gitStrict(cwd, ['worktree', 'prune'], 1024 * 1024, {
+      timeoutMs: WORKTREE_CLEANUP_TIMEOUT_MS,
+      operation: 'prune partial worktree metadata',
+    });
+    cleanup.pruned = true;
+  } catch (e) {
+    cleanup.errors.push(`worktree prune: ${e.message}`);
+  }
+
+  if (options.deleteBranch && branchName && await _branchExists(cwd, branchName)) {
+    try {
+      await gitStrict(cwd, ['branch', '-D', branchName], 1024 * 1024, {
+        timeoutMs: WORKTREE_CLEANUP_TIMEOUT_MS,
+        operation: `delete partial worktree branch ${branchName}`,
+      });
+      cleanup.branchDeleted = true;
+    } catch (e) {
+      cleanup.errors.push(`branch delete: ${e.message}`);
+    }
+  }
+
+  return cleanup;
+}
+
+async function _gitWorktreeAdd(cwd, args, context) {
+  const timeoutMs = _positiveInt(context?.timeoutMs, DEFAULT_WORKTREE_CREATE_TIMEOUT_MS);
+  const onProgress = typeof context?.onProgress === 'function' ? context.onProgress : null;
+  const branchName = context?.branchName || '';
+  const worktreePath = context?.worktreePath || '';
+  _emitGitProgress(onProgress, {
+    stage: 'git_worktree_add',
+    status: 'running',
+    branch: branchName,
+    worktreePath,
+    message: `Starting git worktree checkout for "${branchName}".`,
+  });
+  try {
+    await _runGitSpawn(cwd, args, 1024 * 1024 * 5, {
+      timeoutMs,
+      operation: `create worktree ${branchName || ''}`.trim(),
+      timeoutCode: 'WORKTREE_CREATE_TIMEOUT',
+      cancelCode: 'WORKTREE_CREATE_CANCELLED',
+      signal: context?.signal,
+      heartbeatMs: context?.heartbeatMs || 1000,
+      onProgress: (event) => _emitGitProgress(onProgress, {
+        stage: 'git_worktree_add',
+        branch: branchName,
+        worktreePath,
+        ...event,
+      }),
+    });
+  } catch (e) {
+    e.stage = 'git_worktree_add';
+    e.branch = branchName;
+    e.worktreePath = worktreePath;
+    if (e.code === 'WORKTREE_CREATE_CANCELLED' || e.cancelled) {
+      e.code = 'WORKTREE_CREATE_CANCELLED';
+      e.statusCode = 499;
+      e.cleanup = await _cleanupPartialWorktree(cwd, e.worktreePath, e.branch, {
+        deleteBranch: !!context?.deleteCreatedBranch,
+      });
+      e.message = `Worktree creation was cancelled while checking out "${e.branch}".`;
+      e.message += e.cleanup?.errors?.length
+        ? ' CTM attempted cleanup, but cleanup was incomplete; run Worktrees > Prune if the branch/path remains.'
+        : ' CTM cleaned up the partial checkout; retrying is safe.';
+    }
+    if (e.code === 'WORKTREE_CREATE_TIMEOUT' || e.timedOut) {
+      e.code = 'WORKTREE_CREATE_TIMEOUT';
+      e.statusCode = 504;
+      e.timeoutMs = timeoutMs;
+      e.cleanup = await _cleanupPartialWorktree(cwd, e.worktreePath, e.branch, {
+        deleteBranch: !!context?.deleteCreatedBranch,
+      });
+      e.message = `Worktree creation timed out after ${_formatDuration(timeoutMs)} while checking out "${e.branch}".`;
+      e.message += e.cleanup?.errors?.length
+        ? ' CTM attempted cleanup, but cleanup was incomplete; run Worktrees > Prune if the branch/path remains.'
+        : ' CTM cleaned up the partial checkout; retrying is safe.';
+    }
+    throw e;
+  }
+}
+
+function _abortError(message) {
+  const err = new Error(message || 'Worktree creation was cancelled.');
+  err.code = 'WORKTREE_CREATE_CANCELLED';
+  err.cancelled = true;
+  err.statusCode = 499;
+  return err;
+}
+
+function _throwIfAborted(signal) {
+  if (signal && signal.aborted) throw _abortError();
+}
+
 // Create or attach to a worktree. The user shouldn't be blocked when a
 // worktree at this name already exists from a prior session — they almost
 // always want to reuse it. Behavior:
@@ -322,9 +848,21 @@ async function createWorktree(cwd, name, baseBranch, options) {
   }
   const base = baseBranch || 'HEAD';
   const namespace = _worktreeNamespace(options);
+  const createTimeoutMs = _positiveInt(options?.createTimeoutMs, DEFAULT_WORKTREE_CREATE_TIMEOUT_MS);
+  const signal = options?.signal || null;
+  const onProgress = typeof options?.onProgress === 'function' ? options.onProgress : null;
+  const emitProgress = (event) => _emitGitProgress(onProgress, {
+    stage: event?.stage || 'create_worktree',
+    status: event?.status || 'running',
+    requestedName: name,
+    namespace,
+    ...(event || {}),
+  });
+  _throwIfAborted(signal);
   const parentDir = _worktreeParentDir(cwd, namespace);
   fs.mkdirSync(parentDir, { recursive: true });
 
+  emitProgress({ stage: 'scan_existing', message: 'Inspecting existing worktrees and branches.' });
   const worktrees = await listWorktrees(cwd).catch(() => []);
   const _real = (p) => { try { return fs.realpathSync(p); } catch (_) { return p; } };
 
@@ -333,6 +871,13 @@ async function createWorktree(cwd, name, baseBranch, options) {
   const initialReal = _real(initialPath);
   const existingAtPath = worktrees.find(w => _real(w.path) === initialReal);
   if (existingAtPath && existingAtPath.branch === name) {
+    emitProgress({
+      stage: 'reuse_existing',
+      status: 'succeeded',
+      branch: existingAtPath.branch,
+      worktreePath: existingAtPath.path,
+      message: `Reusing existing worktree "${name}".`,
+    });
     return { path: existingAtPath.path, branch: existingAtPath.branch, reused: true, namespace };
   }
 
@@ -340,12 +885,28 @@ async function createWorktree(cwd, name, baseBranch, options) {
   // was removed but its branch was kept.
   if (!existingAtPath && !fs.existsSync(initialPath) && await _branchExists(cwd, name)
       && !worktrees.some(w => w.branch === name)) {
-    await git(cwd, ['worktree', 'add', initialPath, name]);
+    _throwIfAborted(signal);
+    await _gitWorktreeAdd(cwd, ['worktree', 'add', initialPath, name], {
+      timeoutMs: createTimeoutMs,
+      branchName: name,
+      worktreePath: initialPath,
+      deleteCreatedBranch: false,
+      signal,
+      onProgress: emitProgress,
+    });
+    emitProgress({
+      stage: 'attach_existing_branch',
+      status: 'succeeded',
+      branch: name,
+      worktreePath: initialPath,
+      message: `Attached worktree to existing branch "${name}".`,
+    });
     return { path: initialPath, branch: name, attached: true, namespace };
   }
 
   // Pick a free (path, branch) pair. Suffix until both slots are clear.
   for (let attempt = 1; attempt <= 20; attempt++) {
+    _throwIfAborted(signal);
     const candidateName = attempt === 1 ? name : `${name}-${attempt}`;
     const candidatePath = path.join(parentDir, candidateName);
     const candidateReal = _real(candidatePath);
@@ -353,7 +914,21 @@ async function createWorktree(cwd, name, baseBranch, options) {
     const branchInUse = await _branchExists(cwd, candidateName);
     const pathOnDisk = fs.existsSync(candidatePath);
     if (pathInUse || branchInUse || pathOnDisk) continue;
-    await git(cwd, ['worktree', 'add', '-b', candidateName, candidatePath, base]);
+    await _gitWorktreeAdd(cwd, ['worktree', 'add', '-b', candidateName, candidatePath, base], {
+      timeoutMs: createTimeoutMs,
+      branchName: candidateName,
+      worktreePath: candidatePath,
+      deleteCreatedBranch: true,
+      signal,
+      onProgress: emitProgress,
+    });
+    emitProgress({
+      stage: 'create_branch',
+      status: 'succeeded',
+      branch: candidateName,
+      worktreePath: candidatePath,
+      message: `Created worktree "${candidateName}".`,
+    });
     return {
       path: candidatePath,
       branch: candidateName,
@@ -412,6 +987,105 @@ async function mergeWorktree(cwd, branchName, targetBranch, strategy) {
   return { merged: true, branch: branchName, into: targetBranch };
 }
 
+function _oneLineCommitMessage(message, fallback) {
+  const value = String(message || fallback || 'Finish local work')
+    .replace(/[\r\n]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 180);
+  return value || 'Finish local work';
+}
+
+async function commitWorktreeChanges(worktreePath, message) {
+  const status = String(await gitStrict(worktreePath, ['status', '--porcelain=v1', '--untracked-files=all']) || '');
+  if (!status.trim()) {
+    return { committed: false, dirty: false };
+  }
+  await gitStrict(worktreePath, [
+    'add', '-A', '--', '.',
+    ':(exclude).claude/worktrees',
+    ':(exclude).claude/worktrees/**',
+    ':(exclude).walle/worktrees',
+    ':(exclude).walle/worktrees/**',
+  ]);
+  const stagedExit = await gitExitCode(worktreePath, ['diff', '--cached', '--quiet']);
+  if (stagedExit === 0) {
+    return { committed: false, dirty: true, ignoredOnly: true };
+  }
+  if (stagedExit !== 1) {
+    throw new Error('Could not inspect staged worktree changes before committing.');
+  }
+  const subject = _oneLineCommitMessage(message, 'Finish local work');
+  await gitStrict(worktreePath, ['commit', '-m', subject]);
+  const commit = String(await gitStrict(worktreePath, ['rev-parse', '--short', 'HEAD']) || '').trim();
+  return { committed: true, dirty: true, commit, message: subject };
+}
+
+async function _findWorktreeForFinish(cwd, branchName, opts) {
+  const worktreePath = String(opts?.worktreePath || '').trim();
+  const wantedPath = worktreePath ? _realpath(worktreePath) : '';
+  const worktrees = await listWorktrees(cwd);
+  let wt = null;
+  if (wantedPath) {
+    wt = worktrees.find(item => _realpath(item.path) === wantedPath);
+  }
+  if (!wt && branchName) {
+    wt = worktrees.find(item => item.branch === branchName || item.worktreeName === branchName);
+  }
+  if (!wt && branchName === 'main') {
+    wt = worktrees.find(item => item.isMain);
+  }
+  if (!wt) throw new Error(`Worktree not found for branch: ${branchName || worktreePath}`);
+  return wt;
+}
+
+async function finishWorktree(cwd, branchName, opts) {
+  opts = opts || {};
+  const targetBranch = opts.targetBranch || 'main';
+  const strategy = opts.strategy;
+  const commitDirty = opts.commitDirty !== false;
+  const wt = await _findWorktreeForFinish(cwd, branchName, opts);
+  const branch = wt.branch || branchName || await getBranch(wt.path);
+  if (!branch || branch === 'HEAD') throw new Error('Cannot finish a detached worktree from the phone. Recover a branch first.');
+
+  let commitResult = { committed: false, dirty: false };
+  const dirtyStatus = String(await gitStrict(wt.path, ['status', '--porcelain=v1', '--untracked-files=all']) || '');
+  if (dirtyStatus.trim()) {
+    if (!commitDirty) {
+      throw new Error('Worktree has uncommitted changes. Commit or stash before merging.');
+    }
+    commitResult = await commitWorktreeChanges(wt.path, opts.commitMessage || `Finish ${branch} work`);
+  }
+
+  if (branch === targetBranch) {
+    return {
+      merged: false,
+      alreadyMain: true,
+      branch,
+      into: targetBranch,
+      worktreePath: wt.path,
+      committed: !!commitResult.committed,
+      commit: commitResult.commit || '',
+      commitMessage: commitResult.message || '',
+    };
+  }
+
+  const pre = await mergeWorktreePreCheck(cwd, branch, targetBranch);
+  if (pre.conflicts) {
+    const err = new Error('Merge would have conflicts. Resolve manually.');
+    err.code = 'MERGE_CONFLICTS';
+    throw err;
+  }
+  const merged = await mergeWorktree(cwd, branch, targetBranch, strategy);
+  return {
+    ...merged,
+    worktreePath: wt.path,
+    committed: !!commitResult.committed,
+    commit: commitResult.commit || '',
+    commitMessage: commitResult.message || '',
+  };
+}
+
 // Remove a worktree and optionally delete its branch
 async function removeWorktree(cwd, worktreePath, deleteBranch) {
   // Get branch name before removing. Match tolerates /var ↔ /private/var
@@ -446,6 +1120,15 @@ async function removeWorktree(cwd, worktreePath, deleteBranch) {
   return { removed: true, path: worktreePath, branchDeleted };
 }
 
+// Delete a local branch. `-d` refuses to drop unmerged work; `force` uses `-D`.
+// Caller is responsible for ensuring the branch has no worktree and is not in use
+// by a live session. Throws on git failure (e.g. unmerged without force).
+async function deleteBranch(cwd, branchName, force) {
+  const flag = force ? '-D' : '-d';
+  await gitStrict(cwd, ['branch', flag, branchName]);
+  return { deleted: true, branch: branchName, forced: !!force };
+}
+
 // Best-effort realpath resolution — falls back to the input if it can't be
 // resolved (e.g. already deleted, permission issue).
 function _realpath(p) {
@@ -459,7 +1142,9 @@ function _realpath(p) {
 //   - isCanonical: path lives under an agent-owned <repo>/.claude|.walle/worktrees/<name>
 //   - isGhost: path contains /~/ corruption OR path doesn't exist on disk
 //   - ahead/behind vs mainBranch
-//   - dirtyFiles: count of modified+untracked
+//   - dirtyFiles: count of tracked dirty + untracked files
+//   - trackedDirtyFiles/untrackedFiles: split counts so untracked-only
+//     generated artifacts do not block safe sync from main
 //   - unmergedCommits: rev-list count main..HEAD (0 ⇒ safe to delete)
 //   - lastActivity: ISO timestamp of HEAD commit
 //   - summary: 1-line human-readable status
@@ -476,6 +1161,98 @@ async function _gitSafe(cwd, args, timeoutMs = 5000) {
   });
 }
 
+async function _gitSafeRaw(cwd, args, timeoutMs = 5000) {
+  return new Promise((resolve) => {
+    execFile('git', args, { cwd, timeout: timeoutMs, maxBuffer: 1024 * 1024 }, (err, stdout) => {
+      if (err) return resolve(null);
+      resolve(String(stdout || ''));
+    });
+  });
+}
+
+function _parsePorcelainStatusZ(out) {
+  const entries = String(out || '').split('\0').filter(Boolean);
+  const result = {
+    dirtyFiles: 0,
+    trackedDirtyFiles: 0,
+    untrackedFiles: 0,
+    ignoredFiles: 0,
+    unmergedFiles: 0,
+    stagedFiles: 0,
+    unstagedFiles: 0,
+    untrackedPaths: [],
+  };
+
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    if (entry.length < 3) continue;
+    const xy = entry.slice(0, 2);
+    const filePath = entry.slice(3);
+    if (xy === '??') {
+      result.untrackedFiles += 1;
+      result.untrackedPaths.push(filePath);
+      continue;
+    }
+    if (xy === '!!') {
+      result.ignoredFiles += 1;
+      continue;
+    }
+
+    result.trackedDirtyFiles += 1;
+    if (xy[0] && xy[0] !== ' ') result.stagedFiles += 1;
+    if (xy[1] && xy[1] !== ' ') result.unstagedFiles += 1;
+    if (xy.includes('U') || ['AA', 'DD'].includes(xy)) result.unmergedFiles += 1;
+    // In porcelain v1 -z, rename/copy records include the source path as a
+    // second NUL-terminated field. Skip it so one rename counts once.
+    if (xy[0] === 'R' || xy[0] === 'C') i += 1;
+  }
+
+  result.dirtyFiles = result.trackedDirtyFiles + result.untrackedFiles;
+  result.hasOnlyUntrackedFiles = result.untrackedFiles > 0 && result.trackedDirtyFiles === 0;
+  return result;
+}
+
+function _trackedDirtyCount(wt) {
+  if (!wt) return 0;
+  if (wt.trackedDirtyFiles != null) return Number(wt.trackedDirtyFiles || 0);
+  const dirty = Number(wt.dirtyFiles || 0);
+  const untracked = Number(wt.untrackedFiles || 0);
+  return Math.max(0, dirty - untracked);
+}
+
+function _hasOnlyUntrackedFiles(wt) {
+  if (!wt) return false;
+  const dirty = Number(wt.dirtyFiles || 0);
+  return dirty > 0 && _trackedDirtyCount(wt) === 0;
+}
+
+function _splitNulPaths(out) {
+  return String(out || '').split('\0').filter(Boolean);
+}
+
+function _pathsOverlap(a, b) {
+  const left = String(a || '').replace(/\/+$/, '');
+  const right = String(b || '').replace(/\/+$/, '');
+  if (!left || !right) return false;
+  return left === right || left.startsWith(right + '/') || right.startsWith(left + '/');
+}
+
+async function _untrackedSyncCollisions(worktreePath, targetBranch) {
+  const status = _parsePorcelainStatusZ(await _gitSafeRaw(worktreePath, ['status', '--porcelain=v1', '-uall', '-z']) || '');
+  if (status.trackedDirtyFiles > 0 || status.untrackedPaths.length === 0) {
+    return { status, collisions: [] };
+  }
+  const changedOut = await _gitSafeRaw(worktreePath, ['diff', '--name-only', '-z', 'HEAD', targetBranch], 8000);
+  const changedPaths = _splitNulPaths(changedOut);
+  if (changedPaths.length === 0) return { status, collisions: [] };
+  const collisions = [];
+  for (const untrackedPath of status.untrackedPaths) {
+    const hit = changedPaths.find(changedPath => _pathsOverlap(untrackedPath, changedPath));
+    if (hit) collisions.push({ untrackedPath, incomingPath: hit });
+  }
+  return { status, collisions };
+}
+
 function _checkpointRefSlug(branchName) {
   let slug = String(branchName || 'branch')
     .replace(/[^A-Za-z0-9._-]+/g, '-')
@@ -621,7 +1398,7 @@ function _classifyState(wt) {
   if (wt.isGhost) return 'ghost';
   if (wt.isMain) return 'primary';
   if (!wt.branch || wt.branch === 'HEAD') return 'detached';
-  if (wt.dirtyFiles > 0) return 'dirty';
+  if (_trackedDirtyCount(wt) > 0) return 'dirty';
   const ahead = wt.ahead || 0;
   const behind = wt.behind || 0;
   if (ahead > 0 && behind > 0) return 'diverged';
@@ -654,16 +1431,20 @@ function _buildSummary(wt) {
     return 'Primary worktree';
   }
   if (wt.state === 'detached') return 'Detached HEAD — commits here are at risk. Click Recover branch.';
+  const trackedDirty = _trackedDirtyCount(wt);
+  const untrackedFiles = Number(wt.untrackedFiles || 0);
   const parts = [];
   if (wt.ahead > 0) parts.push(`${wt.ahead} ahead`);
   if (wt.behind > 0) parts.push(`${wt.behind} behind`);
-  if (wt.dirtyFiles > 0) parts.push(`${wt.dirtyFiles} dirty`);
+  if (trackedDirty > 0) parts.push(`${trackedDirty} dirty`);
+  if (untrackedFiles > 0) parts.push(`${untrackedFiles} untracked`);
   if (parts.length === 0) return 'Clean — synced with main';
   let suffix = '';
   if (wt.state === 'ahead') suffix = ' — ready to merge';
   else if (wt.state === 'behind') suffix = ' — sync from main';
   else if (wt.state === 'diverged') suffix = ' — needs sync first';
   else if (wt.state === 'dirty') suffix = ' — commit or stash';
+  else if (wt.state === 'clean' && untrackedFiles > 0) suffix = ' — untracked files kept local';
   return parts.join(', ') + suffix;
 }
 
@@ -729,10 +1510,12 @@ function _recommendedAction(wt) {
     return { kind: 'primary', label: 'Primary', tone: 'neutral', reason: 'Main checkout.' };
   }
   if (!wt.branch || wt.branch === 'HEAD') return { kind: 'recover_branch', label: 'Recover branch', tone: 'danger', reason: 'Detached HEAD commits can become hard to find.' };
-  if (wt.dirtyFiles > 0) return { kind: 'review_dirty', label: 'Open session', tone: 'warning', reason: `${wt.dirtyFiles} uncommitted file(s).` };
+  const trackedDirty = _trackedDirtyCount(wt);
+  if (trackedDirty > 0) return { kind: 'review_dirty', label: 'Open session', tone: 'warning', reason: `${trackedDirty} tracked dirty file(s).` };
   if ((wt.ahead || 0) > 0 && (wt.behind || 0) > 0) return { kind: 'sync_branch', label: 'Sync first', tone: 'warning', reason: 'Branch has commits and is behind main.' };
   if ((wt.behind || 0) > 0) return { kind: 'sync_branch', label: 'Sync', tone: 'warning', reason: 'Branch is behind main.' };
   if ((wt.ahead || 0) > 0) return { kind: 'finish_work', label: 'Finish', tone: 'success', reason: 'Branch has committed work not on main.' };
+  if (_hasOnlyUntrackedFiles(wt)) return { kind: 'review_dirty', label: 'Open session', tone: 'warning', reason: `${wt.untrackedFiles || wt.dirtyFiles} untracked file(s).` };
   return { kind: 'cleanup', label: 'Clean up', tone: 'neutral', reason: 'No unmerged commits or dirty files.' };
 }
 
@@ -830,6 +1613,37 @@ async function syncWorktree(cwd, branchName, strategy, opts) {
       message: 'Worktree HEAD changed before sync could start.',
     };
   }
+  // Make sure main is up to date locally — try a fast-forward fetch but
+  // don't fail if there's no remote.
+  await _gitSafe(repoRoot, ['fetch', 'origin', 'main', '--quiet'], 8000);
+
+  // Pre-check for conflicts using merge-tree (git 2.38+).
+  const preCheck = await mergeWorktreePreCheck(repoRoot, 'main', branchName).catch(() => ({ conflicts: false }));
+  if (preCheck.conflicts) {
+    return { merged: false, conflicts: true, message: 'Merge would conflict — open the worktree in a terminal to resolve.' };
+  }
+
+  const syncSafety = await _untrackedSyncCollisions(wt.path, 'main');
+  if (syncSafety.status.trackedDirtyFiles > 0) {
+    return {
+      merged: false,
+      blocked: true,
+      code: 'TRACKED_DIRTY',
+      beforeHead,
+      message: 'Commit or stash tracked dirty files before syncing from main.',
+    };
+  }
+  if (syncSafety.collisions.length > 0) {
+    return {
+      merged: false,
+      blocked: true,
+      code: 'UNTRACKED_COLLISION',
+      beforeHead,
+      untrackedCollisions: syncSafety.collisions,
+      message: `Sync would overwrite untracked file(s): ${syncSafety.collisions.map(c => c.untrackedPath).slice(0, 3).join(', ')}`,
+    };
+  }
+
   let checkpointRef = '';
   if (opts.createCheckpoint) {
     checkpointRef = await _createWorktreeCheckpoint(repoRoot, branchName, beforeHead);
@@ -844,16 +1658,6 @@ async function syncWorktree(cwd, branchName, strategy, opts) {
     }
   }
 
-  // Make sure main is up to date locally — try a fast-forward fetch but
-  // don't fail if there's no remote.
-  await _gitSafe(repoRoot, ['fetch', 'origin', 'main', '--quiet'], 8000);
-
-  // Pre-check for conflicts using merge-tree (git 2.38+).
-  const preCheck = await mergeWorktreePreCheck(repoRoot, 'main', branchName).catch(() => ({ conflicts: false }));
-  if (preCheck.conflicts) {
-    return { merged: false, conflicts: true, message: 'Merge would conflict — open the worktree in a terminal to resolve.' };
-  }
-
   const args = strategy === 'rebase' ? ['rebase', 'main'] : ['merge', 'main', '--no-edit'];
   const out = await _gitSafe(wt.path, args, 30000);
   if (out === null) {
@@ -873,7 +1677,8 @@ function _syncAllEligibility(wt) {
   if (!wt || wt.isMain) return { eligible: false, reason: 'primary checkout' };
   if (wt.isGhost || wt.state === 'ghost') return { eligible: false, reason: 'ghost worktree' };
   if (!wt.branch || wt.branch === 'HEAD' || wt.state === 'detached') return { eligible: false, reason: 'detached HEAD' };
-  if ((wt.dirtyFiles || 0) > 0) return { eligible: false, reason: `${wt.dirtyFiles} dirty file(s)` };
+  const trackedDirty = _trackedDirtyCount(wt);
+  if (trackedDirty > 0) return { eligible: false, reason: `${trackedDirty} tracked dirty file(s)` };
   if ((wt.behind || 0) <= 0) return { eligible: false, reason: 'not behind main' };
   return { eligible: true, reason: '' };
 }
@@ -1058,7 +1863,7 @@ async function listRichWorktrees(cwd, opts) {
     // Gather status fields in parallel.
     const [revlist, statusOut, lastIso, unmergedOut] = await Promise.all([
       wt.branch ? _gitSafe(wt.path, ['rev-list', '--left-right', '--count', `${mainBranch}...${wt.branch}`]) : Promise.resolve(null),
-      _gitSafe(wt.path, ['status', '--porcelain']),
+      _gitSafeRaw(wt.path, ['status', '--porcelain=v1', '-uall', '-z']),
       _gitSafe(wt.path, ['log', '-1', '--format=%cI', 'HEAD']),
       wt.branch && !wt.isMain ? _gitSafe(wt.path, ['rev-list', '--count', `${mainBranch}..HEAD`]) : Promise.resolve('0'),
     ]);
@@ -1071,11 +1876,18 @@ async function listRichWorktrees(cwd, opts) {
         ahead = parseInt(parts[1], 10) || 0;
       }
     }
-    const dirtyFiles = statusOut ? statusOut.split('\n').filter(Boolean).length : 0;
+    const status = _parsePorcelainStatusZ(statusOut || '');
+    const dirtyFiles = status.dirtyFiles;
     const unmergedCommits = parseInt(unmergedOut, 10) || 0;
 
     const out = {
       ...wt, isGhost: false, isCanonical, ahead, behind, dirtyFiles, unmergedCommits,
+      trackedDirtyFiles: status.trackedDirtyFiles,
+      untrackedFiles: status.untrackedFiles,
+      unmergedFiles: status.unmergedFiles,
+      stagedFiles: status.stagedFiles,
+      unstagedFiles: status.unstagedFiles,
+      hasOnlyUntrackedFiles: status.hasOnlyUntrackedFiles,
       lastActivity: lastIso || null,
       lastActivityRel: _formatRelativeTime(lastIso),
       mainBranch,
@@ -1104,6 +1916,62 @@ async function listRichWorktrees(cwd, opts) {
   return enriched;
 }
 
+// Lean single-worktree status for ONE path — the fast counterpart to
+// listRichWorktrees(). Used by the on-turn-finish refresh so the sidebar
+// dirty/commit badge updates in ~seconds instead of waiting on the 30s
+// listRichWorktrees() fan-out (a documented CPU hog: ~4 git spawns PER worktree
+// across ~40 worktrees). This does those ~4 git calls for just the one worktree.
+// Computes only the fields the session worktree-status badge needs (live branch,
+// ahead/behind vs main, dirty counts, unmerged commits, state). Best-effort:
+// returns null if the path is missing or not a git worktree. mainRemote is a
+// stub here (only meaningful for the primary worktree, which never shows the
+// attention badge); callers needing remote state use listRichWorktrees().
+async function richWorktreeStatusForPath(worktreePath, opts = {}) {
+  const mainBranch = opts.mainBranch || 'main';
+  if (!worktreePath || _isGhostPath(worktreePath)) return null;
+  const branch = await _gitSafe(worktreePath, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  if (!branch) return null;
+  const detached = branch === 'HEAD';
+  const isMain = !detached && (branch === mainBranch || branch === 'main' || branch === 'master');
+  const [revlist, statusOut, lastIso, unmergedOut] = await Promise.all([
+    !detached ? _gitSafe(worktreePath, ['rev-list', '--left-right', '--count', `${mainBranch}...${branch}`]) : Promise.resolve(null),
+    _gitSafeRaw(worktreePath, ['status', '--porcelain=v1', '-uall', '-z']),
+    _gitSafe(worktreePath, ['log', '-1', '--format=%cI', 'HEAD']),
+    (!isMain && !detached) ? _gitSafe(worktreePath, ['rev-list', '--count', `${mainBranch}..HEAD`]) : Promise.resolve('0'),
+  ]);
+  let ahead = 0, behind = 0;
+  if (revlist) {
+    const parts = revlist.split(/\s+/).filter(Boolean);
+    if (parts.length >= 2) { behind = parseInt(parts[0], 10) || 0; ahead = parseInt(parts[1], 10) || 0; }
+  }
+  const status = _parsePorcelainStatusZ(statusOut || '');
+  const out = {
+    path: worktreePath,
+    worktreeName: path.basename(worktreePath || ''),
+    branch: detached ? '' : branch,
+    head: null,
+    isMain,
+    isGhost: false,
+    isCanonical: true,
+    ahead, behind,
+    dirtyFiles: status.dirtyFiles,
+    trackedDirtyFiles: status.trackedDirtyFiles,
+    untrackedFiles: status.untrackedFiles,
+    unmergedFiles: status.unmergedFiles,
+    stagedFiles: status.stagedFiles,
+    unstagedFiles: status.unstagedFiles,
+    hasOnlyUntrackedFiles: status.hasOnlyUntrackedFiles,
+    unmergedCommits: parseInt(unmergedOut, 10) || 0,
+    lastActivity: lastIso || null,
+    lastActivityRel: _formatRelativeTime(lastIso),
+    mainBranch,
+    mainRemote: { branch: mainBranch, remote: null, ahead: 0, behind: 0, state: 'unknown' },
+  };
+  out.state = _classifyState(out);
+  out.summary = _buildSummary(out);
+  return out;
+}
+
 // Get the list of unmerged commits between main and a worktree branch
 // (used by safe-delete and PR-body generation).
 async function getUnmergedCommitList(cwd, branchName, baseBranch) {
@@ -1175,13 +2043,15 @@ async function pushAndCreatePR(cwd, branchName, opts) {
 
 module.exports = {
   git, getCommits, getCommitLog, getBranch, getDiffStat, getFullDiff, getStagedDiff, parseDiff,
-  listWorktrees, createWorktree, mergeWorktreePreCheck, mergeWorktree, removeWorktree,
+  resolveMainBranch, getDefaultReviewBase, getDiffVsRef, getDiffStatVsRef, getDefaultDiffStat, getFileAtRef,
+  listWorktrees, createWorktree, mergeWorktreePreCheck, mergeWorktree, commitWorktreeChanges, finishWorktree, removeWorktree, deleteBranch,
   // Rich-status + new operations
-  listRichWorktrees, syncWorktree, syncAllWorktrees, pruneGhosts, recoverDetachedHead, recoverWorktree,
+  listRichWorktrees, richWorktreeStatusForPath, syncWorktree, syncAllWorktrees, pruneGhosts, recoverDetachedHead, recoverWorktree,
   getUnmergedCommitList, pushAndCreatePR,
   // Internal helpers exposed for tests
   _classifyState, _buildSummary, _isGhostPath, _isCanonicalPath, STATE_SORT_RANK,
   _classifyMainRemote, _recommendedAction, _syncAllEligibility, _sameWorktreePath,
   _parseGitHubRemoteUrl, _githubRemoteSpec, _buildGhPrCreateArgs,
   _worktreeNamespace, _worktreeParentDir, _checkpointRefName, _checkpointRefSlug,
+  _invalidateGitFactCache,
 };