@youtyan/code-viewer 0.6.2 → 0.6.3

package/dist/code-viewer.js

@@ -659,6 +659,175 @@ var init_annotations = __esm(() => {
   });
 });
 
+// web-src/server/command-resolver.ts
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
+import { dirname as dirname2, isAbsolute, join as join2, relative } from "node:path";
+function isExternalCommandName(value) {
+  return commandNameSet.has(value);
+}
+function parseExternalCommandOverride(raw, flag = "--bin", allowedNames = EXTERNAL_COMMAND_NAMES) {
+  const eq = raw.indexOf("=");
+  if (eq <= 0 || eq === raw.length - 1) {
+    return { ok: false, error: `${flag} requires <name>=<absolute-path>` };
+  }
+  const name = raw.slice(0, eq).trim();
+  const path = raw.slice(eq + 1);
+  if (!isExternalCommandName(name)) {
+    return {
+      ok: false,
+      error: `${flag} unsupported command: ${name}`
+    };
+  }
+  if (!allowedNames.includes(name)) {
+    return {
+      ok: false,
+      error: `${flag} unsupported command: ${name}`
+    };
+  }
+  return { ok: true, override: { name, path } };
+}
+function configureExternalCommands(opts) {
+  const env = opts.env ?? process.env;
+  const allowedNames = opts.allowedNames ?? EXTERNAL_COMMAND_NAMES;
+  const selected = new Map;
+  for (const name of allowedNames) {
+    const value = env[envNameForCommand(name)];
+    if (value)
+      selected.set(name, { path: value, source: "env" });
+  }
+  for (const override of opts.cliOverrides ?? []) {
+    if (!allowedNames.includes(override.name)) {
+      return {
+        ok: false,
+        error: `--bin unsupported command: ${override.name}`
+      };
+    }
+    selected.set(override.name, { path: override.path, source: "cli" });
+  }
+  if (selected.size === 0) {
+    activeOverrides.clear();
+    return { ok: true };
+  }
+  const roots = forbiddenExecutableRoots(opts.cwd);
+  if ("error" in roots)
+    return { ok: false, error: roots.error };
+  const resolved = new Map;
+  for (const [name, value] of selected) {
+    const validated = validateExecutablePath(value.path, roots.roots);
+    if ("error" in validated) {
+      return {
+        ok: false,
+        error: `${sourceLabel(value.source)} ${name}: ${validated.error}`
+      };
+    }
+    resolved.set(name, {
+      path: value.path,
+      realPath: validated.realPath,
+      source: value.source
+    });
+  }
+  activeOverrides.clear();
+  for (const [name, value] of resolved)
+    activeOverrides.set(name, value);
+  return { ok: true };
+}
+function commandForExternal(name) {
+  return activeOverrides.get(name)?.realPath ?? name;
+}
+function isCommandNotFoundResult(command, result) {
+  if (result.code === 0)
+    return false;
+  return isCommandNotFoundMessage(command, result.stderr || "");
+}
+function commandNotFoundDetail(command) {
+  const resolved = commandForExternal(command);
+  if (resolved === command)
+    return `${command} not found in PATH`;
+  return `${command} binary not found or not executable: ${resolved}`;
+}
+function envNameForCommand(name) {
+  return `CODE_VIEWER_BIN_${name.toUpperCase().replace(/-/g, "_")}`;
+}
+function sourceLabel(source) {
+  return source === "cli" ? "--bin" : "environment override";
+}
+function validateExecutablePath(raw, forbiddenRoots) {
+  if (!raw)
+    return { error: "path must not be empty" };
+  if (raw.includes("\x00") || /[\r\n]/.test(raw)) {
+    return { error: "path must be single-line and must not contain NUL" };
+  }
+  if (!isAbsolute(raw))
+    return { error: "path must be absolute" };
+  let realPath;
+  try {
+    realPath = realpathSync(raw);
+    const st = statSync(realPath);
+    if (!st.isFile())
+      return { error: "path must point to a file" };
+    accessSync(realPath, constants.X_OK);
+  } catch {
+    return { error: "path must point to an executable file" };
+  }
+  for (const root of forbiddenRoots) {
+    if (sameOrInside(realPath, root)) {
+      return {
+        error: "path must not point inside the current repository or working directory"
+      };
+    }
+  }
+  return { realPath };
+}
+function forbiddenExecutableRoots(cwd) {
+  let cwdReal;
+  try {
+    cwdReal = realpathSync(cwd);
+  } catch {
+    return { error: `--cwd must point to an existing directory: ${cwd}` };
+  }
+  const roots = [cwdReal];
+  const gitRoot = findGitRootByWalking(cwdReal);
+  if (gitRoot && !roots.some((root) => sameOrInside(gitRoot, root))) {
+    roots.push(gitRoot);
+  }
+  return { roots };
+}
+function findGitRootByWalking(start) {
+  let current = start;
+  for (;; ) {
+    try {
+      statSync(join2(current, ".git"));
+      return realpathSync(current);
+    } catch {}
+    const parent = dirname2(current);
+    if (parent === current)
+      return null;
+    current = parent;
+  }
+}
+function sameOrInside(path, root) {
+  const rel = relative(root, path);
+  return rel === "" || !!rel && !rel.startsWith("..") && !isAbsolute(rel);
+}
+function isCommandNotFoundMessage(command, message) {
+  const lower = message.toLowerCase();
+  if (lower.includes("enoent"))
+    return true;
+  if (lower.includes(`spawn ${command.toLowerCase()}`))
+    return true;
+  if (lower.includes(`${command.toLowerCase()}: command not found`))
+    return true;
+  if (lower.includes(`${command.toLowerCase()}: not found`))
+    return true;
+  return false;
+}
+var EXTERNAL_COMMAND_NAMES, commandNameSet, activeOverrides;
+var init_command_resolver = __esm(() => {
+  EXTERNAL_COMMAND_NAMES = ["git", "rg", "docker"];
+  commandNameSet = new Set(EXTERNAL_COMMAND_NAMES);
+  activeOverrides = new Map;
+});
+
 // web-src/server/runtime.ts
 import { spawn, spawnSync } from "node:child_process";
 import { createReadStream, promises as fs } from "node:fs";
@@ -677,7 +846,7 @@ function runSync(args, cwd, options = {}) {
   return {
     code: proc.status ?? (proc.error ? 1 : 0),
     stdout: new TextDecoder().decode(proc.stdout || new Uint8Array),
-    stderr: new TextDecoder().decode(proc.stderr || new Uint8Array)
+    stderr: appendProcessError(new TextDecoder().decode(proc.stderr || new Uint8Array), proc.error)
   };
 }
 function runBytesSync(args, cwd, options = {}) {
@@ -691,7 +860,7 @@ function runBytesSync(args, cwd, options = {}) {
   return {
     code: proc.status ?? (proc.error ? 1 : 0),
     stdout: new Uint8Array(proc.stdout || new Uint8Array),
-    stderr: new TextDecoder().decode(proc.stderr || new Uint8Array)
+    stderr: appendProcessError(new TextDecoder().decode(proc.stderr || new Uint8Array), proc.error)
   };
 }
 function spawnDetached(args) {
@@ -699,6 +868,9 @@ function spawnDetached(args) {
     detached: true,
     stdio: "ignore"
   });
+  child.on("error", (err) => {
+    console.warn("[code-viewer] failed to start detached command:", err.message);
+  });
   child.unref();
 }
 function spawnStream(args, cwd) {
@@ -706,12 +878,32 @@ function spawnStream(args, cwd) {
     cwd,
     stdio: ["ignore", "pipe", "ignore"]
   });
+  let errorCode = 0;
+  proc.on("error", () => {
+    errorCode = 1;
+  });
   return {
     stream: Readable.toWeb(proc.stdout),
-    exited: new Promise((resolve) => proc.on("close", (code) => resolve(code ?? 1))),
+    exited: new Promise((resolve) => {
+      let settled = false;
+      const done = (code) => {
+        if (settled)
+          return;
+        settled = true;
+        resolve(code);
+      };
+      proc.on("error", () => done(1));
+      proc.on("close", (code) => done(errorCode || (code ?? 1)));
+    }),
     kill: (signal) => proc.kill(signal)
   };
 }
+function appendProcessError(stderr, err) {
+  if (!err)
+    return stderr;
+  return `${stderr}${stderr ? `
+` : ""}${err.message}`;
+}
 function fileReadableStream(path) {
   return Readable.toWeb(createReadStream(path));
 }
@@ -847,9 +1039,9 @@ import {
   lstatSync,
   readdirSync,
   readFileSync,
-  statSync
+  statSync as statSync2
 } from "node:fs";
-import { join as join2 } from "node:path";
+import { join as join3 } from "node:path";
 function normalizeBlameRef(ref, base) {
   const rawRef = ref || "worktree";
   if (base === "worktree" && rawRef !== "worktree") {
@@ -861,19 +1053,75 @@ function normalizeBlameRef(ref, base) {
   return { base, ref: rawRef };
 }
 function run(args, cwd) {
-  return runSync(args, cwd);
+  return runSync(resolveGitArgs(args), cwd);
 }
 function runBytes(args, cwd) {
-  return runBytesSync(args, cwd);
+  return runBytesSync(resolveGitArgs(args), cwd);
+}
+function resolveGitArgs(args) {
+  if (args[0] !== "git")
+    return args;
+  return [commandForExternal("git"), ...args.slice(1)];
+}
+function gitFailureMessage(res, fallback) {
+  if (isCommandNotFoundResult("git", res))
+    return commandNotFoundDetail("git");
+  return res.stderr?.trim() || fallback;
+}
+function gitFailureResult(res, fallback) {
+  if (!isCommandNotFoundResult("git", res)) {
+    return { error: fallback };
+  }
+  return {
+    error: commandNotFoundDetail("git"),
+    status: 503
+  };
 }
 function repoRoot(cwd) {
   const res = run(["git", "rev-parse", "--show-toplevel"], cwd);
   return res.code === 0 ? res.stdout.trimEnd() : null;
 }
+function repoRootResult(cwd) {
+  const res = run(["git", "rev-parse", "--show-toplevel"], cwd);
+  if (res.code === 0)
+    return { kind: "root", root: res.stdout.trimEnd() };
+  if (isCommandNotFoundResult("git", res)) {
+    return { kind: "error", error: commandNotFoundDetail("git") };
+  }
+  const stderr = res.stderr.trim();
+  if (/not a git repository/i.test(stderr))
+    return { kind: "outside" };
+  return { kind: "error", error: stderr || "git rev-parse failed" };
+}
 function currentBranch(cwd) {
   const res = run(["git", "rev-parse", "--abbrev-ref", "HEAD"], cwd);
   return res.code === 0 ? res.stdout.trimEnd() : null;
 }
+function verifyCommit(ref, cwd) {
+  const res = run(["git", "rev-parse", "--verify", `${ref}^{commit}`], cwd);
+  if (res.code === 0)
+    return { ok: true, sha: res.stdout.trim() };
+  return { ok: false, error: gitFailureMessage(res, "unknown ref") };
+}
+function statusPorcelainForPath(path, cwd) {
+  const res = run([
+    "git",
+    "-c",
+    "core.quotepath=false",
+    "status",
+    "--porcelain=v1",
+    "-z",
+    "--untracked-files=normal",
+    "--",
+    path
+  ], cwd);
+  if (res.code === 0)
+    return { ok: true, stdout: res.stdout };
+  return {
+    ok: false,
+    error: gitFailureMessage(res, "git status failed")
+  };
+}
 function show(ref, path, cwd) {
   return run(["git", "show", `${ref}:${path}`], cwd);
 }
@@ -881,7 +1129,7 @@ function showBytes(ref, path, cwd) {
   return runBytes(["git", "show", `${ref}:${path}`], cwd);
 }
 function catFileBlobStream(oid, cwd) {
-  return spawnStream(["git", "cat-file", "blob", oid], cwd);
+  return spawnStream(resolveGitArgs(["git", "cat-file", "blob", oid]), cwd);
 }
 function objectSize(ref, path, cwd) {
   const res = run(["git", "cat-file", "-s", `${ref}:${path}`], cwd);
@@ -917,14 +1165,19 @@ function objectId(ref, path, cwd) {
   return { code: 0, oid, stderr: "" };
 }
 function verifyTreeRef(ref, cwd) {
+  return verifyTreeRefResult(ref, cwd).ok;
+}
+function verifyTreeRefResult(ref, cwd) {
   if (!ref || ref === "worktree")
-    return false;
+    return { ok: false, error: "invalid target", status: 400 };
   if (ref.startsWith("-"))
-    return false;
+    return { ok: false, error: "invalid target", status: 400 };
   const res = run(["git", "rev-parse", "--verify", `${ref}^{tree}`], cwd);
-  return res.code === 0;
+  if (res.code === 0)
+    return { ok: true };
+  return { ok: false, ...gitFailureResult(res, "invalid target") };
 }
-function refs(cwd) {
+function refsResult(cwd) {
   const out = {
     branches: [],
     tags: [],
@@ -939,6 +1192,9 @@ function refs(cwd) {
     "refs/heads",
     "refs/remotes"
   ], cwd);
+  if (branches.code !== 0 && isCommandNotFoundResult("git", branches)) {
+    return { refs: out, ...gitFailureResult(branches, "git refs failed") };
+  }
   if (branches.code === 0) {
     for (const line of branches.stdout.split(`
 `)) {
@@ -955,6 +1211,9 @@ function refs(cwd) {
     "--format=%(refname:short)%09%(creatordate:iso-strict)",
     "refs/tags"
   ], cwd);
+  if (tags.code !== 0 && isCommandNotFoundResult("git", tags)) {
+    return { refs: out, ...gitFailureResult(tags, "git refs failed") };
+  }
   if (tags.code === 0) {
     for (const line of tags.stdout.split(`
 `)) {
@@ -964,9 +1223,16 @@ function refs(cwd) {
       out.tags.push({ name, when });
     }
   }
-  out.commits = refCommits(cwd, "", DEFAULT_REF_COMMIT_LIMIT);
+  const commits = refCommitPageResult(cwd, {
+    query: "",
+    max: DEFAULT_REF_COMMIT_LIMIT
+  });
+  if (commits.error) {
+    return { refs: out, error: commits.error, status: commits.status };
+  }
+  out.commits = commits.commits;
   out.current = currentBranch(cwd) || "";
-  return out;
+  return { refs: out };
 }
 function clampCommitLimit(max) {
   return Math.max(1, Math.min(max, MAX_REF_COMMIT_LIMIT));
@@ -1019,14 +1285,15 @@ function mergeCommitResults(limit, ...groups) {
   }
   return merged;
 }
-function runCommitLog(cwd, args) {
+function runCommitLogResult(cwd, args) {
   const commits = run(args, cwd);
-  return commits.code === 0 ? parseCommitLog(commits.stdout) : [];
+  if (commits.code === 0)
+    return { commits: parseCommitLog(commits.stdout) };
+  if (isCommandNotFoundResult("git", commits))
+    return { commits: [], ...gitFailureResult(commits, "git log failed") };
+  return { commits: [] };
 }
-function refCommits(cwd, query = "", max = DEFAULT_REF_COMMIT_LIMIT) {
-  return refCommitPage(cwd, { query, max }).commits;
-}
-function refCommitPage(cwd, options = {}) {
+function refCommitPageResult(cwd, options = {}) {
   const limit = clampCommitLimit(options.max ?? DEFAULT_REF_COMMIT_LIMIT);
   const skip = clampCommitSkip(options.skip ?? 0);
   const fetchLimit = limit + 1;
@@ -1034,6 +1301,13 @@ function refCommitPage(cwd, options = {}) {
   const trimmed = (options.query || "").trim().slice(0, 200).replace(/\0/g, "");
   if (skip === 0 && /^[0-9a-f]{4,40}$/i.test(trimmed)) {
     const verified = run(["git", "rev-parse", "--verify", `${trimmed}^{commit}`], cwd);
+    if (verified.code !== 0 && isCommandNotFoundResult("git", verified)) {
+      return {
+        commits: [],
+        hasMore: false,
+        ...gitFailureResult(verified, "unknown ref")
+      };
+    }
     const single = run([
       "git",
       "log",
@@ -1042,30 +1316,62 @@ function refCommitPage(cwd, options = {}) {
       `--format=${COMMIT_FORMAT}`,
       verified.code === 0 && verified.stdout.trim() ? verified.stdout.trim() : trimmed
     ], cwd);
+    if (single.code !== 0 && isCommandNotFoundResult("git", single)) {
+      return {
+        commits: [],
+        hasMore: false,
+        ...gitFailureResult(single, "git log failed")
+      };
+    }
     if (single.code === 0 && single.stdout.trim()) {
       hashMatches.push(...parseCommitLog(single.stdout));
     }
   }
   if (!trimmed) {
-    const commits = runCommitLog(cwd, commitLogArgs(fetchLimit, skip));
+    const result = runCommitLogResult(cwd, commitLogArgs(fetchLimit, skip));
+    if (result.error) {
+      return {
+        commits: [],
+        hasMore: false,
+        error: result.error,
+        status: result.status
+      };
+    }
+    const commits = result.commits;
     return {
       commits: commits.slice(0, limit),
       hasMore: commits.length > limit
     };
   }
-  const subjectMatches = runCommitLog(cwd, [
+  const subjectMatches = runCommitLogResult(cwd, [
     ...commitLogArgs(fetchLimit, skip),
     "--regexp-ignore-case",
     "--fixed-strings",
     `--grep=${trimmed}`
   ]);
-  const authorMatches = runCommitLog(cwd, [
+  if (subjectMatches.error) {
+    return {
+      commits: [],
+      hasMore: false,
+      error: subjectMatches.error,
+      status: subjectMatches.status
+    };
+  }
+  const authorMatches = runCommitLogResult(cwd, [
     ...commitLogArgs(fetchLimit, skip),
     "--regexp-ignore-case",
     "--fixed-strings",
     `--author=${trimmed}`
   ]);
-  const merged = mergeCommitResults(fetchLimit, hashMatches, subjectMatches, authorMatches);
+  if (authorMatches.error) {
+    return {
+      commits: [],
+      hasMore: false,
+      error: authorMatches.error,
+      status: authorMatches.status
+    };
+  }
+  const merged = mergeCommitResults(fetchLimit, hashMatches, subjectMatches.commits, authorMatches.commits);
   return {
     commits: merged.slice(0, limit),
     hasMore: merged.length > limit
@@ -1160,7 +1466,11 @@ function commitHistory(cwd, options) {
     return { commits: [], hasMore: false, error: "invalid ref" };
   const verified = run(["git", "rev-parse", "--verify", `${ref}^{commit}`], cwd);
   if (verified.code !== 0)
-    return { commits: [], hasMore: false, error: "unknown ref" };
+    return {
+      commits: [],
+      hasMore: false,
+      ...gitFailureResult(verified, "unknown ref")
+    };
   const skip = Math.max(0, Math.floor(options.skip) || 0);
   const limit = Math.max(1, Math.min(Math.floor(options.limit) || 1, MAX_HISTORY_LIMIT));
   const { filterArgs, pathspec, shaTerm } = historyQueryArgs(options.query || "");
@@ -1184,7 +1494,11 @@ function commitHistory(cwd, options) {
     ...pathArgs
   ], cwd);
   if (res.code !== 0)
-    return { commits: [], hasMore: false, error: "git log failed" };
+    return {
+      commits: [],
+      hasMore: false,
+      ...gitFailureResult(res, "git log failed")
+    };
   let parsed = parseHistoryLog(res.stdout);
   if (shaTerm && skip === 0) {
     const bySha = run(["git", "rev-parse", "--verify", `${shaTerm}^{commit}`], cwd);
@@ -1200,7 +1514,7 @@ function commitHistory(cwd, options) {
   const hasMore = parsed.length > limit;
   return { commits: hasMore ? parsed.slice(0, limit) : parsed, hasMore };
 }
-function nameStatus(args, cwd) {
+function nameStatusResult(args, cwd) {
   const res = run([
     "git",
     "-c",
@@ -1213,8 +1527,12 @@ function nameStatus(args, cwd) {
     "-z",
     ...args
   ], cwd);
-  if (res.code !== 0)
-    return [];
+  if (res.code !== 0) {
+    return {
+      files: [],
+      error: gitFailureMessage(res, "git diff --name-status failed")
+    };
+  }
   const parts = res.stdout.split("\x00");
   const files = [];
   for (let i = 0;i < parts.length; ) {
@@ -1238,9 +1556,9 @@ function nameStatus(args, cwd) {
         files.push({ status: kind, path });
     }
   }
-  return files;
+  return { files };
 }
-function numstatZ(args, cwd) {
+function numstatZResult(args, cwd) {
   const res = run([
     "git",
     "-c",
@@ -1253,8 +1571,12 @@ function numstatZ(args, cwd) {
     "-z",
     ...args
   ], cwd);
-  if (res.code !== 0)
-    return [];
+  if (res.code !== 0) {
+    return {
+      files: [],
+      error: gitFailureMessage(res, "git diff --numstat failed")
+    };
+  }
   const parts = res.stdout.split("\x00");
   const files = [];
   for (let i = 0;i < parts.length; ) {
@@ -1277,7 +1599,7 @@ function numstatZ(args, cwd) {
       files.push({ path: rest, additions, deletions, binary });
     }
   }
-  return files;
+  return { files };
 }
 function pathHasSegment(path, segment) {
   const target = segment.toLowerCase();
@@ -1290,9 +1612,9 @@ function isGitInternalPath(path) {
   return pathHasSegment(path, ".git");
 }
 function syntheticUncommittedBlameFromWorktree(cwd, path) {
-  const filePath = join2(cwd, path);
+  const filePath = join3(cwd, path);
   try {
-    const stat = statSync(filePath);
+    const stat = statSync2(filePath);
     if (!stat.isFile())
       return { lines: [], commits: {}, error: "not a file" };
     const text = readFileSync(filePath, "utf8");
@@ -1344,6 +1666,14 @@ function blame(cwd, options) {
   args.push("--", path);
   const res = run(args, cwd);
   if (res.code !== 0) {
+    if (isCommandNotFoundResult("git", res)) {
+      return {
+        lines: [],
+        commits: {},
+        error: commandNotFoundDetail("git"),
+        status: 503
+      };
+    }
     if (normalized.base === "worktree") {
       return syntheticUncommittedBlameFromWorktree(cwd, path);
     }
@@ -1439,7 +1769,7 @@ function omittedWorktreeDirectoryReason(name, omitDirNames) {
   return omitDirNames.has(name) ? "heavy" : undefined;
 }
 function worktreeSubmodulePaths(cwd) {
-  if (!existsSync(join2(cwd, ".gitmodules")))
+  if (!existsSync(join3(cwd, ".gitmodules")))
     return new Set;
   const res = run(["git", "config", "--file", ".gitmodules", "--get-regexp", "\\.path$"], cwd);
   if (res.code !== 0)
@@ -1458,7 +1788,7 @@ function worktreeEntryFromDirent(base, dir, name, isDirectory, omitDirNames, exc
       type: isDirectory ? "tree" : "blob"
     };
   const entryPath = base ? `${base}/${name}` : name;
-  const type = isDirectory ? hasDotGitEntry(join2(dir, name)) ? "commit" : "tree" : "blob";
+  const type = isDirectory ? hasDotGitEntry(join3(dir, name)) ? "commit" : "tree" : "blob";
   const omittedReason = type === "tree" ? omittedWorktreeDirectoryReason(name, omitDirNames) : undefined;
   const submodule = type === "commit" && submodulePaths.has(entryPath) ? true : undefined;
   const baseEntry = submodule ? { name, path: entryPath, type, submodule } : { name, path: entryPath, type };
@@ -1470,7 +1800,7 @@ function worktreeEntryFromDirent(base, dir, name, isDirectory, omitDirNames, exc
 }
 function worktreeFilesystemEntries(cwd, path, recursive, omitDirNames = DEFAULT_WORKTREE_OMIT_DIR_NAMES, excludeNames = []) {
   const base = normalizeTreePath(path);
-  const root = join2(cwd, base);
+  const root = join3(cwd, base);
   const omitDirNameSet = new Set(omitDirNames);
   const excludeNameSet = new Set(excludeNames.map((name) => name.toLowerCase()));
   const submodulePaths = worktreeSubmodulePaths(cwd);
@@ -1517,7 +1847,7 @@ function worktreeFilesystemEntries(cwd, path, recursive, omitDirNames = DEFAULT_
       if (excludeNameSet.has(entry.name.toLowerCase()))
         continue;
       const entryPath = prefix ? `${prefix}/${entry.name}` : entry.name;
-      const full = join2(dir, entry.name);
+      const full = join3(dir, entry.name);
       if (entry.isDirectory()) {
         const omittedReason = omittedWorktreeDirectoryReason(entry.name, omitDirNameSet);
         if (omittedReason) {
@@ -1549,7 +1879,7 @@ function worktreeFilesystemEntries(cwd, path, recursive, omitDirNames = DEFAULT_
 }
 function hasDotGitEntry(dir) {
   try {
-    lstatSync(join2(dir, ".git"));
+    lstatSync(join3(dir, ".git"));
     return true;
   } catch (err) {
     return !!err && typeof err === "object" && "code" in err && err.code !== "ENOENT";
@@ -1612,14 +1942,20 @@ function listTree(ref, path, cwd, options = {}) {
     stderr: ""
   };
 }
+function listTreeResult(ref, path, cwd, options = {}) {
+  const result = listTree(ref, path, cwd, options);
+  if (result.code === 0)
+    return { entries: result.entries };
+  return { entries: [], ...gitFailureResult(result, "git ls-tree failed") };
+}
 function untrackedMeta(cwd) {
   return untracked(cwd).flatMap((path) => {
-    const full = join2(cwd, path);
+    const full = join3(cwd, path);
     let binary = false;
     let lines = 0;
     let fileExists = false;
     try {
-      fileExists = existsSync(full) && statSync(full).isFile();
+      fileExists = existsSync(full) && statSync2(full).isFile();
     } catch {
       fileExists = false;
     }
@@ -1645,11 +1981,15 @@ function untrackedMeta(cwd) {
     ];
   });
 }
-function fileMeta(args, cwd, includeUntracked = false) {
-  const ns = nameStatus(args, cwd);
-  const nm = numstatZ(args, cwd);
-  const byPath = new Map(nm.map((file) => [file.path, file]));
-  const files = ns.map((file) => {
+function fileMetaResult(args, cwd, includeUntracked = false) {
+  const ns = nameStatusResult(args, cwd);
+  if (ns.error)
+    return { files: [], error: ns.error };
+  const nm = numstatZResult(args, cwd);
+  if (nm.error)
+    return { files: [], error: nm.error };
+  const byPath = new Map(nm.files.map((file) => [file.path, file]));
+  const files = ns.files.map((file) => {
     const stats = byPath.get(file.path);
     return {
       ...file,
@@ -1658,11 +1998,13 @@ function fileMeta(args, cwd, includeUntracked = false) {
       binary: stats?.binary || false
     };
   });
-  return includeUntracked ? files.concat(untrackedMeta(cwd)) : files;
+  return {
+    files: includeUntracked ? files.concat(untrackedMeta(cwd)) : files
+  };
 }
 function fileDiffText(args, path, cwd) {
   const paths = Array.isArray(path) ? path : [path];
-  return run([
+  const res = run([
     "git",
     "-c",
     "core.quotepath=false",
@@ -1674,9 +2016,13 @@ function fileDiffText(args, path, cwd) {
     "--",
     ...paths
   ], cwd);
+  if (isCommandNotFoundResult("git", res)) {
+    return { ...res, stderr: commandNotFoundDetail("git"), status: 503 };
+  }
+  return res;
 }
 function untrackedFileDiff(extras, path, cwd) {
-  return run([
+  const res = run([
     "git",
     "-c",
     "core.quotepath=false",
@@ -1688,6 +2034,10 @@ function untrackedFileDiff(extras, path, cwd) {
     "/dev/null",
     path
   ], cwd);
+  if (isCommandNotFoundResult("git", res)) {
+    return { ...res, stderr: commandNotFoundDetail("git"), status: 503 };
+  }
+  return res;
 }
 function splitHunks(diffText) {
   if (!diffText)
@@ -1764,6 +2114,7 @@ function truncateToNHunks(diffText, n, maxLines = Number.POSITIVE_INFINITY) {
 }
 var BLAME_ZERO_SHA = "0000000000000000000000000000000000000000", WORKTREE_RECURSIVE_DEPTH_LIMIT = 32, WORKTREE_RECURSIVE_ENTRY_LIMIT = 50000, DEFAULT_REF_COMMIT_LIMIT = 100, MAX_REF_COMMIT_LIMIT = 500, COMMIT_FORMAT = "%H%x00%s%x00%an%x00%aI", DEFAULT_WORKTREE_OMIT_DIR_NAMES, HISTORY_FORMAT = "%H%x00%s%x00%an%x00%aI%x00%P%x00%b", MAX_HISTORY_LIMIT = 200;
 var init_git = __esm(() => {
+  init_command_resolver();
   init_runtime();
   DEFAULT_WORKTREE_OMIT_DIR_NAMES = [
     "node_modules",
@@ -1820,16 +2171,16 @@ import {
   writeFileSync
 } from "node:fs";
 import { homedir } from "node:os";
-import { join as join3 } from "node:path";
+import { join as join4 } from "node:path";
 function registryDir() {
   const override = process.env.CODE_VIEWER_TEST_SERVER_REGISTRY_DIR;
   if (override)
     return override;
-  return join3(homedir(), ".cache", "code-viewer", "servers");
+  return join4(homedir(), ".cache", "code-viewer", "servers");
 }
 function serverRegistryFilePath(root) {
   const hash = createHash("sha256").update(root).digest("hex").slice(0, 16);
-  return join3(registryDir(), `${hash}.json`);
+  return join4(registryDir(), `${hash}.json`);
 }
 function writeServerRegistry(entry) {
   try {
@@ -1870,7 +2221,7 @@ function removeServerRegistry(root, pid) {
 var init_server_registry = () => {};
 
 // web-src/server/cli-helpers.ts
-import { realpathSync } from "node:fs";
+import { realpathSync as realpathSync2 } from "node:fs";
 function takeValue(argv, index, flag) {
   const value = argv[index + 1];
   if (value === undefined)
@@ -1918,14 +2269,21 @@ function validateRepoRelativePathValue(value, flag) {
 }
 function resolveRepoRootSafe(cwdOption) {
   const base = cwdOption || process.cwd();
+  let baseReal;
   try {
-    return { ok: true, root: repoRoot(base) || realpathSync(base) };
+    baseReal = realpathSync2(base);
   } catch {
     return {
       ok: false,
       error: `--cwd must point to an existing directory: ${base}`
     };
   }
+  const root = repoRootResult(baseReal);
+  if (root.kind === "root")
+    return { ok: true, root: root.root };
+  if (root.kind === "error")
+    return { ok: false, error: root.error };
+  return { ok: true, root: baseReal };
 }
 function resolveRepoRoot(cwdOption) {
   const result = resolveRepoRootSafe(cwdOption);
@@ -3024,8 +3382,8 @@ __export(exports_file_cli, {
   FILE_DEFAULT_HISTORY_LIMIT: () => FILE_DEFAULT_HISTORY_LIMIT,
   FILE_AGENT_HELP: () => FILE_AGENT_HELP
 });
-import { existsSync as existsSync3, readFileSync as readFileSync4, realpathSync as realpathSync2, statSync as statSync2 } from "node:fs";
-import { join as join4, relative } from "node:path";
+import { existsSync as existsSync3, readFileSync as readFileSync4, realpathSync as realpathSync3, statSync as statSync3 } from "node:fs";
+import { join as join5, relative as relative2 } from "node:path";
 function validatePath(value) {
   return validateRepoRelativePathValue(value, "--path");
 }
@@ -3043,6 +3401,7 @@ function parseFileArgs(argv) {
   let cwd;
   const options = new Map;
   const flags = new Set;
+  const commandOverrides = [];
   for (let i = 0;i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--help" || arg === "-h") {
@@ -3054,6 +3413,17 @@ function parseFileArgs(argv) {
         return { ok: false, error: taken.error };
       cwd = taken.value;
       i = taken.next;
+    } else if (arg === "--bin") {
+      const taken = takeValue(argv, i, arg);
+      if ("error" in taken)
+        return { ok: false, error: taken.error };
+      const parsed = parseExternalCommandOverride(taken.value, "--bin", [
+        "git"
+      ]);
+      if (parsed.ok === false)
+        return { ok: false, error: parsed.error };
+      commandOverrides.push(parsed.override);
+      i = taken.next;
     } else if (VALUE_FLAGS.has(arg)) {
       const taken = takeValue(argv, i, arg);
       if ("error" in taken)
@@ -3115,7 +3485,8 @@ function parseFileArgs(argv) {
           base,
           json
         },
-        cwd
+        cwd,
+        ...commandOverrides.length ? { commandOverrides } : {}
       }
     };
   }
@@ -3153,7 +3524,8 @@ function parseFileArgs(argv) {
           query,
           json
         },
-        cwd
+        cwd,
+        ...commandOverrides.length ? { commandOverrides } : {}
       }
     };
   }
@@ -3192,7 +3564,8 @@ function parseFileArgs(argv) {
           end,
           json
         },
-        cwd
+        cwd,
+        ...commandOverrides.length ? { commandOverrides } : {}
       }
     };
   }
@@ -3281,7 +3654,8 @@ function parseFileArgs(argv) {
         maxLines,
         json
       },
-      cwd
+      cwd,
+      ...commandOverrides.length ? { commandOverrides } : {}
     }
   };
 }
@@ -3383,13 +3757,13 @@ function sliceLines(text, start, end) {
 function safeWorktreePathFromRoot(root, path) {
   if (validatePath(path))
     return null;
-  const full = join4(root, path);
+  const full = join5(root, path);
   if (!existsSync3(full))
     return null;
   try {
-    const realRoot = realpathSync2(root);
-    const realFull = realpathSync2(full);
-    const rel = relative(realRoot, realFull);
+    const realRoot = realpathSync3(root);
+    const realFull = realpathSync3(full);
+    const rel = relative2(realRoot, realFull);
     if (rel === "" || rel.startsWith("..") || rel.startsWith("/") || rel.startsWith("\\")) {
       return null;
     }
@@ -3413,7 +3787,7 @@ function readShowText(root, command) {
     };
   }
   try {
-    const stat = statSync2(full);
+    const stat = statSync3(full);
     if (!stat.isFile()) {
       return { code: 1, stdout: "", stderr: "not a file" };
     }
@@ -3466,12 +3840,12 @@ function runShow(root, command) {
   }
 }
 function buildFileDiffRangeArgs(from, to) {
-  const refs2 = [];
+  const refs = [];
   if (from && from !== "worktree")
-    refs2.push(from);
+    refs.push(from);
   if (to && to !== "worktree")
-    refs2.push(to);
-  return refs2;
+    refs.push(to);
+  return refs;
 }
 function buildFileDiffReport(root, command) {
   const base = {
@@ -3550,7 +3924,7 @@ async function runFileCli(argv) {
     console.error('Run "code-viewer file --help" for usage.');
     process.exit(1);
   }
-  const { command, cwd } = parsed.args;
+  const { command, cwd, commandOverrides = [] } = parsed.args;
   if (command.kind === "help") {
     console.log(FILE_HELP);
     return;
@@ -3559,6 +3933,15 @@ async function runFileCli(argv) {
     console.log(FILE_AGENT_HELP);
     return;
   }
+  const commandConfig = configureExternalCommands({
+    cwd: cwd || process.cwd(),
+    cliOverrides: commandOverrides,
+    allowedNames: ["git"]
+  });
+  if (commandConfig.ok === false) {
+    console.error(commandConfig.error);
+    process.exit(1);
+  }
   const root = resolveRepoRoot(cwd);
   if (command.kind === "blame")
     return runBlame(root, command);
@@ -3572,13 +3955,14 @@ async function runFileCli(argv) {
 var FILE_DEFAULT_HISTORY_LIMIT = 20, FILE_HISTORY_HARD_CAP = 200, FILE_DIFF_DEFAULT_MAX_HUNKS = 3, FILE_DIFF_DEFAULT_MAX_LINES = 1200, FILE_DIFF_HUNK_HARD_CAP = 100, FILE_DIFF_LINE_HARD_CAP = 1e5, FILE_HELP, FILE_AGENT_HELP, VALUE_FLAGS, BOOL_FLAGS, DEFAULT_BLAME_REF = "worktree", DEFAULT_BLAME_BASE = "worktree", DEFAULT_HISTORY_REF = "HEAD", DEFAULT_SHOW_REF = "worktree", DEFAULT_DIFF_FROM = "HEAD", DEFAULT_DIFF_TO = "worktree";
 var init_file_cli = __esm(() => {
   init_cli_helpers();
+  init_command_resolver();
   init_git();
   FILE_HELP = `code-viewer file — inspect a path's blame, history, contents, or diff
 
 Usage:
-  code-viewer file blame   --path <path> [--ref <ref>] [--base <worktree|HEAD>] [--json] [--cwd <dir>]
-  code-viewer file history --path <path> [--ref <ref>] [--limit <n>] [--skip <n>] [--query <text>] [--json] [--cwd <dir>]
-  code-viewer file show    --path <path> [--ref <ref>] [--start <line>] [--end <line>] [--json] [--cwd <dir>]
+  code-viewer file blame   --path <path> [--ref <ref>] [--base <worktree|HEAD>] [--json] [--cwd <dir>] [--bin git=<path>]
+  code-viewer file history --path <path> [--ref <ref>] [--limit <n>] [--skip <n>] [--query <text>] [--json] [--cwd <dir>] [--bin git=<path>]
+  code-viewer file show    --path <path> [--ref <ref>] [--start <line>] [--end <line>] [--json] [--cwd <dir>] [--bin git=<path>]
   code-viewer file diff    --path <path> [--from <ref>] [--to <ref>] [--old-path <path>] [--untracked]
                            [--ignore-ws] [--ignore-blank] [--max-hunks <n>] [--max-lines <n>] [--full] [--json] [--cwd <dir>]
   code-viewer file --help
@@ -3591,6 +3975,7 @@ Common options:
                   HEAD. Single-line, no NUL, no leading "-". blame/show accept
                   the literal "worktree" to mean the working tree.
   --cwd <dir>     Repository to target (default: process.cwd()).
+  --bin git=<p>   Override git executable path.
   --json          Emit a structured JSON payload instead of plain text.
   --help, -h      Show this help.
 
@@ -3657,7 +4042,8 @@ Diff Viewer views.
 - Run from inside the repository, or pass --cwd <repo>.
 - No code-viewer server is required (this command reads git refs or the
   worktree directly).
-- Git must be available on PATH.
+- Git must be available on PATH, or supplied with --bin git=/absolute/path
+  / CODE_VIEWER_BIN_GIT.
 
 ## How to call
 
@@ -3902,6 +4288,7 @@ function parseQueryArgs(argv) {
   let server;
   const options = new Map;
   const flags = new Set;
+  const commandOverrides = [];
   for (let i = 0;i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--help" || arg === "-h")
@@ -3915,6 +4302,17 @@ function parseQueryArgs(argv) {
       else
         server = taken.value;
       i = taken.next;
+    } else if (arg === "--bin") {
+      const taken = takeValue(argv, i, arg);
+      if ("error" in taken)
+        return { ok: false, error: taken.error };
+      const parsed = parseExternalCommandOverride(taken.value, "--bin", [
+        "git"
+      ]);
+      if (parsed.ok === false)
+        return { ok: false, error: parsed.error };
+      commandOverrides.push(parsed.override);
+      i = taken.next;
     } else if (VALUE_FLAGS2.has(arg)) {
       const taken = takeValue(argv, i, arg);
       if ("error" in taken)
@@ -3932,7 +4330,11 @@ function parseQueryArgs(argv) {
   const subcommand = rest[0];
   if (!subcommand)
     return { ok: true, args: { command: { kind: "help" } } };
-  const globalArgs = { cwd, server };
+  const globalArgs = {
+    cwd,
+    server,
+    ...commandOverrides.length ? { commandOverrides } : {}
+  };
   if (subcommand === "agent-help") {
     return { ok: true, args: { command: { kind: "agent-help" } } };
   }
@@ -4707,7 +5109,7 @@ async function runQueryCli(argv) {
     console.error('Run "code-viewer query --help" for usage.');
     process.exit(1);
   }
-  const { command, cwd, server } = parsed.args;
+  const { command, cwd, server, commandOverrides = [] } = parsed.args;
   if (command.kind === "help") {
     console.log(QUERY_HELP);
     return;
@@ -4716,7 +5118,16 @@ async function runQueryCli(argv) {
     console.log(QUERY_AGENT_HELP);
     return;
   }
-  const root = resolveRepoRoot(cwd);
+  const commandConfig = configureExternalCommands({
+    cwd: cwd || process.cwd(),
+    cliOverrides: commandOverrides,
+    allowedNames: ["git"]
+  });
+  if (commandConfig.ok === false) {
+    console.error(commandConfig.error);
+    process.exit(1);
+  }
+  const root = server ? cwd || process.cwd() : resolveRepoRoot(cwd);
   const serverUrl = await ensureServerUrl(root, server, "/");
   if (command.kind === "sources")
     return runSources(serverUrl, command);
@@ -5561,6 +5972,8 @@ Usage:
 Global options:
   --cwd <dir>      repository directory (default: current directory)
   --server <url>   code-viewer server URL (default: auto-discovered)
+  --bin git=<p>    override the CLI-side git path used for server discovery.
+                  Server-side rg/docker paths are set when starting code-viewer.
 
 Examples:
   code-viewer query sources --json
@@ -5966,6 +6379,7 @@ object bytes (text-shaped objects are previewable via \`s3 text\`).
 var init_query_cli = __esm(() => {
   init_routes();
   init_cli_helpers();
+  init_command_resolver();
   init_cli_helpers();
   VALUE_FLAGS2 = new Set([
     "--db",
@@ -6458,6 +6872,7 @@ function parseSearchArgs(argv) {
   const options = new Map;
   const paths = [];
   const flags = new Set;
+  const commandOverrides = [];
   for (let i = 0;i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--help" || arg === "-h") {
@@ -6472,6 +6887,17 @@ function parseSearchArgs(argv) {
       else
         server = taken.value;
       i = taken.next;
+    } else if (arg === "--bin") {
+      const taken = takeValue(argv, i, arg);
+      if ("error" in taken)
+        return { ok: false, error: taken.error };
+      const parsed = parseExternalCommandOverride(taken.value, "--bin", [
+        "git"
+      ]);
+      if (parsed.ok === false)
+        return { ok: false, error: parsed.error };
+      commandOverrides.push(parsed.override);
+      i = taken.next;
     } else if (REPEATABLE_VALUE_FLAGS.has(arg)) {
       const taken = takeValue(argv, i, arg);
       if ("error" in taken)
@@ -6559,7 +6985,8 @@ function parseSearchArgs(argv) {
           json: flags.has("--json")
         },
         cwd,
-        server
+        server,
+        ...commandOverrides.length ? { commandOverrides } : {}
       }
     };
   }
@@ -6594,7 +7021,8 @@ function parseSearchArgs(argv) {
         json: flags.has("--json")
       },
       cwd,
-      server
+      server,
+      ...commandOverrides.length ? { commandOverrides } : {}
     }
   };
 }
@@ -6686,7 +7114,7 @@ async function runSearchCli(argv) {
     console.error('Run "code-viewer search --help" for usage.');
     process.exit(1);
   }
-  const { command, cwd, server } = parsed.args;
+  const { command, cwd, server, commandOverrides = [] } = parsed.args;
   if (command.kind === "help") {
     console.log(SEARCH_HELP);
     return;
@@ -6695,7 +7123,16 @@ async function runSearchCli(argv) {
     console.log(SEARCH_AGENT_HELP);
     return;
   }
-  const root = resolveRepoRoot(cwd);
+  const commandConfig = configureExternalCommands({
+    cwd: cwd || process.cwd(),
+    cliOverrides: commandOverrides,
+    allowedNames: ["git"]
+  });
+  if (commandConfig.ok === false) {
+    console.error(commandConfig.error);
+    process.exit(1);
+  }
+  const root = server ? cwd || process.cwd() : resolveRepoRoot(cwd);
   const serverUrl = await ensureServerUrl(root, server, "/");
   if (command.kind === "code")
     return runCode(serverUrl, command);
@@ -6705,15 +7142,16 @@ async function runSearchCli(argv) {
 var FILE_NAME_SEARCH_DEFAULT_MAX = 50, SEARCH_HELP, SEARCH_AGENT_HELP, VALUE_FLAGS3, REPEATABLE_VALUE_FLAGS, BOOL_FLAGS3;
 var init_search_cli = __esm(() => {
   init_cli_helpers();
+  init_command_resolver();
   init_search();
   SEARCH_HELP = `code-viewer search — text and filename search across the worktree or a git ref
 
 Usage:
   code-viewer search code --term <text> [--ref <ref>] [--path <path>...]
                           [--regex] [--max <n>] [--json]
-                          [--cwd <dir>] [--server <url>]
+                          [--cwd <dir>] [--server <url>] [--bin <name>=<path>]
   code-viewer search files --term <pattern> [--ref <ref>] [--max <n>] [--json]
-                           [--cwd <dir>] [--server <url>]
+                           [--cwd <dir>] [--server <url>] [--bin <name>=<path>]
   code-viewer search --help
   code-viewer search agent-help
 
@@ -6726,6 +7164,8 @@ Common options:
   --json            Emit a structured JSON payload instead of plain lines.
   --cwd <dir>       Repository to target (default: process.cwd()).
   --server <url>    code-viewer server URL (default: auto-discover).
+  --bin git=<p>     Override the CLI-side git path used for server discovery.
+                    Server-side rg/docker paths are set when starting code-viewer.
   --help, -h        Show this help.
 
 search code only:
@@ -6852,24 +7292,24 @@ Parse failures and unreachable servers exit 1.
 
 // web-src/server/root.ts
 import { existsSync as existsSync4 } from "node:fs";
-import { dirname as dirname2, join as join5, normalize } from "node:path";
+import { dirname as dirname3, join as join6, normalize } from "node:path";
 import { fileURLToPath } from "node:url";
 function findRoot(start) {
   let current = start;
   for (let i = 0;i < 5; i++) {
-    if (existsSync4(join5(current, "package.json")) && existsSync4(join5(current, "web"))) {
+    if (existsSync4(join6(current, "package.json")) && existsSync4(join6(current, "web"))) {
       return normalize(current);
     }
-    const parent = dirname2(current);
+    const parent = dirname3(current);
     if (parent === current)
       break;
     current = parent;
   }
-  return normalize(join5(start, "..", ".."));
+  return normalize(join6(start, "..", ".."));
 }
 var ROOT;
 var init_root = __esm(() => {
-  ROOT = findRoot(dirname2(fileURLToPath(import.meta.url)));
+  ROOT = findRoot(dirname3(fileURLToPath(import.meta.url)));
 });
 
 // web-src/server/skill-cli.ts
@@ -6884,7 +7324,7 @@ __export(exports_skill_cli, {
 });
 import { cpSync, existsSync as existsSync5, mkdirSync as mkdirSync2, readdirSync as readdirSync2 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { join as join6, resolve } from "node:path";
+import { join as join7, resolve } from "node:path";
 function parseAgentList(value) {
   if (value === "all")
     return [...AGENT_NAMES];
@@ -6944,7 +7384,7 @@ function parseSkillArgs(argv) {
 function discoverBundledSkills(skillsRoot) {
   if (!existsSync5(skillsRoot))
     return [];
-  return readdirSync2(skillsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory() && existsSync5(join6(skillsRoot, entry.name, "SKILL.md"))).map((entry) => entry.name).sort();
+  return readdirSync2(skillsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory() && existsSync5(join7(skillsRoot, entry.name, "SKILL.md"))).map((entry) => entry.name).sort();
 }
 function installSkill(args, deps) {
   const skills = discoverBundledSkills(deps.skillsRoot);
@@ -6958,8 +7398,8 @@ function installSkill(args, deps) {
   const results = [];
   for (const agent of args.agents) {
     for (const skill of skills) {
-      const sourceDir = join6(deps.skillsRoot, skill);
-      const target = join6(base, AGENT_SKILL_DIRS[agent], "skills", skill);
+      const sourceDir = join7(deps.skillsRoot, skill);
+      const target = join7(base, AGENT_SKILL_DIRS[agent], "skills", skill);
       const action = existsSync5(target) ? "updated" : "installed";
       try {
         mkdirSync2(target, { recursive: true });
@@ -6988,7 +7428,7 @@ function runSkillCli(argv) {
     return;
   }
   const result = installSkill(parsed.args, {
-    skillsRoot: join6(ROOT, "skills"),
+    skillsRoot: join7(ROOT, "skills"),
     homeDir: homedir2(),
     projectDir: process.cwd()
   });
@@ -7122,6 +7562,7 @@ function parseStatusArgs(argv) {
   const options = new Map;
   const flags = new Set;
   const positional = [];
+  const commandOverrides = [];
   for (let i = 0;i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--help" || arg === "-h") {
@@ -7133,6 +7574,17 @@ function parseStatusArgs(argv) {
         return { ok: false, error: taken.error };
       cwd = taken.value;
       i = taken.next;
+    } else if (arg === "--bin") {
+      const taken = takeValue(argv, i, arg);
+      if ("error" in taken)
+        return { ok: false, error: taken.error };
+      const parsed = parseExternalCommandOverride(taken.value, "--bin", [
+        "git"
+      ]);
+      if (parsed.ok === false)
+        return { ok: false, error: parsed.error };
+      commandOverrides.push(parsed.override);
+      i = taken.next;
     } else if (VALUE_FLAGS4.has(arg)) {
       const taken = takeValue(argv, i, arg);
       if ("error" in taken)
@@ -7183,7 +7635,8 @@ function parseStatusArgs(argv) {
         limit,
         json: flags.has("--json")
       },
-      cwd
+      cwd,
+      ...commandOverrides.length ? { commandOverrides } : {}
     }
   };
 }
@@ -7196,9 +7649,13 @@ function sumTotals(files) {
   }
   return { files: files.length, additions, deletions };
 }
-function buildGroup(files) {
+function buildGroup(files, error) {
   const sorted = [...files].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
-  return { files: sorted, totals: sumTotals(sorted) };
+  return {
+    files: sorted,
+    totals: sumTotals(sorted),
+    ...error ? { error } : {}
+  };
 }
 function metaPathKey(file) {
   return `${file.old_path || ""}\x00${file.path}`;
@@ -7215,6 +7672,9 @@ function mergeMissingByPath(primary, fallback) {
   }
   return merged;
 }
+function isMissingDiffBaseError(error) {
+  return !!error && /ambiguous argument 'HEAD'|bad revision 'HEAD'/i.test(error);
+}
 function joinCli(parts, serverUrl) {
   const head = parts[0];
   const tail = parts.slice(1).join(" ");
@@ -7259,6 +7719,8 @@ function formatGroupText(label, group) {
   const totals = group.totals;
   const summary = totals.files === 0 ? `${label}: 0 files` : `${label}: ${totals.files} files (+${totals.additions} / -${totals.deletions})`;
   lines.push(summary);
+  if (group.error)
+    lines.push(`  # error: ${group.error}`);
   for (const file of group.files)
     lines.push(formatChangedLine(file));
   return lines;
@@ -7274,10 +7736,13 @@ function formatRecentText(commits) {
 }
 function buildStatusReport(opts) {
   const { root, ref, limit } = opts;
-  const stagedFiles = fileMeta(["--cached"], root, false);
-  const changedFiles = mergeMissingByPath(fileMeta(["HEAD"], root, true), stagedFiles);
-  const changed = buildGroup(changedFiles);
-  const staged = buildGroup(stagedFiles);
+  const stagedResult = fileMetaResult(["--cached"], root, false);
+  const changedResult = fileMetaResult(["HEAD"], root, true);
+  const worktreeFallbackResult = isMissingDiffBaseError(changedResult.error) ? fileMetaResult([], root, true) : null;
+  const stagedFiles = stagedResult.files;
+  const changedFiles = changedResult.error ? worktreeFallbackResult ? mergeMissingByPath(worktreeFallbackResult.files, stagedFiles) : [] : mergeMissingByPath(changedResult.files, stagedFiles);
+  const changed = buildGroup(changedFiles, worktreeFallbackResult ? worktreeFallbackResult.error || stagedResult.error : changedResult.error || stagedResult.error);
+  const staged = buildGroup(stagedFiles, stagedResult.error);
   const history = commitHistory(root, { ref, skip: 0, limit });
   const branch = currentBranch(root);
   const remote = remoteWebUrl(root);
@@ -7325,7 +7790,7 @@ function runStatusCli(argv) {
     console.error('Run "code-viewer status --help" for usage.');
     process.exit(1);
   }
-  const { command, cwd } = parsed.args;
+  const { command, cwd, commandOverrides = [] } = parsed.args;
   if (command.kind === "help") {
     console.log(STATUS_HELP);
     return;
@@ -7334,6 +7799,15 @@ function runStatusCli(argv) {
     console.log(STATUS_AGENT_HELP);
     return;
   }
+  const commandConfig = configureExternalCommands({
+    cwd: cwd || process.cwd(),
+    cliOverrides: commandOverrides,
+    allowedNames: ["git"]
+  });
+  if (commandConfig.ok === false) {
+    console.error(commandConfig.error);
+    process.exit(1);
+  }
   const root = resolveRepoRoot(cwd);
   const report = buildStatusReport({
     root,
@@ -7342,9 +7816,13 @@ function runStatusCli(argv) {
   });
   if (command.json) {
     console.log(JSON.stringify(report, null, 2));
+    if (report.changed.error || report.staged.error)
+      process.exit(1);
     return;
   }
   console.log(formatStatusReportText(report));
+  if (report.changed.error || report.staged.error)
+    process.exit(1);
 }
 var STATUS_DEFAULT_LIMIT = 10, STATUS_HARD_CAP_LIMIT = 100, STATUS_DEFAULT_REF = "HEAD", STATUS_HELP, STATUS_AGENT_HELP = `code-viewer status — agent guide
 
@@ -7376,11 +7854,11 @@ browser home page uses — no server, no SQLite, no docker required.
   { repoRoot, branch, remoteWebUrl, changed, staged, recentCommits,
     nextCommands }
   changed / staged share shape { files: GitFileMeta[], totals: { files,
-  additions, deletions } } so AI can iterate both the same way.
+  additions, deletions }, error? } so AI can iterate both the same way.
   recentCommitsError is present when --ref cannot resolve; the command
   still emits changed / staged / nextCommands and exits 0.
-- exit 0 on success. exit 1 only on argument errors or when --cwd does
-  not resolve to a directory.
+- exit 0 on success. exit 1 on argument errors, when --cwd does not
+  resolve to a directory, or when changed / staged git collection fails.
 
 ## Suggested usage
 
@@ -7390,16 +7868,18 @@ browser home page uses — no server, no SQLite, no docker required.
 `, VALUE_FLAGS4, BOOL_FLAGS4;
 var init_status_cli = __esm(() => {
   init_cli_helpers();
+  init_command_resolver();
   init_git();
   init_server_registry();
   STATUS_HELP = `code-viewer status — snapshot the current repo for AI agents
 
 Usage:
-  code-viewer status [--cwd <repo>] [--ref <ref>] [--limit <N>] [--json]
+  code-viewer status [--cwd <repo>] [--bin git=<path>] [--ref <ref>] [--limit <N>] [--json]
   code-viewer status agent-help
 
 Options:
   --cwd <repo>    Repository to inspect (default: current directory).
+  --bin git=<p>   Override git executable path.
   --ref <ref>     Ref to read recent commits from (default: ${STATUS_DEFAULT_REF}).
   --limit <N>     Recent commits to include (default: ${STATUS_DEFAULT_LIMIT}, max ${STATUS_HARD_CAP_LIMIT}).
   --json          Emit a structured JSON payload instead of plain text.
@@ -7928,7 +8408,22 @@ var init_spawn_runner = () => {};
 // web-src/server/database/adapters/docker-utils.ts
 import { spawnSync as spawnSync2 } from "node:child_process";
 function isDockerComposeServiceUnavailableError(err) {
-  return err instanceof DockerComposeServiceUnavailableError;
+  return err instanceof DockerComposeServiceUnavailableError || err instanceof DockerCommandUnavailableError;
+}
+function dockerCommand() {
+  return commandForExternal("docker");
+}
+function isDockerCommandUnavailableResult(result) {
+  return isCommandNotFoundResult("docker", result);
+}
+function throwIfDockerCommandUnavailableResult(result) {
+  if (isDockerCommandUnavailableResult(result)) {
+    throw new DockerCommandUnavailableError;
+  }
+}
+function throwIfCachedComposeDockerCommandUnavailable(cwd) {
+  const failure = composePsCache.get(cwd)?.error || "";
+  throwIfDockerCommandUnavailableResult({ code: 1, stderr: failure });
 }
 function parseComposePsOutput(stdout) {
   const output = stdout.trim();
@@ -7942,18 +8437,21 @@ function parseComposePsOutput(stdout) {
   }
   return byService;
 }
-function cacheComposePsFailure(cwd, stderr, now) {
-  const failureTtl = /docker daemon|cannot connect|is the docker daemon running/i.test(stderr) ? COMPOSE_PS_FAILURE_TTL_MS : COMPOSE_CONTAINER_NAME_NEGATIVE_TTL_MS;
+function cacheComposePsFailure(cwd, result, now) {
+  const stderr = result.stderr || "";
+  const failureTtl = isDockerCommandUnavailableResult(result) || /docker daemon|cannot connect|is the docker daemon running/i.test(stderr) ? COMPOSE_PS_FAILURE_TTL_MS : COMPOSE_CONTAINER_NAME_NEGATIVE_TTL_MS;
   composePsCache.set(cwd, {
     containers: null,
     positiveExpiresAt: now,
-    negativeExpiresAt: now + failureTtl
+    negativeExpiresAt: now + failureTtl,
+    error: stderr
   });
 }
 function runComposePsAsync(cwd, signal) {
   throwIfAborted(signal, "docker compose ps aborted");
   if (spawnSyncImpl !== spawnSync2) {
-    const proc = spawnSyncImpl("docker", ["compose", "ps", "--format", "json", "--status", "running"], {
+    const command = dockerCommand();
+    const proc = spawnSyncImpl(command, ["compose", "ps", "--format", "json", "--status", "running"], {
       encoding: "utf8",
       timeout: 5000,
       stdio: ["ignore", "pipe", "pipe"],
@@ -7961,19 +8459,21 @@ function runComposePsAsync(cwd, signal) {
     });
     return Promise.resolve({
       stdout: String(proc.stdout || ""),
-      stderr: String(proc.stderr || ""),
+      stderr: `${String(proc.stderr || "")}${proc.error ? `
+${proc.error.message}` : ""}`,
       code: proc.status ?? 1
     });
   }
   return spawnTextAsync({
-    command: "docker",
+    command: dockerCommand(),
     args: ["compose", "ps", "--format", "json", "--status", "running"],
     cwd,
     timeoutMs: 5000,
     signal,
     killSignal: "SIGKILL",
     abortMessage: "docker compose ps aborted",
-    timeoutMessage: "docker compose ps timed out"
+    timeoutMessage: "docker compose ps timed out",
+    rejectOnError: false
   });
 }
 async function resolveRunningComposeContainerNameAsync(serviceName, cwd, signal) {
@@ -8002,11 +8502,14 @@ async function resolveRunningComposeContainerNameAsync(serviceName, cwd, signal)
         } catch (err) {
           if (isAbortLikeError(err, controller.signal))
             throw err;
-          cacheComposePsFailure(cwd, err instanceof Error ? err.message : String(err), startedAt);
+          cacheComposePsFailure(cwd, {
+            code: 1,
+            stderr: err instanceof Error ? err.message : String(err)
+          }, startedAt);
           return null;
         }
         if (proc.code !== 0) {
-          cacheComposePsFailure(cwd, proc.stderr || "", startedAt);
+          cacheComposePsFailure(cwd, proc, startedAt);
           return null;
         }
         try {
@@ -8021,7 +8524,8 @@ async function resolveRunningComposeContainerNameAsync(serviceName, cwd, signal)
           composePsCache.set(cwd, {
             containers: null,
             positiveExpiresAt: startedAt,
-            negativeExpiresAt: startedAt + COMPOSE_CONTAINER_NAME_NEGATIVE_TTL_MS
+            negativeExpiresAt: startedAt + COMPOSE_CONTAINER_NAME_NEGATIVE_TTL_MS,
+            error: "could not parse docker compose ps output"
           });
           return null;
         }
@@ -8064,12 +8568,14 @@ async function resolveRunningComposeContainerNameAsync(serviceName, cwd, signal)
 async function resolveRunningComposeContainerNameOrThrowAsync(serviceName, cwd, signal) {
   const containerName = await resolveRunningComposeContainerNameAsync(serviceName, cwd, signal);
   if (!containerName) {
+    throwIfCachedComposeDockerCommandUnavailable(cwd);
     throw new DockerComposeServiceUnavailableError(serviceName, cwd);
   }
   return containerName;
 }
-var COMPOSE_CONTAINER_NAME_POSITIVE_TTL_MS = 30000, COMPOSE_CONTAINER_NAME_NEGATIVE_TTL_MS = 3000, COMPOSE_PS_FAILURE_TTL_MS = 15000, composePsCache, composePsPending, spawnSyncImpl, DockerComposeServiceUnavailableError;
+var COMPOSE_CONTAINER_NAME_POSITIVE_TTL_MS = 30000, COMPOSE_CONTAINER_NAME_NEGATIVE_TTL_MS = 3000, COMPOSE_PS_FAILURE_TTL_MS = 15000, composePsCache, composePsPending, spawnSyncImpl, DockerComposeServiceUnavailableError, DockerCommandUnavailableError;
 var init_docker_utils = __esm(() => {
+  init_command_resolver();
   init_spawn_runner();
   composePsCache = new Map;
   composePsPending = new Map;
@@ -8085,6 +8591,13 @@ var init_docker_utils = __esm(() => {
       this.cwd = cwd;
     }
   };
+  DockerCommandUnavailableError = class DockerCommandUnavailableError extends Error {
+    status = 503;
+    constructor() {
+      super(`${commandNotFoundDetail("docker")}. Install Docker or pass --bin docker=/absolute/path.`);
+      this.name = "DockerCommandUnavailableError";
+    }
+  };
 });
 
 // web-src/server/database/adapters/sql-capture.ts
@@ -8135,7 +8648,7 @@ function fallbackDockerDatabases(defaultDb) {
 function buildExecArgs(config, sql) {
   if (config.kind === "postgresql") {
     return [
-      "docker",
+      dockerCommand(),
       "exec",
       "-i",
       "-e",
@@ -8161,7 +8674,7 @@ function buildExecArgs(config, sql) {
     ];
   }
   return [
-    "docker",
+    dockerCommand(),
     "exec",
     "-i",
     "-e",
@@ -8186,7 +8699,8 @@ function execInContainer(config, sql, timeoutMs = 1e4) {
   });
   return {
     stdout: proc.stdout || "",
-    stderr: proc.stderr || "",
+    stderr: `${proc.stderr || ""}${proc.error ? `
+${proc.error.message}` : ""}`,
     code: proc.status ?? 1
   };
 }
@@ -8207,11 +8721,20 @@ async function readStreamText(stream) {
 }
 async function execWithBunSpawn(spawnFn, args, timeoutMs, signal) {
   throwIfAborted(signal, "query aborted");
-  const proc = spawnFn(args, {
-    stdin: "ignore",
-    stdout: "pipe",
-    stderr: "pipe"
-  });
+  let proc;
+  try {
+    proc = spawnFn(args, {
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+  } catch (err) {
+    return {
+      code: 1,
+      stdout: "",
+      stderr: err instanceof Error ? err.message : String(err)
+    };
+  }
   let timedOut = false;
   let aborted = false;
   const abort = () => {
@@ -8261,13 +8784,17 @@ function execWithNodeSpawn(args, timeoutMs, signal) {
 }
 async function execInContainerAsync(config, sql, timeoutMs = 1e4, signal) {
   recordSql(sql);
-  if (spawnSyncImpl2 !== spawnSync3)
-    return execInContainer(config, sql, timeoutMs);
+  let result;
+  if (spawnSyncImpl2 !== spawnSync3) {
+    result = execInContainer(config, sql, timeoutMs);
+    throwIfDockerCommandUnavailableResult(result);
+    return result;
+  }
   const args = buildExecArgs(config, sql);
   const bunSpawn = globalThis.Bun?.spawn;
-  if (bunSpawn)
-    return execWithBunSpawn(bunSpawn, args, timeoutMs, signal);
-  return execWithNodeSpawn(args, timeoutMs, signal);
+  result = bunSpawn ? await execWithBunSpawn(bunSpawn, args, timeoutMs, signal) : await execWithNodeSpawn(args, timeoutMs, signal);
+  throwIfDockerCommandUnavailableResult(result);
+  return result;
 }
 function stripFinalLineBreak(text) {
   if (text.endsWith(`\r
@@ -8798,14 +9325,22 @@ function createDockerAdapter(config) {
         try {
           const result = await execAsync(`SHOW CREATE TABLE ${tableIdentifier(table)}`, signal);
           return result.rows.length > 0 ? result.rows[0][1] || "" : "";
-        } catch {
+        } catch (err) {
+          if (isAbortLikeError(err, signal))
+            throw err;
+          if (err instanceof DockerCommandUnavailableError)
+            throw err;
           return "";
         }
       }
       try {
         const result = await execAsync(`SELECT 'CREATE TABLE ' || ${escapeSqlString(tableIdentifier(table))} || ' (...)' AS ddl`, signal);
         return result.rows.length > 0 ? result.rows[0][0] || "" : "";
-      } catch {
+      } catch (err) {
+        if (isAbortLikeError(err, signal))
+          throw err;
+        if (err instanceof DockerCommandUnavailableError)
+          throw err;
         return "";
       }
     },
@@ -8822,7 +9357,11 @@ function createDockerAdapter(config) {
           name: row[0],
           sql: row[1] || ""
         }));
-      } catch {
+      } catch (err) {
+        if (isAbortLikeError(err, signal))
+          throw err;
+        if (err instanceof DockerCommandUnavailableError)
+          throw err;
         return [];
       }
     },
@@ -8873,6 +9412,7 @@ async function listDockerDatabasesAsync(serviceName, kind, env, cwd, signal) {
     return [...cached.value];
   const containerName = await resolveRunningComposeContainerNameAsync(serviceName, cwd, signal);
   if (!containerName) {
+    throwIfCachedComposeDockerCommandUnavailable(cwd);
     return setDockerDatabasesCache(cacheKey, [], DOCKER_DATABASES_NEGATIVE_TTL_MS, now);
   }
   const user = env.POSTGRES_USER || env.MYSQL_USER || env.MARIADB_USER || env.POSTGRES_USERNAME || env.MYSQL_USERNAME || env.USER || "root";
@@ -8906,6 +9446,8 @@ async function listDockerDatabasesAsync(serviceName, kind, env, cwd, signal) {
   } catch (err) {
     if (isAbortLikeError(err, signal))
       throw err;
+    if (err instanceof DockerCommandUnavailableError)
+      throw err;
     const fallback = fallbackDockerDatabases(defaultDb);
     if (fallback.length > 0)
       return fallback;
@@ -8925,6 +9467,7 @@ async function listDockerSchemasAsync(serviceName, kind, env, cwd, overrideDatab
     return [...cached.value];
   const containerName = await resolveRunningComposeContainerNameAsync(serviceName, cwd, signal);
   if (!containerName) {
+    throwIfCachedComposeDockerCommandUnavailable(cwd);
     return setDockerSchemasCache(cacheKey, [], DOCKER_DATABASES_NEGATIVE_TTL_MS, now);
   }
   const config = {
@@ -8947,6 +9490,8 @@ async function listDockerSchemasAsync(serviceName, kind, env, cwd, overrideDatab
   } catch (err) {
     if (isAbortLikeError(err, signal))
       throw err;
+    if (err instanceof DockerCommandUnavailableError)
+      throw err;
     return setDockerSchemasCache(cacheKey, ["public"], DOCKER_DATABASES_NEGATIVE_TTL_MS, now);
   }
 }
@@ -9039,11 +9584,11 @@ __ES_STATUS__:%{http_code}
   ];
   return { args, input: curlConfig };
 }
-function execEsRequestAsync(config, method, path, body, timeoutMs = 15000, signal) {
+async function execEsRequestAsync(config, method, path, body, timeoutMs = 15000, signal) {
   throwIfAborted(signal, "elasticsearch request aborted");
   const invocation = buildEsRequestInvocation(config, method, path, body);
-  return spawnTextAsync({
-    command: "docker",
+  const result = await spawnTextAsync({
+    command: dockerCommand(),
     args: invocation.args,
     env: process.env,
     input: invocation.input,
@@ -9053,6 +9598,8 @@ function execEsRequestAsync(config, method, path, body, timeoutMs = 15000, signa
     timeoutMessage: `elasticsearch request timed out after ${timeoutMs}ms`,
     rejectOnError: false
   });
+  throwIfDockerCommandUnavailableResult(result);
+  return result;
 }
 function parseEsResponse(stdout) {
   const marker = "__ES_STATUS__:";
@@ -9400,11 +9947,11 @@ function buildRedisCliInvocation(config, args) {
   const spawnEnv = hasPassword ? { ...process.env, REDISCLI_AUTH: config.password } : process.env;
   return { args: dockerArgs, env: spawnEnv };
 }
-function execRedisCliAsync(config, args, timeoutMs = 1e4, signal) {
+async function execRedisCliAsync(config, args, timeoutMs = 1e4, signal) {
   throwIfAborted(signal, "redis-cli aborted");
   const invocation = buildRedisCliInvocation(config, args);
-  return spawnTextAsync({
-    command: "docker",
+  const result = await spawnTextAsync({
+    command: dockerCommand(),
     args: invocation.args,
     env: invocation.env,
     timeoutMs,
@@ -9413,6 +9960,8 @@ function execRedisCliAsync(config, args, timeoutMs = 1e4, signal) {
     timeoutMessage: `redis-cli timed out after ${timeoutMs}ms`,
     rejectOnError: false
   });
+  throwIfDockerCommandUnavailableResult(result);
+  return result;
 }
 function parseInfoKeyspace(stdout) {
   const counts = new Map;
@@ -10655,14 +11204,19 @@ function timeoutReadableStream(body, signal) {
 async function dockerCurlFetch(opts) {
   const { args, input } = dockerCurlCommand(opts);
   if (spawnSyncImplIsTestOverride) {
-    const proc2 = spawnSyncImpl3("docker", args, {
+    const proc2 = spawnSyncImpl3(dockerCommand(), args, {
       encoding: "buffer",
       input,
       timeout: s3DockerCurlTimeoutMs,
       stdio: ["pipe", "pipe", "pipe"]
     });
     if ((proc2.status ?? 1) !== 0) {
-      const stderr = new TextDecoder().decode(proc2.stderr || new Uint8Array).replace(/\s+/g, " ").trim();
+      const stderr = new TextDecoder().decode(proc2.stderr || new Uint8Array).concat(proc2.error ? `
+${proc2.error.message}` : "").replace(/\s+/g, " ").trim();
+      throwIfDockerCommandUnavailableResult({
+        code: proc2.status ?? 1,
+        stderr
+      });
       throw new S3HttpError(503, `S3 HTTP transport failed via docker exec${stderr ? `: ${stderr.slice(0, 240)}` : ""}`);
     }
     return responseFromCurlOutput(new Uint8Array(proc2.stdout || new Uint8Array));
@@ -10671,16 +11225,21 @@ async function dockerCurlFetch(opts) {
     throw new S3HttpError(503, "S3 HTTP transport aborted");
   }
   const proc = await spawnCollectAsync({
-    command: "docker",
+    command: dockerCommand(),
     args,
     input,
     timeoutMs: s3DockerCurlTimeoutMs,
     signal: opts.signal,
     abortMessage: "S3 HTTP transport aborted",
-    timeoutMessage: `docker exec curl timed out after ${s3DockerCurlTimeoutMs}ms`
+    timeoutMessage: `docker exec curl timed out after ${s3DockerCurlTimeoutMs}ms`,
+    rejectOnError: false
   });
   if (proc.code !== 0) {
     const stderr = new TextDecoder().decode(proc.stderr).replace(/\s+/g, " ").trim();
+    throwIfDockerCommandUnavailableResult({
+      code: proc.code,
+      stderr
+    });
     throw new S3HttpError(503, `S3 HTTP transport failed via docker exec${stderr ? `: ${stderr.slice(0, 240)}` : ""}`);
   }
   return responseFromCurlOutput(new Uint8Array(proc.stdout));
@@ -11329,14 +11888,14 @@ import {
   existsSync as existsSync6,
   openSync,
   readSync,
-  realpathSync as realpathSync3,
-  statSync as statSync3
+  realpathSync as realpathSync4,
+  statSync as statSync4
 } from "node:fs";
 import { lstat, open, readdir, readFile as readFile2, stat } from "node:fs/promises";
-import { basename, join as join7, relative as relative2 } from "node:path";
+import { basename, join as join8, relative as relative3 } from "node:path";
 function isSqliteFile(fullPath) {
   try {
-    const stat2 = statSync3(fullPath);
+    const stat2 = statSync4(fullPath);
     if (!stat2.isFile() || stat2.size < 16)
       return false;
     const buf = Buffer.alloc(16);
@@ -11404,7 +11963,7 @@ async function discoverSqliteFilesAsync(cwd, omitDirNames, signal) {
         return;
       if (omitSet.has(entry.toLowerCase()))
         continue;
-      const full = join7(dir, entry);
+      const full = join8(dir, entry);
       let entryStat;
       try {
         entryStat = await lstat(full);
@@ -11421,7 +11980,7 @@ async function discoverSqliteFilesAsync(cwd, omitDirNames, signal) {
           continue;
         if (!await isSqliteFileAsync(full))
           continue;
-        const rel = relative2(cwd, full);
+        const rel = relative3(cwd, full);
         if (rel.startsWith("..") || rel.startsWith("/"))
           continue;
         results.push({
@@ -11448,18 +12007,18 @@ function validateDbPath(cwd, dbPath) {
   const parts = dbPath.split(/[\\/]+/);
   if (parts.some((p) => p === ".." || p.toLowerCase() === ".git" || p.toLowerCase() === ".code-viewer"))
     return null;
-  const full = join7(cwd, dbPath);
+  const full = join8(cwd, dbPath);
   if (!existsSync6(full))
     return null;
   let realCwd;
   let realFull;
   try {
-    realCwd = realpathSync3(cwd);
-    realFull = realpathSync3(full);
+    realCwd = realpathSync4(cwd);
+    realFull = realpathSync4(full);
   } catch {
     return null;
   }
-  const rel = relative2(realCwd, realFull);
+  const rel = relative3(realCwd, realFull);
   if (rel === "" || rel.startsWith("..") || rel.startsWith("/"))
     return null;
   if (!isSqliteFile(realFull))
@@ -11585,7 +12144,7 @@ function resolveEnvValue(raw, composeDirEnv = {}) {
 }
 async function readDotenvAsync(composeDir) {
   try {
-    const content = await readFile2(join7(composeDir, ".env"), "utf-8");
+    const content = await readFile2(join8(composeDir, ".env"), "utf-8");
     return parseDotenvContent(content);
   } catch {
     return {};
@@ -11707,7 +12266,7 @@ function parseComposeContent(content, filepath, composeDir, cwd, composeDirEnv,
   for (let match = serviceRegex.exec(servicesBlock);match !== null; match = serviceRegex.exec(servicesBlock)) {
     servicePositions.push({ name: match[1], start: match.index });
   }
-  const relDir = relative2(cwd, composeDir);
+  const relDir = relative3(cwd, composeDir);
   const isRoot = relDir === "" || relDir === ".";
   const relDirSlash = relDir.replace(/\\/g, "/");
   const filename = basename(filepath);
@@ -11807,7 +12366,7 @@ async function discoverDockerDatabasesAsync(cwd, omitDirNames = [], signal) {
     if (depth > MAX_SCAN_DEPTH)
       return;
     for (const filename of COMPOSE_FILENAMES) {
-      const filepath = join7(dir, filename);
+      const filepath = join8(dir, filename);
       if (await pathExistsAsync(filepath)) {
         await parseComposeFileAsync(filepath, dir, cwd, results);
         break;
@@ -11830,7 +12389,7 @@ async function discoverDockerDatabasesAsync(cwd, omitDirNames = [], signal) {
         return;
       if (omitSet.has(entry.toLowerCase()))
         continue;
-      const full = join7(dir, entry);
+      const full = join8(dir, entry);
       let entryStat;
       try {
         entryStat = await lstat(full);
@@ -11974,12 +12533,12 @@ import {
   readdirSync as nodeReaddirSync,
   watch as nodeWatch
 } from "node:fs";
-import { join as join8, relative as relative3 } from "node:path";
+import { join as join9, relative as relative4 } from "node:path";
 function normalizeRelativePath(path) {
   return path.replace(/\\/g, "/").replace(/^\/+/, "");
 }
 function isInsideRoot(root, path) {
-  const rel = relative3(root, path).replace(/\\/g, "/");
+  const rel = relative4(root, path).replace(/\\/g, "/");
   return rel === "" || !rel.startsWith("..") && !rel.startsWith("/");
 }
 function startWorktreeUpdateWatch(options) {
@@ -12017,7 +12576,7 @@ function startWorktreeUpdateWatch(options) {
   const pendingChangedPaths = new Set;
   let watchLimitReported = false;
   const ignored = (path) => isSkippableSearchPath(normalizeRelativePath(path), options.omitDirNames, options.excludeNames);
-  const directoryRelativePath = (dir) => normalizeRelativePath(relative3(options.root, dir));
+  const directoryRelativePath = (dir) => normalizeRelativePath(relative4(options.root, dir));
   const ignoredDirectory = (dir) => {
     const rel = directoryRelativePath(dir);
     return Boolean(rel && ignored(rel));
@@ -12083,7 +12642,7 @@ function startWorktreeUpdateWatch(options) {
     for (const entry of entries) {
       if (!entry.isDirectory())
         continue;
-      const child = join8(dir, entry.name);
+      const child = join9(dir, entry.name);
       if (ignoredDirectory(child))
         continue;
       children.push(child);
@@ -12167,10 +12726,10 @@ function startWorktreeUpdateWatch(options) {
           scheduleUpdate();
           return;
         }
-        const changed = normalizeRelativePath(join8(rel, filename.toString()));
+        const changed = normalizeRelativePath(join9(rel, filename.toString()));
         if (ignored(changed))
           return;
-        const fullChangedPath = join8(options.root, changed);
+        const fullChangedPath = join9(options.root, changed);
         if (!isInsideRoot(options.root, fullChangedPath))
           return;
         if (initialScanAsync) {
@@ -12219,9 +12778,9 @@ var init_worktree_watcher = __esm(() => {
 });
 
 // web-src/server/state-store.ts
-import { join as join9 } from "node:path";
+import { join as join10 } from "node:path";
 function codeViewerPath(root, fileName) {
-  return join9(root, CODE_VIEWER_DIR2, fileName);
+  return join10(root, CODE_VIEWER_DIR2, fileName);
 }
 function isRecord(value) {
   return !!value && typeof value === "object" && !Array.isArray(value);
@@ -14142,9 +14701,9 @@ var init_handle_s3 = __esm(() => {
 });
 
 // web-src/server/database/query-history.ts
-import { join as join10 } from "node:path";
+import { join as join11 } from "node:path";
 function historyFilePath(root) {
-  return join10(root, CODE_VIEWER_DIR3, HISTORY_FILE_NAME);
+  return join11(root, CODE_VIEWER_DIR3, HISTORY_FILE_NAME);
 }
 function emptyState() {
   return { version: 1, entries: [] };
@@ -14294,9 +14853,9 @@ var init_query_history = __esm(() => {
 // web-src/server/database/snapshot-store.ts
 import { createHash as createHash5, randomBytes as randomBytes2 } from "node:crypto";
 import { mkdirSync as mkdirSync3 } from "node:fs";
-import { join as join11 } from "node:path";
+import { join as join12 } from "node:path";
 async function getStoreDb(cwd) {
-  const dbPath = join11(cwd, CODE_VIEWER_DIR4, SNAPSHOT_DB_NAME);
+  const dbPath = join12(cwd, CODE_VIEWER_DIR4, SNAPSHOT_DB_NAME);
   if (storeDb && storeDbPath === dbPath)
     return storeDb;
   if (storeDb) {
@@ -14304,7 +14863,7 @@ async function getStoreDb(cwd) {
       storeDb.close();
     } catch {}
   }
-  mkdirSync3(join11(cwd, CODE_VIEWER_DIR4), { recursive: true });
+  mkdirSync3(join12(cwd, CODE_VIEWER_DIR4), { recursive: true });
   const DbClass = await loadSqliteClass();
   storeDb = new DbClass(dbPath);
   storeDbPath = dbPath;
@@ -14910,9 +15469,9 @@ var init_snapshot_runner = __esm(() => {
 });
 
 // web-src/server/database/tabs-store.ts
-import { join as join12 } from "node:path";
+import { join as join13 } from "node:path";
 function tabsFilePath(root) {
-  return join12(root, CODE_VIEWER_DIR5, TABS_FILE_NAME);
+  return join13(root, CODE_VIEWER_DIR5, TABS_FILE_NAME);
 }
 function emptyState2() {
   return { version: 1, tabs: [], activeTabId: null };
@@ -16576,8 +17135,8 @@ var init_handle = __esm(() => {
 });
 
 // web-src/server/doctor.ts
-import { accessSync, constants, readFileSync as readFileSync5, statSync as statSync4 } from "node:fs";
-import { dirname as dirname3, join as join13, relative as relative4 } from "node:path";
+import { accessSync as accessSync2, constants as constants2, readFileSync as readFileSync5, statSync as statSync5 } from "node:fs";
+import { dirname as dirname4, join as join14, relative as relative5 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 function statusWorse(a, b) {
   const rank = { ok: 0, warn: 1, error: 2 };
@@ -16666,12 +17225,12 @@ function findCodeViewerPackageJson() {
   try {
     let cursor;
     try {
-      cursor = dirname3(fileURLToPath2(import.meta.url));
+      cursor = dirname4(fileURLToPath2(import.meta.url));
     } catch {
-      cursor = dirname3(process.argv[1] || ".");
+      cursor = dirname4(process.argv[1] || ".");
     }
     for (let depth = 0;depth < 8; depth += 1) {
-      const candidate = join13(cursor, "package.json");
+      const candidate = join14(cursor, "package.json");
       try {
         const raw = readFileSync5(candidate, "utf8");
         const pkg = JSON.parse(raw);
@@ -16679,7 +17238,7 @@ function findCodeViewerPackageJson() {
           return { version: pkg.version, path: candidate };
         }
       } catch {}
-      const next = dirname3(cursor);
+      const next = dirname4(cursor);
       if (next === cursor)
         break;
       cursor = next;
@@ -16767,9 +17326,9 @@ async function checkSqlite(cwd) {
   return { id: "sqlite", title: "SQLite driver", rows };
 }
 async function trySnapshotDbOpen(cwd) {
-  const dbPath = join13(cwd, SNAPSHOT_DB_REL);
+  const dbPath = join14(cwd, SNAPSHOT_DB_REL);
   try {
-    statSync4(dbPath);
+    statSync5(dbPath);
   } catch {
     return { kind: "skipped" };
   }
@@ -16788,17 +17347,17 @@ async function trySnapshotDbOpen(cwd) {
   }
 }
 function checkSnapshotStore(cwd) {
-  const dbPath = join13(cwd, SNAPSHOT_DB_REL);
-  const dir = dirname3(dbPath);
+  const dbPath = join14(cwd, SNAPSHOT_DB_REL);
+  const dir = dirname4(dbPath);
   let dirStatus = "ok";
   let dirDetail = dir;
   let dirHint;
   try {
-    accessSync(dir, constants.W_OK);
+    accessSync2(dir, constants2.W_OK);
     dirDetail = `${dir} (writable)`;
   } catch {
     try {
-      statSync4(dir);
+      statSync5(dir);
       dirStatus = "error";
       dirDetail = `${dir} (not writable)`;
       dirHint = "Snapshot creation will fail until the directory is writable. " + "Check filesystem permissions on the .code-viewer directory.";
@@ -16808,7 +17367,7 @@ function checkSnapshotStore(cwd) {
   }
   let dbDetail = dbPath;
   try {
-    const stat2 = statSync4(dbPath);
+    const stat2 = statSync5(dbPath);
     dbDetail = `${dbPath} (${stat2.size.toLocaleString()} bytes)`;
   } catch {
     dbDetail = `${dbPath} (not created yet — created on first snapshot)`;
@@ -16834,7 +17393,7 @@ function checkSnapshotStore(cwd) {
   };
 }
 async function checkGit(cwd, signal) {
-  const versionRes = await runCached(versionCache, TTL.version, "git", ["--version"], TIMEOUT.version, signal);
+  const versionRes = await runCached(versionCache, TTL.version, commandForExternal("git"), ["--version"], TIMEOUT.version, signal);
   if (!versionRes || versionRes.code !== 0) {
     return {
       id: "git",
@@ -16844,7 +17403,7 @@ async function checkGit(cwd, signal) {
           id: "git.binary",
           title: "git binary",
           status: "error",
-          detail: "not found in PATH",
+          detail: versionRes && isCommandNotFoundResult("git", versionRes) ? commandNotFoundDetail("git") : "git command failed",
           hint: "git is required for diff, history, and blame features. Install git and ensure it is on PATH."
         }
       ]
@@ -16858,11 +17417,11 @@ async function checkGit(cwd, signal) {
       detail: firstLine2(versionRes.stdout)
     }
   ];
-  const repoCheck = await runCached(gitCache, TTL.gitRepo, "git", ["rev-parse", "--is-inside-work-tree"], TIMEOUT.git, signal, cwd);
+  const repoCheck = await runCached(gitCache, TTL.gitRepo, commandForExternal("git"), ["rev-parse", "--is-inside-work-tree"], TIMEOUT.git, signal, cwd);
   if (repoCheck && repoCheck.code === 0 && /true/.test(repoCheck.stdout)) {
-    const topRes = await runCached(gitCache, TTL.gitRepo, "git", ["rev-parse", "--show-toplevel"], TIMEOUT.git, signal, cwd);
+    const topRes = await runCached(gitCache, TTL.gitRepo, commandForExternal("git"), ["rev-parse", "--show-toplevel"], TIMEOUT.git, signal, cwd);
     const top = topRes?.stdout.trim() || cwd;
-    const insideCwd = relative4(top, cwd) || ".";
+    const insideCwd = relative5(top, cwd) || ".";
     rows.push({
       id: "git.repo",
       title: "Working tree",
@@ -16881,10 +17440,10 @@ async function checkGit(cwd, signal) {
   return { id: "git", title: "Git", rows };
 }
 async function detectComposeBinary(signal) {
-  const v2 = await runCached(versionCache, TTL.version, "docker", ["compose", "version", "--short"], TIMEOUT.version, signal);
+  const v2 = await runCached(versionCache, TTL.version, commandForExternal("docker"), ["compose", "version", "--short"], TIMEOUT.version, signal);
   if (v2 && v2.code === 0) {
     return {
-      cmd: { binary: "docker", subcommand: ["compose"] },
+      cmd: { binary: commandForExternal("docker"), subcommand: ["compose"] },
       v2Version: firstLine2(v2.stdout)
     };
   }
@@ -16937,13 +17496,13 @@ async function checkDocker(signal, discoveryResult) {
   const summary = summarizeDockerSources(discoveryResult);
   const dockerSourcesPresent = summary.total > 0;
   const rows = [];
-  const dockerVersion = await runCached(versionCache, TTL.version, "docker", ["--version"], TIMEOUT.version, signal);
+  const dockerVersion = await runCached(versionCache, TTL.version, commandForExternal("docker"), ["--version"], TIMEOUT.version, signal);
   const dockerOk = dockerVersion?.code === 0;
   rows.push({
     id: "docker.binary",
     title: "docker CLI",
     status: dockerOk ? "ok" : dockerSourcesPresent ? "error" : "warn",
-    detail: dockerOk ? firstLine2(dockerVersion.stdout) : "not found in PATH",
+    detail: dockerOk ? firstLine2(dockerVersion.stdout) : dockerVersion && isCommandNotFoundResult("docker", dockerVersion) ? commandNotFoundDetail("docker") : "docker command failed",
     ...dockerOk ? {} : {
       hint: dockerSourcesPresent ? "Compose files reference Docker services that need the docker CLI. Install Docker Desktop or the docker engine." : "docker is optional unless this project uses Docker compose data sources."
     }
@@ -16974,7 +17533,7 @@ async function checkDocker(signal, discoveryResult) {
       hint: "docker-compose v1 standalone is legacy. Prefer the Docker Compose v2 plugin (`docker compose ...`)."
     });
   }
-  const dockerInfo = dockerOk ? await runCached(dockerInfoCache, TTL.dockerInfo, "docker", ["info", "--format", "{{.ServerVersion}}"], TIMEOUT.dockerInfo, signal) : null;
+  const dockerInfo = dockerOk ? await runCached(dockerInfoCache, TTL.dockerInfo, commandForExternal("docker"), ["info", "--format", "{{.ServerVersion}}"], TIMEOUT.dockerInfo, signal) : null;
   if (dockerOk) {
     if (dockerInfo && dockerInfo.code === 0) {
       rows.push({
@@ -17502,6 +18061,7 @@ async function handleDoctor(ctx) {
 var SNAPSHOT_DB_REL = ".code-viewer/db-snapshots.sqlite", REQUIRED_NODE_MAJOR = 20, TTL, TIMEOUT, versionCache, gitCache, dockerInfoCache, CACHE_KEY_SEP = "\x01", composeConfigCache, composePsCache2, doctorGeneration = 0, DEFAULT_DATASTORE_PROBE_TIMEOUT_MS = 2000, DEFAULT_DATASTORE_CONNECTIVITY_DEPS;
 var init_doctor = __esm(() => {
   init_cli_helpers();
+  init_command_resolver();
   init_docker();
   init_elasticsearch();
   init_redis();
@@ -17549,6 +18109,7 @@ function parseDoctorCliArgs(argv) {
   let cwd = process.cwd();
   let port = 0;
   let json2 = false;
+  const commandOverrides = [];
   for (let i = 0;i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--help" || arg === "-h" || arg === "help") {
@@ -17568,6 +18129,23 @@ function parseDoctorCliArgs(argv) {
       cwd = next;
       continue;
     }
+    if (arg === "--bin") {
+      const next = argv[++i];
+      if (!next) {
+        return {
+          kind: "error",
+          message: "--bin requires <name>=<absolute-path>"
+        };
+      }
+      const parsed = parseExternalCommandOverride(next, "--bin", [
+        "git",
+        "docker"
+      ]);
+      if (parsed.ok === false)
+        return { kind: "error", message: parsed.error };
+      commandOverrides.push(parsed.override);
+      continue;
+    }
     if (arg === "--port") {
       const next = argv[++i];
       if (!next)
@@ -17584,7 +18162,15 @@ function parseDoctorCliArgs(argv) {
     }
     return { kind: "error", message: `unknown argument: ${arg}` };
   }
-  return { kind: "run", args: { cwd, port, json: json2 } };
+  return {
+    kind: "run",
+    args: {
+      cwd,
+      port,
+      json: json2,
+      ...commandOverrides.length ? { commandOverrides } : {}
+    }
+  };
 }
 function formatDoctorReportText(report) {
   const lines = [];
@@ -17635,7 +18221,17 @@ async function runDoctorCli(argv) {
 `);
     return;
   }
-  const { cwd, port, json: json2 } = parsed.args;
+  const { cwd, port, json: json2, commandOverrides = [] } = parsed.args;
+  const commandConfig = configureExternalCommands({
+    cwd,
+    cliOverrides: commandOverrides,
+    allowedNames: ["git", "docker"]
+  });
+  if (commandConfig.ok === false) {
+    process.stderr.write(`code-viewer doctor: ${commandConfig.error}
+`);
+    process.exit(2);
+  }
   const report = await buildDoctorReport({
     cwd,
     scopeOmitDirNames: DEFAULT_WORKTREE_OMIT_DIR_NAMES,
@@ -17655,12 +18251,13 @@ async function runDoctorCli(argv) {
 var DOCTOR_HELP = `code-viewer doctor — diagnose the current environment
 
 Usage:
-  code-viewer doctor [--cwd <path>] [--port <N>] [--json]
+  code-viewer doctor [--cwd <path>] [--port <N>] [--json] [--bin <git|docker>=<path>]
   code-viewer doctor agent-help
 
 Options:
   --cwd <path>   Working directory to inspect (default: process.cwd()).
   --port <N>     Listening port to mention in the report (default: 0 = no server).
+  --bin <n>=<p>  Override git/docker executable path. Repeatable.
   --json         Print the full DoctorReport as JSON instead of a summary.
   --help, -h     Show this help.
 
@@ -17672,6 +18269,7 @@ Exit codes:
   2  invalid arguments
 `, STATUS_SYMBOL;
 var init_doctor_cli = __esm(() => {
+  init_command_resolver();
   init_doctor();
   init_git();
   STATUS_SYMBOL = {
@@ -17700,7 +18298,7 @@ function normalizeNewDirectoryName(name) {
 
 // web-src/server/cache.ts
 import { lstatSync as lstatSync3 } from "node:fs";
-import { join as join14 } from "node:path";
+import { join as join15 } from "node:path";
 function cacheFresh(cached, now = Date.now(), ttlMs = CACHE_TTL_MS) {
   return !!cached && now - cached.storedAt <= ttlMs;
 }
@@ -17715,7 +18313,7 @@ function setTimedCacheEntry(cache, key, value, now = Date.now(), maxEntries = MA
 }
 function worktreeFileSignature(path, cwd) {
   try {
-    const stats = lstatSync3(join14(cwd, path));
+    const stats = lstatSync3(join15(cwd, path));
     const inode = "ino" in stats ? stats.ino : 0;
     return `state:file|size:${stats.size}|mtime:${stats.mtimeMs}|ctime:${stats.ctimeMs}|ino:${inode}`;
   } catch {
@@ -17761,12 +18359,12 @@ function startDevAssetReload(options) {
 var init_dev_assets = () => {};
 
 // web-src/server/search-service.ts
-import { existsSync as existsSync7, lstatSync as lstatSync4, readFileSync as readFileSync6, realpathSync as realpathSync4 } from "node:fs";
-import { join as join15, relative as relative5 } from "node:path";
+import { existsSync as existsSync7, lstatSync as lstatSync4, readFileSync as readFileSync6, realpathSync as realpathSync5 } from "node:fs";
+import { join as join16, relative as relative6 } from "node:path";
 function rgAvailable(cwd) {
   if (rgAvailableCache !== null)
     return rgAvailableCache;
-  const proc = runSync(["rg", "--version"], cwd);
+  const proc = runSync([commandForExternal("rg"), "--version"], cwd);
   rgAvailableCache = proc.code === 0;
   return rgAvailableCache;
 }
@@ -17783,18 +18381,18 @@ function safeWorktreePath(env, path) {
     return null;
   if (isGitInternalPath(path))
     return null;
-  const full = join15(env.cwd, path);
+  const full = join16(env.cwd, path);
   if (!existsSync7(full))
     return null;
   let realCwd;
   let realFull;
   try {
-    realCwd = realpathSync4(env.cwd);
-    realFull = realpathSync4(full);
+    realCwd = realpathSync5(env.cwd);
+    realFull = realpathSync5(full);
   } catch {
     return null;
   }
-  const rel = relative5(realCwd, realFull);
+  const rel = relative6(realCwd, realFull);
   if (rel === "" || rel.startsWith("..") || rel.startsWith("/") || rel.startsWith("\\"))
     return null;
   if (isGitInternalPath(rel))
@@ -17844,6 +18442,7 @@ function grepWorktree(env, req) {
   if (rgAvailable(env.cwd)) {
     const safePaths = paths.filter((path) => safeWorktreePath(env, path));
     const args = buildRgArgs(req.query, req.max, safePaths, req.regex, env.omitDirNames, env.excludeNames);
+    args[0] = commandForExternal("rg");
     const proc = runSync(args, env.cwd, { timeout: 5000 });
     const stdout = proc.stdout;
     const matches2 = parseRgOutput(stdout, req.max, env.omitDirNames, env.excludeNames).filter((match) => isSafePath(match.path) && !isGitInternalPath(match.path) && !isSkippableSearchPath(match.path, env.omitDirNames, env.excludeNames) && !!safeWorktreePath(env, match.path));
@@ -17873,7 +18472,7 @@ function grepWorktree(env, req) {
 function grepTreeRef(env, req) {
   const safePaths = filterCallerPaths(env, req.paths);
   const args = [
-    "git",
+    commandForExternal("git"),
     "-c",
     "core.quotepath=false",
     "grep",
@@ -17899,6 +18498,17 @@ function grepTreeRef(env, req) {
   };
 }
 function grepRepo(env, req) {
+  const isWorktree = req.ref === "worktree" || req.ref === "";
+  if (!isWorktree) {
+    const refCheck = verifyTreeRefResult(req.ref, env.cwd);
+    if (refCheck.ok !== true) {
+      return {
+        ok: false,
+        error: refCheck.error,
+        status: refCheck.status
+      };
+    }
+  }
   if (!req.query.trim()) {
     return {
       ok: true,
@@ -17910,24 +18520,32 @@ function grepRepo(env, req) {
       }
     };
   }
-  if (req.ref === "worktree" || req.ref === "") {
+  if (isWorktree) {
     return { ok: true, value: grepWorktree(env, req) };
   }
-  if (!verifyTreeRef(req.ref, env.cwd)) {
-    return { ok: false, error: "invalid target" };
-  }
   return { ok: true, value: grepTreeRef(env, req) };
 }
 function listRepoFiles(env, ref, generation) {
-  if (ref !== "worktree" && !verifyTreeRef(ref, env.cwd)) {
-    return { ok: false, error: "invalid target" };
+  if (ref !== "worktree" && ref !== "") {
+    const refCheck = verifyTreeRefResult(ref, env.cwd);
+    if (refCheck.ok !== true) {
+      return {
+        ok: false,
+        error: refCheck.error,
+        status: refCheck.status
+      };
+    }
   }
   const effectiveRef = ref || "worktree";
-  const entries = listTree(effectiveRef, "", env.cwd, {
+  const tree = listTreeResult(effectiveRef, "", env.cwd, {
     recursive: true,
     omitDirNames: env.omitDirNames,
     excludeNames: env.excludeNames
-  }).entries.filter((entry) => !isExcludedScopePath(entry.path, env.excludeNames));
+  });
+  if (tree.error) {
+    return { ok: false, error: tree.error, status: tree.status };
+  }
+  const entries = tree.entries.filter((entry) => !isExcludedScopePath(entry.path, env.excludeNames));
   return {
     ok: true,
     value: buildFileSearchList(effectiveRef, generation, entries)
@@ -17935,6 +18553,7 @@ function listRepoFiles(env, ref, generation) {
 }
 var rgAvailableCache = null;
 var init_search_service = __esm(() => {
+  init_command_resolver();
   init_git();
   init_runtime();
   init_search();
@@ -17942,7 +18561,7 @@ var init_search_service = __esm(() => {
 
 // web-src/server/mcp.ts
 import { readFileSync as readFileSync7 } from "node:fs";
-import { join as join16 } from "node:path";
+import { join as join17 } from "node:path";
 function defaultMcpTools(options = {}) {
   return [
     {
@@ -18481,7 +19100,10 @@ function runStatusTool(input, defaultCwd) {
   }
   try {
     const report = buildStatusReport({ root: resolved.root, ref, limit });
-    return { text: JSON.stringify(report, null, 2) };
+    return {
+      text: JSON.stringify(report, null, 2),
+      isError: !!(report.changed.error || report.staged.error)
+    };
   } catch (err) {
     const detail = err instanceof Error ? err.message : String(err);
     return { text: `status failed: ${detail}`, isError: true };
@@ -19413,7 +20035,7 @@ var init_mcp = __esm(() => {
   init_search_cli();
   init_search_service();
   init_status_cli();
-  PACKAGE_VERSION = JSON.parse(readFileSync7(join16(ROOT, "package.json"), "utf8")).version;
+  PACKAGE_VERSION = JSON.parse(readFileSync7(join17(ROOT, "package.json"), "utf8")).version;
   MCP_SERVER_INFO = {
     name: "code-viewer",
     title: "code-viewer",
@@ -19495,21 +20117,21 @@ var init_state_route = __esm(() => {
 var exports_preview = {};
 import {
   closeSync as closeSync2,
-  constants as constants2,
+  constants as constants3,
   existsSync as existsSync8,
   lstatSync as lstatSync5,
   mkdirSync as mkdirSync4,
   openSync as openSync2,
   readFileSync as readFileSync8,
-  realpathSync as realpathSync5,
+  realpathSync as realpathSync6,
   renameSync,
-  statSync as statSync5,
+  statSync as statSync6,
   unlinkSync as unlinkSync2,
   watch,
   writeFileSync as writeFileSync2
 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
-import { basename as basename3, dirname as dirname4, extname as extname2, join as join17, relative as relative6 } from "node:path";
+import { basename as basename3, dirname as dirname5, extname as extname2, join as join18, relative as relative7 } from "node:path";
 function parseCli() {
   const rest = [];
   for (let i = 2;i < process.argv.length; i++) {
@@ -19518,15 +20140,15 @@ function parseCli() {
       console.log(`code-viewer ${VERSION}
 
 Usage:
-  code-viewer [--cwd <repo>] [--port <port>] [--open] [git-diff-args...]
-  code-viewer status [--cwd <repo>] [--ref <ref>] [--limit <N>] [--json]
+  code-viewer [--cwd <repo>] [--port <port>] [--open] [--bin <name>=<path>] [git-diff-args...]
+  code-viewer status [--cwd <repo>] [--bin git=<path>] [--ref <ref>] [--limit <N>] [--json]
   code-viewer annotate <start|add|add-db|rename|edit|move|list|delete|clear> [options]
-  code-viewer query <sources|schemas|schema|columns|ddl|exec|list|clear|snapshot|diff|search|redis|elasticsearch|s3> [options]
-  code-viewer search code --term <text> [--ref <ref>] [--path <p>...] [--regex] [--max <n>] [--json]
-  code-viewer search files --term <pattern> [--ref <ref>] [--max <n>] [--json]
-  code-viewer file <blame|history|show|diff> --path <p> [--ref <ref>] [...subcommand options] [--json]
+  code-viewer query <sources|schemas|schema|columns|ddl|exec|list|clear|snapshot|diff|search|redis|elasticsearch|s3> [options] [--bin git=<path>]
+  code-viewer search code --term <text> [--ref <ref>] [--path <p>...] [--regex] [--max <n>] [--json] [--bin git=<path>]
+  code-viewer search files --term <pattern> [--ref <ref>] [--max <n>] [--json] [--bin git=<path>]
+  code-viewer file <blame|history|show|diff> --path <p> [--ref <ref>] [...subcommand options] [--json] [--bin git=<path>]
   code-viewer skill install [--agent <list>] [--global]
-  code-viewer doctor [--cwd <path>] [--port <N>] [--json]
+  code-viewer doctor [--cwd <path>] [--port <N>] [--json] [--bin <git|docker>=<path>]
   code-viewer agent-help
   code-viewer help
 
@@ -19562,9 +20184,8 @@ Examples:
         process.exit(1);
       }
       try {
-        const nextReal = realpathSync5(next);
-        const candidate = repoRoot(next);
-        cwd = candidate === nextReal ? candidate : nextReal;
+        cwd = realpathSync6(next);
+        cwdWasExplicit = true;
       } catch {
         console.error("--cwd must point to an existing directory");
         process.exit(1);
@@ -19579,6 +20200,18 @@ Examples:
       listenPort = parsed;
     } else if (arg === "--open") {
       openAfterStart = true;
+    } else if (arg === "--bin") {
+      const next = process.argv[++i];
+      if (!next) {
+        console.error("--bin requires <name>=<absolute-path>");
+        process.exit(1);
+      }
+      const parsed = parseExternalCommandOverride(next);
+      if (parsed.ok === false) {
+        console.error(parsed.error);
+        process.exit(1);
+      }
+      commandOverrides.push(parsed.override);
     } else if (arg === "--allow-upload") {} else if (arg === "--scope-omit-dir") {
       const next = process.argv[++i];
       if (!next) {
@@ -19595,6 +20228,21 @@ Examples:
   }
   if (rest.length)
     cliArgs = rest;
+  const commandConfig = configureExternalCommands({
+    cwd,
+    cliOverrides: commandOverrides
+  });
+  if (commandConfig.ok === false) {
+    console.error(commandConfig.error);
+    process.exit(1);
+  }
+  const candidate = repoRoot(cwd);
+  if (cwdWasExplicit) {
+    if (candidate === cwd)
+      cwd = candidate;
+  } else if (candidate) {
+    cwd = candidate;
+  }
   warnIfLegacyConfigPresent();
   if (scopeOmitDirCliOverride) {
     scopeOmitDirNames = scopeOmitDirCliOverride;
@@ -19603,7 +20251,7 @@ Examples:
 }
 function warnIfLegacyConfigPresent() {
   try {
-    if (existsSync8(join17(cwd, ".code-viewer.json"))) {
+    if (existsSync8(join18(cwd, ".code-viewer.json"))) {
       console.warn("[code-viewer] .code-viewer.json is no longer used; configure scope and upload from Viewer Settings instead. The file can be safely removed.");
     }
   } catch {}
@@ -19710,7 +20358,7 @@ function staticFile(pathname) {
   const spec = map[pathname];
   if (!spec)
     return null;
-  const full = join17(WEB_ROOT, spec[0]);
+  const full = join18(WEB_ROOT, spec[0]);
   if (!existsSync8(full))
     return text("not found", 404);
   return new Response(readFileSync8(full), {
@@ -19718,17 +20366,17 @@ function staticFile(pathname) {
   });
 }
 function buildRangeArgs(range) {
-  const refs2 = [];
+  const refs = [];
   if (range.from && range.from !== "worktree")
-    refs2.push(range.from);
+    refs.push(range.from);
   if (range.to && range.to !== "worktree")
-    refs2.push(range.to);
-  return { args: refs2.length ? refs2 : cliArgs, refs: refs2 };
+    refs.push(range.to);
+  return { args: refs.length ? refs : cliArgs, refs };
 }
-function includeUntracked(range, refs2) {
+function includeUntracked(range, refs) {
   const toWorktree = !range.to || range.to === "worktree";
-  if (refs2.length > 0)
-    return toWorktree && refs2.length < 2;
+  if (refs.length > 0)
+    return toWorktree && refs.length < 2;
   return cliArgs.length === 0 || cliArgs.length === 1 && cliArgs[0] === "HEAD";
 }
 function guessMediaKind(path) {
@@ -19815,11 +20463,13 @@ function computePayload(extras, range, pathFilter = "") {
       generation
     };
   }
-  const { args, refs: refs2 } = buildRangeArgs(range);
+  const { args, refs } = buildRangeArgs(range);
   const fullArgs = [...extras, ...args];
-  const files = fileMeta(fullArgs, cwd, false);
-  if (includeUntracked(range, refs2))
+  const metaResult = fileMetaResult(fullArgs, cwd, false);
+  const files = metaResult.files;
+  if (!metaResult.error && includeUntracked(range, refs)) {
     files.push(...untrackedMeta(cwd));
+  }
   const filteredFiles = pathFilter ? files.filter((file) => file.path === pathFilter || file.old_path === pathFilter) : files;
   filteredFiles.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
   filteredFiles.forEach((file, i) => {
@@ -19839,14 +20489,15 @@ function computePayload(extras, range, pathFilter = "") {
     return acc;
   }, { files: meta.length, additions: 0, deletions: 0 });
   const toWorktree = !range.to || range.to === "worktree";
-  const label = refs2.length ? `${refs2.join(" .. ")}${toWorktree && refs2.length === 1 ? " .. worktree" : ""}` : cliArgs.join(" ");
+  const label = refs.length ? `${refs.join(" .. ")}${toWorktree && refs.length === 1 ? " .. worktree" : ""}` : cliArgs.join(" ");
   return {
     files: meta,
     totals,
     range: label || "HEAD",
     project: basename3(cwd),
     branch: currentBranch(cwd) || undefined,
-    generation
+    generation,
+    ...metaResult.error ? { error: metaResult.error } : {}
   };
 }
 function handleDiffJson(url) {
@@ -19962,12 +20613,12 @@ function safeWorktreePath2(path) {
   return safeWorktreePath(currentSearchEnv(), path);
 }
 function worktreePath(path) {
-  return join17(cwd, path);
+  return join18(cwd, path);
 }
 function safeOpenWorktreePath(path) {
   if (path === "") {
     try {
-      const realCwd = realpathSync5(cwd);
+      const realCwd = realpathSync6(cwd);
       if (isGitInternalPath(realCwd))
         return null;
       return realCwd;
@@ -19978,7 +20629,7 @@ function safeOpenWorktreePath(path) {
   return safeWorktreePath2(path);
 }
 function parentRepoPath(path) {
-  const parent = dirname4(path);
+  const parent = dirname5(path);
   return parent === "." ? "" : parent;
 }
 function isoDate(ms) {
@@ -19989,7 +20640,7 @@ function worktreeFileMetadata(path, knownSize) {
   if (!full)
     return {};
   try {
-    const stat2 = statSync5(full);
+    const stat2 = statSync6(full);
     return {
       size: knownSize ?? stat2.size,
       created_at: isoDate(stat2.birthtimeMs),
@@ -20014,7 +20665,7 @@ function directoryMetadata(target, path) {
     if (!full)
       return {};
     try {
-      const stat2 = statSync5(full);
+      const stat2 = statSync6(full);
       return {
         created_at: isoDate(stat2.birthtimeMs),
         updated_at: isoDate(stat2.mtimeMs)
@@ -20065,19 +20716,25 @@ function handleTree(url) {
     return text("invalid path", 400);
   if ((target === "worktree" || target === "") && isGitInternalPath(path))
     return text("forbidden", 403);
-  if (target !== "worktree" && !verifyTreeRef(target, cwd))
-    return text("invalid target", 400);
+  if (target !== "worktree") {
+    const refCheck = verifyTreeRefResult(target, cwd);
+    if (refCheck.ok !== true)
+      return text(refCheck.error, refCheck.status ?? 400);
+  }
   const recursive = url.searchParams.get("recursive") === "1";
   if (invalidScopeOmitDirNamesQuery(url))
     return text("invalid omit dirs", 400);
   if (invalidScopeExcludeNamesQuery(url))
     return text("invalid exclude names", 400);
   const excludeNames = scopeExcludeNamesFromQuery(url);
-  const entries = listTree(target, path, cwd, {
+  const tree = listTreeResult(target, path, cwd, {
     recursive,
     omitDirNames: scopeOmitDirNamesFromQuery(url),
     excludeNames
-  }).entries.filter((entry) => !isExcludedScopePath(entry.path, excludeNames));
+  });
+  if (tree.error)
+    return text(tree.error, tree.status ?? 500);
+  const entries = tree.entries.filter((entry) => !isExcludedScopePath(entry.path, excludeNames));
   return json2({
     ref: target,
     path,
@@ -20141,7 +20798,7 @@ function handleFiles2(url) {
     return json2(cached.body);
   const result = listRepoFiles(currentSearchEnv(omitDirNames, excludeNames), target, generation);
   if (result.ok !== true)
-    return text(result.error, 400);
+    return text(result.error, result.status ?? 400);
   fileListCache.set(key, { generation, body: result.value });
   return json2(result.value);
 }
@@ -20165,7 +20822,7 @@ function handleGrep(url) {
     max
   });
   if (result.ok !== true)
-    return text(result.error, 400);
+    return text(result.error, result.status ?? 400);
   return json2(result.value);
 }
 function handleRefCommits(url) {
@@ -20174,7 +20831,10 @@ function handleRefCommits(url) {
   const parsedSkip = Number(url.searchParams.get("skip") || "0");
   const max = Number.isFinite(parsedMax) && parsedMax > 0 ? parsedMax : undefined;
   const skip = Number.isFinite(parsedSkip) && parsedSkip > 0 ? parsedSkip : undefined;
-  return json2(refCommitPage(cwd, { query, max, skip }));
+  const result = refCommitPageResult(cwd, { query, max, skip });
+  if (result.error)
+    return text(result.error, result.status ?? 500);
+  return json2({ commits: result.commits, hasMore: result.hasMore });
 }
 function handleLog(url) {
   const ref = url.searchParams.get("ref") || "HEAD";
@@ -20191,23 +20851,13 @@ function handleLog(url) {
     ...path ? { path } : {}
   });
   if (result.error)
-    return text(result.error, 400);
+    return text(result.error, result.status ?? 400);
   const wantsWorktreeHead = path && skip === 0 && (ref === "worktree" || url.searchParams.get("worktree") === "1");
   let commits = result.commits;
   let hasWorktree = false;
   if (wantsWorktreeHead) {
-    const status = runSync([
-      "git",
-      "-c",
-      "core.quotepath=false",
-      "status",
-      "--porcelain=v1",
-      "-z",
-      "--untracked-files=normal",
-      "--",
-      path
-    ], cwd);
-    if (status.code === 0 && status.stdout.length > 0) {
+    const status = statusPorcelainForPath(path, cwd);
+    if (status.ok && status.stdout.length > 0) {
       const parts = status.stdout.split("\x00").filter(Boolean);
       if (parts.length > 0) {
         hasWorktree = true;
@@ -20234,7 +20884,7 @@ function handleLog(url) {
 }
 function blamePathKey(p) {
   try {
-    const st = statSync5(join17(cwd, p));
+    const st = statSync6(join18(cwd, p));
     return `${st.mtimeMs}:${st.size}`;
   } catch {
     return "missing";
@@ -20266,10 +20916,12 @@ function handleFileBlame(url) {
   if (base === "worktree") {
     cacheKey = `worktree|${path}|${blamePathKey(path)}`;
   } else {
-    const resolved = runSync(["git", "rev-parse", "--verify", `${normalized.ref}^{commit}`], cwd);
-    if (resolved.code !== 0)
-      return text("unknown ref", 400);
-    cacheKey = `HEAD|${path}|${resolved.stdout.trim()}`;
+    const resolved = verifyCommit(normalized.ref, cwd);
+    if (resolved.ok === false) {
+      const status = resolved.error === commandNotFoundDetail("git") ? 503 : 400;
+      return text(resolved.error || "unknown ref", status);
+    }
+    cacheKey = `HEAD|${path}|${resolved.sha}`;
   }
   const cached = blameCache.get(cacheKey);
   if (cached) {
@@ -20280,6 +20932,8 @@ function handleFileBlame(url) {
     return json2({ ...cached, base, ref, generation });
   }
   const result = blame(cwd, { path, ref: normalized.ref, base });
+  if (result.error && result.status)
+    return text(result.error, result.status);
   if (!result.error)
     rememberBlame(cacheKey, result);
   return json2({ ...result, base, ref, generation });
@@ -20332,19 +20986,30 @@ function handleFileDiff(url) {
   const cached = fileCache.get(cacheKey);
   let diffText;
   let errText = "";
+  let errStatus;
   if (cacheFresh(cached)) {
     diffText = cached.diffText;
   } else {
     if (isUntracked) {
-      diffText = untrackedFileDiff(extras, path, cwd).stdout || "";
+      const res = untrackedFileDiff(extras, path, cwd);
+      diffText = res.stdout || "";
+      if (res.code !== 0) {
+        errText = res.stderr;
+        errStatus = res.status;
+      }
     } else {
       const res = fileDiffText([...extras, ...args], oldPath ? [oldPath, path] : path, cwd);
       diffText = res.stdout || "";
-      if (res.code !== 0)
+      if (res.code !== 0) {
         errText = res.stderr;
+        errStatus = res.status;
+      }
     }
-    setTimedCacheEntry(fileCache, cacheKey, { diffText });
+    if (!errText)
+      setTimedCacheEntry(fileCache, cacheKey, { diffText });
   }
+  if (errStatus)
+    return text(errText || "diff failed", errStatus);
   const mode = url.searchParams.get("mode") || "full";
   const truncated = mode === "preview" ? truncateToNHunks(diffText, Number(url.searchParams.get("max_hunks")) || PREVIEW_HUNKS_DEFAULT, Number(url.searchParams.get("max_lines")) || PREVIEW_LINES_DEFAULT) : truncateToNHunks(diffText, 1e9);
   const body = {
@@ -20365,7 +21030,7 @@ function handleFileDiff(url) {
 }
 function worktreeLineIndexSignature(full) {
   try {
-    const stat2 = statSync5(full);
+    const stat2 = statSync6(full);
     return `size:${stat2.size}|mtime:${stat2.mtimeMs}|ctime:${stat2.ctimeMs}|ino:${stat2.ino || 0}`;
   } catch {
     return null;
@@ -20381,7 +21046,7 @@ async function getWorktreeLineIndex(full) {
     lineIndexCache.set(full, cached);
     return cached.index;
   }
-  const stat2 = statSync5(full);
+  const stat2 = statSync6(full);
   if (stat2.size > LINE_INDEX_MAX_FILE_BYTES)
     return null;
   const index = await buildLineOffsetIndexFromStream(fileReadableStream(full), stat2.size);
@@ -20526,8 +21191,9 @@ async function handleFileRange(url) {
     };
     return json2(body);
   } else {
-    if (!verifyTreeRef(ref, cwd))
-      return text("invalid ref", 400);
+    const refCheck = verifyTreeRefResult(ref, cwd);
+    if (refCheck.ok !== true)
+      return text(refCheck.error, refCheck.status ?? 400);
     const oid = objectId(ref, path, cwd);
     if (oid.code !== 0 || !oid.oid)
       return text("not in ref", 404);
@@ -20557,8 +21223,9 @@ function handleRawFile(req, url) {
   const ref = url.searchParams.get("ref") || "worktree";
   let body;
   if (ref !== "worktree" && ref !== "") {
-    if (!verifyTreeRef(ref, cwd))
-      return text("invalid ref", 400);
+    const refCheck = verifyTreeRefResult(ref, cwd);
+    if (refCheck.ok !== true)
+      return text(refCheck.error, refCheck.status ?? 400);
     const size = rawFileSize(path, ref);
     if (size == null)
       return text("not in ref", 404);
@@ -20626,7 +21293,7 @@ function rawFileSize(path, ref) {
   if (!full)
     return null;
   try {
-    return statSync5(full).size;
+    return statSync6(full).size;
   } catch {
     return null;
   }
@@ -20651,7 +21318,7 @@ function safeUploadFileName(name) {
   return trimmed;
 }
 function uploadOpenFlags() {
-  return constants2.O_WRONLY | constants2.O_CREAT | constants2.O_EXCL | (constants2.O_NOFOLLOW || 0);
+  return constants3.O_WRONLY | constants3.O_CREAT | constants3.O_EXCL | (constants3.O_NOFOLLOW || 0);
 }
 async function handleUploadFiles(req) {
   if (!uploadEnabled)
@@ -20687,7 +21354,7 @@ async function handleUploadFiles(req) {
   const realDir = safeOpenWorktreePath(dir);
   if (!realDir)
     return text("not found", 404);
-  const stats = statSync5(realDir);
+  const stats = statSync6(realDir);
   if (!stats.isDirectory())
     return text("not a directory", 400);
   const files = form.getAll("files").filter((item) => item instanceof File);
@@ -20711,8 +21378,8 @@ async function handleUploadFiles(req) {
     total += file.size;
     if (total > MAX_UPLOAD_TOTAL_BYTES)
       return text("upload too large", 413);
-    const target = join17(realDir, safeName);
-    if (relative6(realDir, dirname4(target)) !== "")
+    const target = join18(realDir, safeName);
+    if (relative7(realDir, dirname5(target)) !== "")
       return text("invalid filename", 400);
     if (existsSync8(target))
       return text("file exists", 409);
@@ -20833,9 +21500,9 @@ function triggerUpdate(changedPaths) {
   sendSse("update", data);
 }
 function moveMacPathIntoTrash(path) {
-  const trashDir = join17(homedir3(), ".Trash");
+  const trashDir = join18(homedir3(), ".Trash");
   const base = basename3(path) || "code-viewer-trash-item";
-  const target = join17(trashDir, `${base}-${Date.now()}-${process.pid}-${Math.random().toString(36).slice(2, 8)}`);
+  const target = join18(trashDir, `${base}-${Date.now()}-${process.pid}-${Math.random().toString(36).slice(2, 8)}`);
   try {
     mkdirSync4(trashDir, { recursive: true });
     renameSync(path, target);
@@ -20877,11 +21544,11 @@ function restoreTrashPath(originalPath, trashPath) {
     if (!existsSync8(trashPath))
       return { ok: false, error: "trash item not found" };
     try {
-      const trashRoot = join17(homedir3(), ".Trash");
-      const trashRelative = relative6(trashRoot, trashPath);
+      const trashRoot = join18(homedir3(), ".Trash");
+      const trashRelative = relative7(trashRoot, trashPath);
       if (trashRelative === "" || trashRelative.startsWith("..") || trashRelative.startsWith("/") || trashRelative.startsWith("\\"))
         return { ok: false, error: "invalid trash handle" };
-      mkdirSync4(dirname4(original), { recursive: true });
+      mkdirSync4(dirname5(original), { recursive: true });
       renameSync(trashPath, original);
       return { ok: true };
     } catch (error) {
@@ -20936,7 +21603,7 @@ async function handleOpenPath(req) {
   const target = safeOpenWorktreePath(targetPath);
   if (!target)
     return text("not found", 404);
-  const stats = statSync5(target);
+  const stats = statSync6(target);
   if (!stats.isDirectory())
     return text("not a directory", 400);
   openOsPath(target);
@@ -21021,13 +21688,13 @@ async function handleCreateDirectory(req) {
   const parent = safeOpenWorktreePath(dir);
   if (!parent)
     return text("not found", 404);
-  const stats = statSync5(parent);
+  const stats = statSync6(parent);
   if (!stats.isDirectory())
     return text("not a directory", 400);
   const targetPath = dir ? `${dir}/${name}` : name;
   if (!safeRepoPath(targetPath) || isGitInternalPath(targetPath))
     return text("invalid target", 400);
-  const target = join17(parent, name);
+  const target = join18(parent, name);
   if (existsSync8(target))
     return text("already exists", 409);
   try {
@@ -21328,11 +21995,12 @@ function restartWorktreeWatch() {
   }
   worktreeWatch = startScopedWorktreeWatch();
 }
-var WEB_ROOT, VERSION, DEFAULT_ARGS, PREVIEW_HUNKS_DEFAULT = 3, PREVIEW_LINES_DEFAULT = 1200, WATCHED_ASSET_FILES, SIZE_SMALL = 2000, SIZE_MEDIUM = 8000, SIZE_LARGE = 20000, LINE_INDEX_MIN_START = 1e4, LINE_INDEX_MAX_FILE_BYTES, BLOB_LINE_CACHE_MAX_BYTES, MAX_UPLOAD_FILE_BYTES, MAX_UPLOAD_TOTAL_BYTES, MAX_UPLOAD_BODY_BYTES, MAX_UPLOAD_FILES = 50, SAFE_UPLOAD_EXTENSIONS, generation = 1, cwd, cliArgs, listenPort = 0, openAfterStart = false, scopeOmitDirNames, scopeOmitDirCliOverride = null, scopeExcludeNames, scopeWatchLimit, uploadEnabled = true, enc, sseClients, sseKeepalives, fileCache, blameCache, BLAME_CACHE_MAX = 64, metaCache, fileListCache, lineIndexCache, blobLineIndexCache, blobBytesCache, blobLineCacheBytes = 0, safePath, MCP_MAX_BODY_BYTES = 1048576, MCP_INSTRUCTIONS, isCodeViewerInternalPath, watchLimitReached = null, server, worktreeWatch = null, shuttingDown = false;
+var WEB_ROOT, VERSION, DEFAULT_ARGS, PREVIEW_HUNKS_DEFAULT = 3, PREVIEW_LINES_DEFAULT = 1200, WATCHED_ASSET_FILES, SIZE_SMALL = 2000, SIZE_MEDIUM = 8000, SIZE_LARGE = 20000, LINE_INDEX_MIN_START = 1e4, LINE_INDEX_MAX_FILE_BYTES, BLOB_LINE_CACHE_MAX_BYTES, MAX_UPLOAD_FILE_BYTES, MAX_UPLOAD_TOTAL_BYTES, MAX_UPLOAD_BODY_BYTES, MAX_UPLOAD_FILES = 50, SAFE_UPLOAD_EXTENSIONS, generation = 1, cwd, cliArgs, listenPort = 0, openAfterStart = false, commandOverrides, cwdWasExplicit = false, scopeOmitDirNames, scopeOmitDirCliOverride = null, scopeExcludeNames, scopeWatchLimit, uploadEnabled = true, enc, sseClients, sseKeepalives, fileCache, blameCache, BLAME_CACHE_MAX = 64, metaCache, fileListCache, lineIndexCache, blobLineIndexCache, blobBytesCache, blobLineCacheBytes = 0, safePath, MCP_MAX_BODY_BYTES = 1048576, MCP_INSTRUCTIONS, isCodeViewerInternalPath, watchLimitReached = null, server, worktreeWatch = null, shuttingDown = false;
 var init_preview = __esm(async () => {
   init_routes();
   init_annotations();
   init_cache();
+  init_command_resolver();
   init_dev_assets();
   init_doctor();
   init_git();
@@ -21345,8 +22013,8 @@ var init_preview = __esm(async () => {
   init_server_registry();
   init_state_store();
   init_worktree_watcher();
-  WEB_ROOT = join17(ROOT, "web");
-  VERSION = JSON.parse(readFileSync8(join17(ROOT, "package.json"), "utf8")).version;
+  WEB_ROOT = join18(ROOT, "web");
+  VERSION = JSON.parse(readFileSync8(join18(ROOT, "package.json"), "utf8")).version;
   DEFAULT_ARGS = ["HEAD"];
   WATCHED_ASSET_FILES = ["index.html", "style.css", "app.js"];
   LINE_INDEX_MAX_FILE_BYTES = 256 * 1024 * 1024;
@@ -21390,8 +22058,9 @@ var init_preview = __esm(async () => {
     ".scss",
     ".html"
   ]);
-  cwd = repoRoot(process.cwd()) || process.cwd();
+  cwd = process.cwd();
   cliArgs = DEFAULT_ARGS;
+  commandOverrides = [];
   scopeOmitDirNames = DEFAULT_WORKTREE_OMIT_DIR_NAMES;
   scopeExcludeNames = DEFAULT_EXCLUDE_NAMES;
   scopeWatchLimit = DEFAULT_WORKTREE_WATCH_DIRECTORY_LIMIT;
@@ -21474,8 +22143,12 @@ var init_preview = __esm(async () => {
         return handleMcp(req);
       if (url.pathname === "/_annotations")
         return handleAnnotations(req);
-      if (url.pathname === "/_refs")
-        return json2(refs(cwd));
+      if (url.pathname === "/_refs") {
+        const result = refsResult(cwd);
+        if (result.error)
+          return text(result.error, result.status ?? 500);
+        return json2(result.refs);
+      }
       if (url.pathname === "/refresh" && req.method === "POST") {
         if (!sideEffectRequestAllowed(req))
           return text("forbidden", 403);