byterover-cli 3.1.0 → 3.2.0

package/dist/server/infra/process/task-router.js

@@ -16,8 +16,10 @@
  */
 import { AgentNotAvailableError, serializeTaskError } from '../../core/domain/errors/task-error.js';
 import { LlmEventNames, TransportLlmEventList, TransportTaskEventNames } from '../../core/domain/transport/schemas.js';
+import { isDescendantOf } from '../../utils/path-utils.js';
 import { transportLog } from '../../utils/process-logger.js';
 import { isValidTaskType } from '../../utils/type-guards.js';
+import { resolveProject } from '../project/resolve-project.js';
 import { broadcastToProjectRoom } from './broadcast-utils.js';
 /**
  * Grace period (in ms) to keep completed tasks in memory for late-arriving events.
@@ -245,11 +247,27 @@ export class TaskRouter {
             broadcastToProjectRoom(this.projectRegistry, this.projectRouter, projectPath, TransportTaskEventNames.ERROR, { error, taskId }, clientId);
             return { taskId };
         }
-        // ── Resolve projectPath & store task synchronously ────────────────────────
-        // Resolve projectPath: explicit field > client's registered projectPath > clientCwd.
-        // Client's registered projectPath is the walked-up project root (where .brv/ lives),
-        // while clientCwd is the raw working directory (may be a subdirectory).
-        const projectPath = data.projectPath ?? this.resolveClientProjectPath?.(clientId) ?? data.clientCwd;
+        // ── Resolve projectPath & worktreeRoot, store task synchronously ─────────
+        let projectPath;
+        let worktreeRoot;
+        try {
+            const taskContext = this.resolveTaskContext(data, clientId);
+            if (taskContext.error) {
+                const error = serializeTaskError(new Error(taskContext.error));
+                this.transport.sendTo(clientId, TransportTaskEventNames.ERROR, { error, taskId });
+                broadcastToProjectRoom(this.projectRegistry, this.projectRouter, taskContext.projectPath, TransportTaskEventNames.ERROR, { error, taskId }, clientId);
+                return { taskId };
+            }
+            projectPath = taskContext.projectPath;
+            worktreeRoot = taskContext.worktreeRoot;
+        }
+        catch (error_) {
+            const error = serializeTaskError(error_ instanceof Error ? error_ : new Error(String(error_)));
+            const fallbackProjectPath = data.projectPath ?? this.resolveClientProjectPath?.(clientId) ?? data.clientCwd;
+            this.transport.sendTo(clientId, TransportTaskEventNames.ERROR, { error, taskId });
+            broadcastToProjectRoom(this.projectRegistry, this.projectRouter, fallbackProjectPath, TransportTaskEventNames.ERROR, { error, taskId }, clientId);
+            return { taskId };
+        }
         transportLog(`Task accepted: ${taskId} (type=${data.type}, client=${clientId})`);
         this.tasks.set(taskId, {
             clientId,
@@ -261,6 +279,7 @@ export class TaskRouter {
             ...(projectPath ? { projectPath } : {}),
             taskId,
             type: data.type,
+            ...(worktreeRoot ? { worktreeRoot } : {}),
         });
         // ── Send task:created synchronously (before any await) ────────────────────
         const createdPayload = {
@@ -294,6 +313,7 @@ export class TaskRouter {
             ...(projectPath ? { projectPath } : {}),
             taskId,
             type: data.type,
+            ...(worktreeRoot ? { worktreeRoot } : {}),
         };
         // eslint-disable-next-line no-void
         void this.agentPool
@@ -467,6 +487,41 @@ export class TaskRouter {
             this.routeLlmEvent(eventName, data);
         });
     }
+    resolveTaskContext(data, clientId) {
+        // When both projectPath and worktreeRoot are explicitly provided,
+        // skip the resolver entirely — a broken link under clientCwd must not
+        // reject an otherwise valid explicit payload.
+        if (data.projectPath && data.worktreeRoot) {
+            if (!isDescendantOf(data.worktreeRoot, data.projectPath)) {
+                return {
+                    error: `worktreeRoot "${data.worktreeRoot}" must be equal to or within projectPath "${data.projectPath}".`,
+                    projectPath: data.projectPath,
+                };
+            }
+            return { projectPath: data.projectPath, worktreeRoot: data.worktreeRoot };
+        }
+        // Resolve from clientCwd (fresh, workspace-link-aware) when needed.
+        let resolvedProjectPath;
+        let resolvedWorkspaceRoot;
+        if (data.clientCwd) {
+            const resolution = resolveProject({ cwd: data.clientCwd });
+            resolvedProjectPath = resolution?.projectRoot;
+            resolvedWorkspaceRoot = resolution?.worktreeRoot;
+        }
+        // Fallback order: explicit > fresh cwd resolution > stale registration > raw clientCwd.
+        // Fresh resolution is preferred over registered path because the registered path
+        // may be stale (e.g. in-flight reassociation after worktree add/remove).
+        const registeredProjectPath = this.resolveClientProjectPath?.(clientId);
+        const projectPath = data.projectPath ?? resolvedProjectPath ?? registeredProjectPath ?? data.clientCwd;
+        const worktreeRoot = data.worktreeRoot ?? resolvedWorkspaceRoot ?? projectPath;
+        if (projectPath && worktreeRoot && !isDescendantOf(worktreeRoot, projectPath)) {
+            return {
+                error: `worktreeRoot "${worktreeRoot}" must be equal to or within projectPath "${projectPath}".`,
+                projectPath,
+            };
+        }
+        return { projectPath, worktreeRoot };
+    }
     /**
      * Generic handler for routing LLM events from Agent to clients.
      * Checks both active and recently completed tasks (within grace period).

package/dist/server/infra/project/resolve-project.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Result of canonical project resolution.
+ */
+export interface ProjectResolution {
+    /** Directory containing .brv/config.json */
+    projectRoot: string;
+    /** How the project root was discovered */
+    source: 'direct' | 'flag' | 'linked';
+    /** Worktree root (equals projectRoot when direct, equals cwd when linked) */
+    worktreeRoot: string;
+}
+/**
+ * Error thrown when a .brv pointer file points to a project root that no longer has .brv/.
+ */
+export declare class BrokenWorktreePointerError extends Error {
+    readonly pointerDir: string;
+    readonly targetProjectRoot: string;
+    constructor(pointerDir: string, targetProjectRoot: string);
+}
+/**
+ * Error thrown when a .brv file (pointer) exists but contains malformed/invalid content.
+ */
+export declare class MalformedWorktreePointerError extends Error {
+    readonly pointerDir: string;
+    readonly reason: string;
+    constructor(pointerDir: string, reason: string);
+}
+export declare function hasBrvConfig(dir: string): boolean;
+/**
+ * Checks if a directory is a git root (.git directory or .git file for worktrees/submodules).
+ */
+export declare function isGitRoot(dir: string): boolean;
+/**
+ * Checks if .brv in the given directory is a FILE (pointer), not a directory.
+ */
+export declare function isWorktreePointer(dir: string): boolean;
+/**
+ * Reads and validates a .brv pointer file.
+ * @throws MalformedWorktreePointerError if the file has invalid content
+ */
+export declare function readWorktreePointer(dir: string): string;
+export interface ResolveProjectOptions {
+    /** Override cwd (defaults to process.cwd()) */
+    cwd?: string;
+    /** Explicit --project-root flag value */
+    projectRootFlag?: string;
+}
+/**
+ * Canonical project resolver — single source of truth for discovering
+ * which .brv/ project a given working directory belongs to.
+ *
+ * Git-style resolution: walks up from cwd to find the nearest `.brv`
+ * (file or directory), just like git walks up to find `.git`.
+ *
+ * 1. --project-root flag
+ * 2. Walk up from cwd looking for .brv:
+ *    a. .brv is a directory with config.json → source: 'direct'
+ *    b. .brv is a file (pointer) → follow to parent → source: 'linked'
+ * 3. null (no .brv found at cwd or any ancestor)
+ *
+ * The walk-up stops at the **first** .brv found — it does NOT skip past
+ * a .brv to find a "better" one higher up. This prevents accidental
+ * inheritance from stale .brv/ directories in ancestor directories.
+ *
+ * @throws BrokenWorktreePointerError if .brv file points to a missing project
+ * @throws MalformedWorktreePointerError if .brv file has invalid content
+ */
+export declare function resolveProject(options?: ResolveProjectOptions): null | ProjectResolution;
+export interface AddWorktreeResult {
+    backedUp?: boolean;
+    message: string;
+    success: boolean;
+}
+/**
+ * Register a worktree: writes .brv pointer file in the target directory
+ * and creates a registry entry in the parent's .brv/worktrees/.
+ *
+ * If the target already has a .brv/ directory (e.g., auto-init'd), it is
+ * backed up to .brv-backup/ and replaced with a pointer file.
+ */
+export declare function addWorktree(projectRoot: string, worktreePath: string, options?: {
+    force?: boolean;
+}): AddWorktreeResult;
+export interface RemoveWorktreeResult {
+    message: string;
+    success: boolean;
+}
+/**
+ * Remove a worktree: deletes the .brv pointer file and cleans up the registry entry.
+ * If a .brv-backup/ exists, restores it.
+ */
+export declare function removeWorktree(worktreePath: string): RemoveWorktreeResult;
+export interface WorktreeInfo {
+    name: string;
+    worktreePath: string;
+}
+/**
+ * List all registered worktrees for a project by scanning .brv/worktrees/ entries.
+ */
+export declare function listWorktrees(projectRoot: string): WorktreeInfo[];
+/**
+ * Walk up from startDir looking for the nearest directory with .brv/ DIRECTORY
+ * (not a .brv file). Used only by `brv worktree add` auto-detect mode.
+ * NOT used by the resolver.
+ */
+export declare function findParentProject(startDir: string): string | undefined;

package/dist/server/infra/project/resolve-project.js

@@ -0,0 +1,473 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { BRV_DIR, PROJECT_CONFIG_FILE, WORKTREE_LINK_METADATA, WORKTREES_DIR } from '../../constants.js';
+import { WorktreeLinkMetadataSchema, WorktreePointerSchema } from '../../core/domain/project/worktrees-schema.js';
+import { resolvePath } from '../../utils/path-utils.js';
+// ============================================================================
+// Errors
+// ============================================================================
+/**
+ * Error thrown when a .brv pointer file points to a project root that no longer has .brv/.
+ */
+export class BrokenWorktreePointerError extends Error {
+    pointerDir;
+    targetProjectRoot;
+    constructor(pointerDir, targetProjectRoot) {
+        super(`Worktree pointer broken: "${targetProjectRoot}" no longer has ${BRV_DIR}/${PROJECT_CONFIG_FILE}. ` +
+            `Run 'brv worktree remove' to remove the pointer.`);
+        this.pointerDir = pointerDir;
+        this.targetProjectRoot = targetProjectRoot;
+        this.name = 'BrokenWorktreePointerError';
+    }
+}
+/**
+ * Error thrown when a .brv file (pointer) exists but contains malformed/invalid content.
+ */
+export class MalformedWorktreePointerError extends Error {
+    pointerDir;
+    reason;
+    constructor(pointerDir, reason) {
+        super(`Worktree pointer in "${pointerDir}" is malformed: ${reason}. ` +
+            `Fix the .brv file or run 'brv worktree remove' to remove it.`);
+        this.pointerDir = pointerDir;
+        this.reason = reason;
+        this.name = 'MalformedWorktreePointerError';
+    }
+}
+// ============================================================================
+// Core helpers
+// ============================================================================
+export function hasBrvConfig(dir) {
+    return existsSync(join(dir, BRV_DIR, PROJECT_CONFIG_FILE));
+}
+/**
+ * Checks if a directory is a git root (.git directory or .git file for worktrees/submodules).
+ */
+export function isGitRoot(dir) {
+    const gitPath = join(dir, '.git');
+    try {
+        const stat = lstatSync(gitPath);
+        return stat.isDirectory() || stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Checks if .brv in the given directory is a FILE (pointer), not a directory.
+ */
+export function isWorktreePointer(dir) {
+    const brvPath = join(dir, BRV_DIR);
+    try {
+        return lstatSync(brvPath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Reads and validates a .brv pointer file.
+ * @throws MalformedWorktreePointerError if the file has invalid content
+ */
+export function readWorktreePointer(dir) {
+    const brvPath = join(dir, BRV_DIR);
+    let raw;
+    try {
+        raw = readFileSync(brvPath, 'utf8');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new MalformedWorktreePointerError(dir, `cannot read .brv file: ${message}`);
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        throw new MalformedWorktreePointerError(dir, 'invalid JSON');
+    }
+    const result = WorktreePointerSchema.safeParse(json);
+    if (!result.success) {
+        throw new MalformedWorktreePointerError(dir, 'missing or invalid "projectRoot" field');
+    }
+    return result.data.projectRoot;
+}
+/**
+ * Canonical project resolver — single source of truth for discovering
+ * which .brv/ project a given working directory belongs to.
+ *
+ * Git-style resolution: walks up from cwd to find the nearest `.brv`
+ * (file or directory), just like git walks up to find `.git`.
+ *
+ * 1. --project-root flag
+ * 2. Walk up from cwd looking for .brv:
+ *    a. .brv is a directory with config.json → source: 'direct'
+ *    b. .brv is a file (pointer) → follow to parent → source: 'linked'
+ * 3. null (no .brv found at cwd or any ancestor)
+ *
+ * The walk-up stops at the **first** .brv found — it does NOT skip past
+ * a .brv to find a "better" one higher up. This prevents accidental
+ * inheritance from stale .brv/ directories in ancestor directories.
+ *
+ * @throws BrokenWorktreePointerError if .brv file points to a missing project
+ * @throws MalformedWorktreePointerError if .brv file has invalid content
+ */
+export function resolveProject(options) {
+    const cwd = options?.cwd ?? process.cwd();
+    // Step 1: Explicit --project-root flag — fail loudly if invalid
+    if (options?.projectRootFlag) {
+        const flagRoot = resolve(options.projectRootFlag);
+        if (!hasBrvConfig(flagRoot)) {
+            throw new Error(`--project-root "${flagRoot}" is not a ByteRover project (no ${BRV_DIR}/${PROJECT_CONFIG_FILE}).`);
+        }
+        const canonical = resolvePath(flagRoot);
+        return {
+            projectRoot: canonical,
+            source: 'flag',
+            worktreeRoot: canonical,
+        };
+    }
+    let startDir;
+    try {
+        startDir = resolvePath(cwd);
+    }
+    catch {
+        return null;
+    }
+    // Step 2: Walk up from cwd looking for .brv (file or directory)
+    let current = startDir;
+    const root = resolve('/');
+    while (current !== root) {
+        const result = resolveAtDir(current);
+        if (result !== undefined) {
+            return result;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    // Also check root
+    if (current !== startDir) {
+        const result = resolveAtDir(current);
+        if (result !== undefined) {
+            return result;
+        }
+    }
+    // Step 3: No .brv found anywhere
+    return null;
+}
+/**
+ * Check a single directory for .brv and resolve it.
+ * Returns ProjectResolution, null (invalid .brv), or undefined (no .brv here, keep walking).
+ */
+function resolveAtDir(dir) {
+    const brvPath = join(dir, BRV_DIR);
+    let stat;
+    try {
+        stat = lstatSync(brvPath);
+    }
+    catch {
+        // .brv doesn't exist here — keep walking
+        return undefined;
+    }
+    // .brv is a directory → real project
+    if (stat.isDirectory()) {
+        if (existsSync(join(brvPath, PROJECT_CONFIG_FILE))) {
+            return {
+                projectRoot: dir,
+                source: 'direct',
+                worktreeRoot: dir,
+            };
+        }
+        // .brv/ exists but no config.json — stop here (don't walk past it)
+        return null;
+    }
+    // .brv is a file → pointer to parent project
+    if (stat.isFile()) {
+        const targetRoot = readWorktreePointer(dir);
+        let canonicalTarget;
+        try {
+            canonicalTarget = resolvePath(targetRoot);
+        }
+        catch {
+            throw new BrokenWorktreePointerError(dir, targetRoot);
+        }
+        if (!hasBrvConfig(canonicalTarget)) {
+            throw new BrokenWorktreePointerError(dir, canonicalTarget);
+        }
+        return {
+            projectRoot: canonicalTarget,
+            source: 'linked',
+            worktreeRoot: dir,
+        };
+    }
+    // .brv is something else — stop here
+    return null;
+}
+// ============================================================================
+// Worktree CRUD operations
+// ============================================================================
+/**
+ * Sanitize a path into a safe directory name for the worktrees registry.
+ * Replaces path separators and special chars with dashes, then appends
+ * a numeric suffix if the name already exists in .brv/worktrees/.
+ */
+function sanitizeWorktreeName(worktreePath, projectRoot) {
+    // Try to use relative path for readability, fall back to basename
+    const name = worktreePath.startsWith(projectRoot + sep) || worktreePath.startsWith(projectRoot + '/') ? worktreePath.slice(projectRoot.length + 1) : basename(worktreePath);
+    const baseName = name.replaceAll(/[/\\]/g, '-').replaceAll(/[^a-zA-Z0-9._-]/g, '-');
+    // Check for collisions in existing registry entries
+    const worktreesDir = join(projectRoot, BRV_DIR, WORKTREES_DIR);
+    if (!existsSync(worktreesDir)) {
+        return baseName;
+    }
+    const existing = new Set();
+    try {
+        for (const entry of readdirSync(worktreesDir)) {
+            existing.add(entry);
+        }
+    }
+    catch {
+        return baseName;
+    }
+    if (!existing.has(baseName)) {
+        return baseName;
+    }
+    let counter = 2;
+    while (existing.has(`${baseName}-${counter}`)) {
+        counter++;
+    }
+    return `${baseName}-${counter}`;
+}
+/**
+ * Register a worktree: writes .brv pointer file in the target directory
+ * and creates a registry entry in the parent's .brv/worktrees/.
+ *
+ * If the target already has a .brv/ directory (e.g., auto-init'd), it is
+ * backed up to .brv-backup/ and replaced with a pointer file.
+ */
+export function addWorktree(projectRoot, worktreePath, options) {
+    // Validate parent has .brv/config.json
+    if (!hasBrvConfig(projectRoot)) {
+        return { message: `"${projectRoot}" is not a ByteRover project (no .brv/config.json).`, success: false };
+    }
+    // Validate target directory exists
+    if (!existsSync(worktreePath)) {
+        return { message: `Target directory does not exist: ${worktreePath}`, success: false };
+    }
+    // Cannot add self
+    if (worktreePath === projectRoot) {
+        return { message: 'Cannot add the project root as its own worktree.', success: false };
+    }
+    const targetBrvPath = join(worktreePath, BRV_DIR);
+    let backedUp = false;
+    try {
+        const stat = lstatSync(targetBrvPath);
+        if (stat.isFile()) {
+            // Already a pointer — check if it points to the same parent
+            try {
+                const existingTarget = readWorktreePointer(worktreePath);
+                const canonicalExisting = resolvePath(existingTarget);
+                const canonicalProject = resolvePath(projectRoot);
+                if (canonicalExisting === canonicalProject) {
+                    return { message: `Already registered as worktree of "${projectRoot}".`, success: true };
+                }
+                return {
+                    message: `"${worktreePath}" is already a worktree of "${canonicalExisting}". Remove it first with 'brv worktree remove'.`,
+                    success: false,
+                };
+            }
+            catch {
+                // Malformed pointer — overwrite below
+            }
+        }
+        if (stat.isDirectory()) {
+            // Existing .brv/ directory — back up and replace
+            if (!options?.force) {
+                return {
+                    message: `"${worktreePath}" has its own .brv/ project. Use --force to replace it with a worktree pointer. ` +
+                        'The existing .brv/ will be moved to .brv-backup/.',
+                    success: false,
+                };
+            }
+            const backupPath = join(worktreePath, '.brv-backup');
+            if (existsSync(backupPath)) {
+                rmSync(backupPath, { force: true, recursive: true });
+            }
+            renameSync(targetBrvPath, backupPath);
+            backedUp = true;
+        }
+    }
+    catch {
+        // .brv doesn't exist — proceed
+    }
+    // Write .brv pointer file
+    const pointerContent = JSON.stringify({ projectRoot: resolvePath(projectRoot) }, null, 2) + '\n';
+    writeFileSync(targetBrvPath, pointerContent, 'utf8');
+    // Create registry entry in parent
+    const name = sanitizeWorktreeName(worktreePath, projectRoot);
+    const worktreeDir = join(projectRoot, BRV_DIR, WORKTREES_DIR, name);
+    mkdirSync(worktreeDir, { recursive: true });
+    const metadata = {
+        addedAt: new Date().toISOString(),
+        worktreePath: resolvePath(worktreePath),
+    };
+    writeFileSync(join(worktreeDir, WORKTREE_LINK_METADATA), JSON.stringify(metadata, null, 2) + '\n', 'utf8');
+    const msg = backedUp
+        ? `Added worktree "${worktreePath}" (existing .brv/ backed up to .brv-backup/).`
+        : `Added worktree "${worktreePath}".`;
+    return { backedUp, message: msg, success: true };
+}
+/**
+ * Remove a worktree: deletes the .brv pointer file and cleans up the registry entry.
+ * If a .brv-backup/ exists, restores it.
+ */
+export function removeWorktree(worktreePath) {
+    const brvPath = join(worktreePath, BRV_DIR);
+    // Verify .brv is a pointer file
+    try {
+        const stat = lstatSync(brvPath);
+        if (!stat.isFile()) {
+            return { message: `"${worktreePath}" is not a worktree (has .brv/ directory, not pointer file).`, success: false };
+        }
+    }
+    catch {
+        return { message: `No .brv found in "${worktreePath}".`, success: false };
+    }
+    // Read pointer to find parent
+    let projectRoot;
+    try {
+        projectRoot = readWorktreePointer(worktreePath);
+        projectRoot = resolvePath(projectRoot);
+    }
+    catch {
+        // Can't read pointer — just delete the file
+        unlinkSync(brvPath);
+        return { message: `Removed worktree pointer (parent project unknown).`, success: true };
+    }
+    // Delete pointer file
+    unlinkSync(brvPath);
+    // Restore backup if exists
+    const backupPath = join(worktreePath, '.brv-backup');
+    if (existsSync(backupPath)) {
+        renameSync(backupPath, brvPath);
+    }
+    // Clean up registry entry in parent
+    const worktreesDir = join(projectRoot, BRV_DIR, WORKTREES_DIR);
+    if (existsSync(worktreesDir)) {
+        try {
+            const entries = readdirSync(worktreesDir, { withFileTypes: true });
+            const canonicalWorktree = resolvePath(worktreePath);
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                const metaPath = join(worktreesDir, entry.name, WORKTREE_LINK_METADATA);
+                if (!existsSync(metaPath))
+                    continue;
+                try {
+                    const meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+                    const parsed = WorktreeLinkMetadataSchema.safeParse(meta);
+                    if (parsed.success && resolvePath(parsed.data.worktreePath) === canonicalWorktree) {
+                        rmSync(join(worktreesDir, entry.name), { force: true, recursive: true });
+                        break;
+                    }
+                }
+                catch {
+                    // Malformed metadata — skip
+                }
+            }
+        }
+        catch {
+            // Registry cleanup is best-effort
+        }
+    }
+    return { message: `Removed worktree "${worktreePath}".`, success: true };
+}
+/**
+ * List all registered worktrees for a project by scanning .brv/worktrees/ entries.
+ */
+export function listWorktrees(projectRoot) {
+    const worktreesDir = join(projectRoot, BRV_DIR, WORKTREES_DIR);
+    if (!existsSync(worktreesDir)) {
+        return [];
+    }
+    const result = [];
+    try {
+        const entries = readdirSync(worktreesDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const metaPath = join(worktreesDir, entry.name, WORKTREE_LINK_METADATA);
+            if (!existsSync(metaPath))
+                continue;
+            try {
+                const meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+                const parsed = WorktreeLinkMetadataSchema.safeParse(meta);
+                if (parsed.success) {
+                    result.push({
+                        name: entry.name,
+                        worktreePath: parsed.data.worktreePath,
+                    });
+                }
+            }
+            catch {
+                // Skip malformed entries
+            }
+        }
+    }
+    catch {
+        // Directory unreadable
+    }
+    return result;
+}
+/**
+ * Walk up from startDir looking for the nearest directory with .brv/ DIRECTORY
+ * (not a .brv file). Used only by `brv worktree add` auto-detect mode.
+ * NOT used by the resolver.
+ */
+export function findParentProject(startDir) {
+    let current;
+    try {
+        current = resolvePath(startDir);
+    }
+    catch {
+        return undefined;
+    }
+    // Skip cwd itself — we're looking for a PARENT
+    current = dirname(current);
+    const root = resolve('/');
+    while (current !== root) {
+        const brvPath = join(current, BRV_DIR);
+        try {
+            const stat = lstatSync(brvPath);
+            if (stat.isDirectory() && existsSync(join(brvPath, PROJECT_CONFIG_FILE))) {
+                return current;
+            }
+        }
+        catch {
+            // .brv doesn't exist here
+        }
+        if (isGitRoot(current)) {
+            break;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    // Check the boundary directory itself
+    if (current !== startDir) {
+        const brvPath = join(current, BRV_DIR);
+        try {
+            const stat = lstatSync(brvPath);
+            if (stat.isDirectory() && existsSync(join(brvPath, PROJECT_CONFIG_FILE))) {
+                return current;
+            }
+        }
+        catch {
+            // Not found
+        }
+    }
+    return undefined;
+}

package/dist/server/infra/transport/handlers/index.d.ts

@@ -24,9 +24,13 @@ export { ResetHandler } from './reset-handler.js';
 export type { ResetHandlerDeps } from './reset-handler.js';
 export { ReviewHandler } from './review-handler.js';
 export type { ReviewHandlerDeps } from './review-handler.js';
+export { SourceHandler } from './source-handler.js';
+export type { SourceHandlerDeps } from './source-handler.js';
 export { SpaceHandler } from './space-handler.js';
 export type { SpaceHandlerDeps } from './space-handler.js';
 export { StatusHandler } from './status-handler.js';
 export type { StatusHandlerDeps } from './status-handler.js';
 export { VcHandler } from './vc-handler.js';
 export type { IVcHandlerDeps } from './vc-handler.js';
+export { WorktreeHandler } from './worktree-handler.js';
+export type { WorktreeHandlerDeps } from './worktree-handler.js';