feat: add 'codescan root' CLI subcommand and MCP tool

Reports the resolved project root from CWD (CLI) or from the MCP
server's project_root (MCP). Bare absolute path on stdout for
scripting; --json or MCP-tool form returns a richer object with
project_root, codescan_dir, db_path, watcher_pid, watcher_status,
walk_up_steps.

Use case: dispatch / worktree co-location scripts that need to ask
"which .codescan/ does codescan resolve to?" instead of duplicating
the walk-up logic in bash. Also handy for human debugging when an
edit lands in an unexpected project.

Factors a new pub fn findRepoRootInfo() helper alongside the existing
findRepoRoot() so both CLI and MCP share the same walk-up
implementation.

Also broadens .gitignore zig-cache/ and zig-out/ patterns to match
anywhere in the tree (was root-only) so a stray src/zig-cache/ from
a sub-directory build doesn't pollute git status.

Closes inbox/2026-05-04-feature-request-codescan-root.md.

Author: Peter Marreck

.gitignore

@@ -1,5 +1,5 @@
-/zig-cache/
-/zig-out/
+zig-cache/
+zig-out/
 /.codescan/
 /.codescan-fixtures/
 /.serena/

src/cli.zig

@@ -36,6 +36,7 @@ pub const CommandTag = enum {
 	status,
 	setup_model,
 	log,
+	root,
 };
 pub const ConfigAction = enum {
 	show,
@@ -412,6 +413,10 @@ pub fn parse(allocator: std.mem.Allocator, args: []const []const u8) !Parsed {
 		parsed.command = .log;
 		help_topic_default = "log";
 		i += 1;
+	} else if (std.mem.eql(u8, cmd, "root")) {
+		parsed.command = .root;
+		help_topic_default = "root";
+		i += 1;
 	} else if (std.mem.eql(u8, cmd, "clean") or std.mem.eql(u8, cmd, "clear")) {
 		parsed.command = .clean;
         help_topic_default = "clean";

src/main.zig

@@ -1342,6 +1342,10 @@ pub fn main() !void {
 			try stdout.writeAll(log_output);
 			try stdout.flush();
 		},
+		.root => {
+			try runRoot(allocator, parsed.output, stdout);
+			try stdout.flush();
+		},
         .setup_model => {
             const dialect: setup_model_text.Dialect = switch (settings.embedding_dialect) {
                 .ollama => .ollama,
@@ -2111,6 +2115,41 @@ fn findRepoRoot(allocator: std.mem.Allocator, start_path: []const u8) !?[]u8 {
 	return findRepoRootUntil(allocator, start_path, null);
 }
 
+pub const RootInfo = struct {
+	project_root: []const u8, // absolute path of the dir containing .codescan/
+	codescan_dir: []const u8, // absolute path of the .codescan/ dir itself
+	walk_up_steps: usize,     // number of dir levels traversed from start_path
+};
+
+/// Walk up from `start_path` looking for the nearest `.codescan/` ancestor.
+/// Caller owns `project_root` and `codescan_dir` (each freed independently).
+pub fn findRepoRootInfo(allocator: std.mem.Allocator, start_path: []const u8) !?RootInfo {
+	const start_abs = try std.fs.cwd().realpathAlloc(allocator, start_path);
+	errdefer allocator.free(start_abs);
+
+	var current = start_abs;
+	var steps: usize = 0;
+	while (true) {
+		if (try hasCodescanDir(current)) {
+			const codescan_dir = try std.fs.path.join(allocator, &.{ current, ".codescan" });
+			return RootInfo{
+				.project_root = current,
+				.codescan_dir = codescan_dir,
+				.walk_up_steps = steps,
+			};
+		}
+		const parent = std.fs.path.dirname(current) orelse break;
+		if (std.mem.eql(u8, parent, current)) break;
+		const next = try allocator.dupe(u8, parent);
+		allocator.free(current);
+		current = next;
+		steps += 1;
+	}
+	allocator.free(current);
+	return null;
+}
+
+
 fn findRepoRootUntil(
 	allocator: std.mem.Allocator,
 	start_path: []const u8,
@@ -5296,6 +5335,67 @@ fn appendJsonBoolFlag(
     if (enabled) try args.append(allocator, flag);
 }
 
+pub fn runRoot(
+	allocator: std.mem.Allocator,
+	format: cli.OutputFormat,
+	writer: *std.Io.Writer,
+) !void {
+	const cwd_path = try std.fs.cwd().realpathAlloc(allocator, ".");
+	defer allocator.free(cwd_path);
+
+	const info_opt = findRepoRootInfo(allocator, cwd_path) catch |err| {
+		if (format == .json) {
+			try writer.print("{{\"error\":\"{s}\"}}\n", .{@errorName(err)});
+		} else {
+			try writer.print("error: {s}\n", .{@errorName(err)});
+		}
+		return err;
+	};
+
+	const info = info_opt orelse {
+		if (format == .json) {
+			try writer.print("{{\"root\":null,\"error\":\"no .codescan/ directory found walking up from {s}\"}}\n", .{cwd_path});
+		} else {
+			try writer.print("error: no .codescan/ directory found walking up from {s}\n", .{cwd_path});
+		}
+		std.process.exit(1);
+	};
+	defer {
+		allocator.free(info.project_root);
+		allocator.free(info.codescan_dir);
+	}
+
+	if (format == .human) {
+		try writer.print("{s}\n", .{info.project_root});
+		return;
+	}
+
+	// JSON output: include codescan_dir, db_path, watcher pid/status, walk_up_steps
+	const db_path = try std.fs.path.join(allocator, &.{ info.codescan_dir, "index.sqlite3" });
+	defer allocator.free(db_path);
+
+	const pid_opt = pidfile.readAndCheckPid(allocator, info.codescan_dir) catch null;
+	const watcher_status: []const u8 = if (pidfile.isWatcherRunning(allocator, info.codescan_dir))
+		"running"
+	else if (pid_opt != null)
+		"stale"
+	else
+		"stopped";
+
+	try writer.writeAll("{");
+	try writer.print("\"project_root\":\"{s}\",", .{info.project_root});
+	try writer.print("\"root\":\"{s}\",", .{info.codescan_dir});
+	try writer.print("\"db_path\":\"{s}\",", .{db_path});
+	if (pid_opt) |pid| {
+		try writer.print("\"watcher_pid\":{d},", .{pid});
+	} else {
+		try writer.writeAll("\"watcher_pid\":null,");
+	}
+	try writer.print("\"watcher_status\":\"{s}\",", .{watcher_status});
+	try writer.print("\"walk_up_steps\":{d}", .{info.walk_up_steps});
+	try writer.writeAll("}\n");
+}
+
 pub fn runStatus(
 	allocator: std.mem.Allocator,
 	db_path: []const u8,

src/mcp.zig

@@ -656,6 +656,46 @@ fn callTool(allocator: std.mem.Allocator, name: []const u8, args: ?std.json.Obje
 		defer allocator.free(log_output);
 
 		try out.writer.writeAll(log_output);
+	} else if (std.mem.eql(u8, name, "root")) {
+		// Resolve from the server's project root rather than CWD — the MCP
+		// server may have been launched from anywhere; settings.root_path
+		// is the authoritative starting point.
+		const info_opt = main.findRepoRootInfo(allocator, settings.root_path) catch |err|
+			return toolError("MCP root: walk-up failed: {}\n", .{err});
+
+		if (info_opt) |info| {
+			defer {
+				allocator.free(info.project_root);
+				allocator.free(info.codescan_dir);
+			}
+			const db_path = std.fs.path.join(allocator, &.{ info.codescan_dir, "index.sqlite3" }) catch
+				return toolError("MCP root: db_path join failed\n", .{});
+			defer allocator.free(db_path);
+
+			const pidfile_mod = @import("pidfile.zig");
+			const pid_opt = pidfile_mod.readAndCheckPid(allocator, info.codescan_dir) catch null;
+			const watcher_status: []const u8 = if (pidfile_mod.isWatcherRunning(allocator, info.codescan_dir))
+				"running"
+			else if (pid_opt != null)
+				"stale"
+			else
+				"stopped";
+
+			try out.writer.writeAll("{");
+			try out.writer.print("\"project_root\":\"{s}\",", .{info.project_root});
+			try out.writer.print("\"root\":\"{s}\",", .{info.codescan_dir});
+			try out.writer.print("\"db_path\":\"{s}\",", .{db_path});
+			if (pid_opt) |pid| {
+				try out.writer.print("\"watcher_pid\":{d},", .{pid});
+			} else {
+				try out.writer.writeAll("\"watcher_pid\":null,");
+			}
+			try out.writer.print("\"watcher_status\":\"{s}\",", .{watcher_status});
+			try out.writer.print("\"walk_up_steps\":{d}", .{info.walk_up_steps});
+			try out.writer.writeAll("}");
+		} else {
+			try out.writer.print("{{\"root\":null,\"error\":\"no .codescan/ directory found walking up from {s}\"}}", .{settings.root_path});
+		}
 	} else {
 		return error.UnknownTool;
 	}
@@ -855,7 +895,8 @@ const tools_list_json =
 	\\{"name":"rename","description":"Rename a symbol across the workspace (via LSP)","inputSchema":{"type":"object","properties":{"file":{"type":"string","description":"File path"},"pattern":{"type":"string","description":"Symbol name path"},"to":{"type":"string","description":"New name"},"dry_run":{"type":"boolean","description":"Preview changes without applying"}},"required":["file","pattern","to"]}},
 	\\{"name":"config","description":"Show current codescan configuration","inputSchema":{"type":"object","properties":{}}},
 		\\{"name":"status","description":"Show index and watcher status","inputSchema":{"type":"object","properties":{}}},
-	\\{"name":"logs","description":"Read recent watcher logs from the OS log (macOS unified log / Linux journald), filtered to codescan and optionally to a project root.","inputSchema":{"type":"object","properties":{"root":{"type":"string","description":"Absolute project root path; filters messages to this project"},"since":{"type":"string","description":"Time window (e.g. '1h', '15m'). Default 1h."},"limit":{"type":"integer","description":"Max lines to return (last N after filter)"},"all":{"type":"boolean","description":"If true, show logs from all codescan projects"}}}}
+	\\{"name":"logs","description":"Read recent watcher logs from the OS log (macOS unified log / Linux journald), filtered to codescan and optionally to a project root.","inputSchema":{"type":"object","properties":{"root":{"type":"string","description":"Absolute project root path; filters messages to this project"},"since":{"type":"string","description":"Time window (e.g. '1h', '15m'). Default 1h."},"limit":{"type":"integer","description":"Max lines to return (last N after filter)"},"all":{"type":"boolean","description":"If true, show logs from all codescan projects"}}}},
+	\\{"name":"root","description":"Report which .codescan/ directory codescan resolves to from the server's project root. Returns absolute path of project root, the .codescan dir, db_path, watcher pid/status, and how many directory levels were walked up.","inputSchema":{"type":"object","properties":{}}}
 	\\]}
 ;