byterover-cli 1.7.2 → 2.0.0

package/dist/server/infra/context-tree/file-context-tree-merger.js

@@ -0,0 +1,261 @@
+import { copyFile, mkdir, opendir, readFile, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
+import { dirname, extname, join } from 'node:path';
+import { BRV_DIR, CONTEXT_TREE_BACKUP_DIR, CONTEXT_TREE_CONFLICT_DIR, CONTEXT_TREE_DIR } from '../../constants.js';
+import { computeContentHash } from './hash-utils.js';
+import { toUnixPath } from './path-utils.js';
+/**
+ * File-based implementation of IContextTreeMerger.
+ *
+ * Merge decision per file (remote hash compared against last snapshot hash):
+ *   - Remote unchanged  → skip; local version wins regardless of local state.
+ *   - Remote changed, local clean, preserveLocalFiles=false → overwrite with remote (regular pull).
+ *   - Remote changed, local clean, preserveLocalFiles=true  → conflict (first-time connect; no
+ *     shared history so the local file is not treated as "old").
+ *   - Remote changed, local also changed                    → conflict.
+ *   Conflict handling: local copy saved to .brv/context-tree-conflicts/ and renamed _N.md;
+ *   remote content written to the original path.
+ *
+ * Clean local files absent from remote are deleted (preserveLocalFiles=false) or preserved
+ * (preserveLocalFiles=true). Locally-deleted files are re-created if remote has a newer version.
+ *
+ * A full backup of the context tree is taken before each merge and used for automatic rollback
+ * on failure. The backup is deleted after a successful merge.
+ */
+export class FileContextTreeMerger {
+    static MAX_RENAME_ATTEMPTS = 100;
+    snapshotService;
+    constructor(deps) {
+        this.snapshotService = deps.snapshotService;
+    }
+    static isErrnoException(e) {
+        return e instanceof Error && 'code' in e;
+    }
+    async merge(params) {
+        const { directory, files, localChanges, preserveLocalFiles = false } = params;
+        const contextTreeDir = join(directory, BRV_DIR, CONTEXT_TREE_DIR);
+        const backupDir = join(directory, BRV_DIR, CONTEXT_TREE_BACKUP_DIR);
+        const conflictDir = join(directory, BRV_DIR, CONTEXT_TREE_CONFLICT_DIR);
+        // Capture pre-merge disk state and saved snapshot state for comparison
+        const localState = await this.snapshotService.getCurrentState(directory);
+        const snapshotState = await this.snapshotService.getSnapshotState(directory);
+        // Only added/modified files can conflict — deleted files are absent from disk so they
+        // cannot be read during conflict handling. Locally-deleted + remote-changed falls through
+        // to the "file not on disk" branch in runMerge(), where remote wins by re-creating the file.
+        const locallyChangedPaths = new Set([...localChanges.added, ...localChanges.modified]);
+        const remoteFilesMap = this.buildRemoteFilesMap(files);
+        // Clear any leftover backup or conflict folder from a previous merge.
+        await rm(backupDir, { force: true, recursive: true });
+        await rm(conflictDir, { force: true, recursive: true });
+        // Backup local context tree as a safety net for rollback on failure.
+        try {
+            await this.copyDir(contextTreeDir, backupDir);
+        }
+        catch (error) {
+            if (!FileContextTreeMerger.isErrnoException(error) || error.code !== 'ENOENT')
+                throw error;
+            // Context tree dir does not exist — nothing to back up, continue
+        }
+        try {
+            const result = await this.runMerge({
+                conflictDir,
+                contextTreeDir,
+                locallyChangedPaths,
+                localState,
+                preserveLocalFiles,
+                remoteFilesMap,
+                snapshotState,
+            });
+            // Save snapshot atomically before deleting backup.
+            // If this fails, the catch block will restore the context tree from the backup.
+            await this.snapshotService.saveSnapshotFromState(result.remoteFileStates, directory);
+            // Snapshot saved — backup is no longer needed.
+            await rm(backupDir, { force: true, recursive: true });
+            const mergeResult = {
+                added: result.added,
+                conflicted: result.conflicted,
+                deleted: result.deleted,
+                edited: result.edited,
+                restoredFromRemote: result.restoredFromRemote,
+            };
+            return mergeResult;
+        }
+        catch (error) {
+            // Failure: automatically restore context tree from backup.
+            await rm(contextTreeDir, { force: true, recursive: true });
+            try {
+                await rename(backupDir, contextTreeDir);
+            }
+            catch {
+                // Backup does not exist (context tree was empty before merge) — context tree is cleanly absent.
+            }
+            // Remove any partial conflict directory created before the failure.
+            await rm(conflictDir, { force: true, recursive: true }).catch(() => { });
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Merge failed: ${message}. Context tree has been restored to its original state.`);
+        }
+    }
+    /**
+     * Builds a map of remote files with normalized paths and decoded content.
+     */
+    buildRemoteFilesMap(files) {
+        const result = new Map();
+        for (const file of files) {
+            const normalPath = toUnixPath(file.path).replace(/^\/+/, '');
+            result.set(normalPath, { decodedContent: file.decodeContent() });
+        }
+        return result;
+    }
+    /**
+     * Recursively copies a directory tree from src to dest.
+     */
+    async copyDir(src, dest) {
+        await mkdir(dest, { recursive: true });
+        const dir = await opendir(src);
+        for await (const entry of dir) {
+            const srcPath = join(src, entry.name);
+            const destPath = join(dest, entry.name);
+            await (entry.isDirectory() ? this.copyDir(srcPath, destPath) : copyFile(srcPath, destPath));
+        }
+    }
+    /**
+     * Finds the first available filename by inserting _N before the extension.
+     * e.g. "path/to/file.md" → "path/to/file_1.md", "path/to/file_2.md", …
+     */
+    async findAvailableName(contextTreeDir, relativePath) {
+        const ext = extname(relativePath); // '.md'
+        const withoutExt = relativePath.slice(0, -ext.length); // 'path/to/file'
+        for (let n = 1; n <= FileContextTreeMerger.MAX_RENAME_ATTEMPTS; n++) {
+            const candidate = `${withoutExt}_${n}${ext}`;
+            const fullPath = join(contextTreeDir, candidate);
+            try {
+                // eslint-disable-next-line no-await-in-loop
+                await stat(fullPath);
+                // File exists — try next number
+            }
+            catch {
+                return candidate;
+            }
+        }
+        throw new Error(`Cannot find available name for ${relativePath} after ${FileContextTreeMerger.MAX_RENAME_ATTEMPTS} attempts`);
+    }
+    async runMerge(params) {
+        const { conflictDir, contextTreeDir, locallyChangedPaths, localState, preserveLocalFiles, remoteFilesMap, snapshotState, } = params;
+        const added = [];
+        const edited = [];
+        const deleted = [];
+        const conflicted = [];
+        const restoredFromRemote = [];
+        const remoteFileStates = new Map();
+        /* eslint-disable no-await-in-loop */
+        for (const [normalPath, file] of remoteFilesMap) {
+            const targetPath = join(contextTreeDir, normalPath);
+            const remoteHash = computeContentHash(file.decodedContent);
+            const snapshotHash = snapshotState.get(normalPath)?.hash;
+            remoteFileStates.set(normalPath, {
+                hash: remoteHash,
+                size: Buffer.byteLength(file.decodedContent, 'utf8'),
+            });
+            if (remoteHash === snapshotHash) {
+                // Remote has NOT changed this file — local wins, skip regardless of local state
+                continue;
+            }
+            // Remote has changed this file (or it is new to remote).
+            if (locallyChangedPaths.has(normalPath)) {
+                // Both sides changed — check if content is actually different before treating as conflict.
+                const localContent = await readFile(targetPath, 'utf8');
+                if (localContent === file.decodedContent) {
+                    // Both sides converged on the same content — no real conflict, treat as edited.
+                    edited.push(normalPath);
+                }
+                else {
+                    // True conflict: preserve original local in conflict dir, rename local to _N.md,
+                    // write remote to original path.
+                    const newRelPath = await this.writeConflict({
+                        conflictDir,
+                        contextTreeDir,
+                        localContent,
+                        normalPath,
+                        remoteContent: file.decodedContent,
+                        targetPath,
+                    });
+                    added.push(newRelPath);
+                    conflicted.push(normalPath);
+                }
+            }
+            else if (localState.has(normalPath)) {
+                if (preserveLocalFiles) {
+                    // First-time connect: no shared history — treat tracked+clean file as a conflict.
+                    // Convergence cannot occur here: local is clean (equals snapshot) and remote hash ≠
+                    // snapshot hash, so the contents are guaranteed to differ.
+                    const localContent = await readFile(targetPath, 'utf8');
+                    const newRelPath = await this.writeConflict({
+                        conflictDir,
+                        contextTreeDir,
+                        localContent,
+                        normalPath,
+                        remoteContent: file.decodedContent,
+                        targetPath,
+                    });
+                    added.push(newRelPath);
+                    conflicted.push(normalPath);
+                }
+                else {
+                    // Regular pull: file exists locally and is clean — overwrite with remote
+                    await writeFile(targetPath, file.decodedContent, 'utf8');
+                    edited.push(normalPath);
+                }
+            }
+            else {
+                // File not on disk — either new from remote or locally deleted with remote having newer version.
+                await mkdir(dirname(targetPath), { recursive: true });
+                await writeFile(targetPath, file.decodedContent, 'utf8');
+                if (snapshotState.has(normalPath)) {
+                    // File was in the last snapshot but is absent from disk — user deleted it.
+                    // Remote has a newer version so it is restored. Track this so the caller can notify the user.
+                    restoredFromRemote.push(normalPath);
+                }
+                added.push(normalPath);
+            }
+        }
+        // Apply remote deletions: if a file no longer exists in remote, remote deleted it — sync
+        // that deletion locally. Skip files with local changes so the user's work is not lost.
+        //
+        // Skip entirely when preserveLocalFiles=true (first-time space connect): the local context
+        // tree has no shared history with the target space, so "absent from remote" means
+        // "remote has never seen it", not "remote deleted it".
+        if (!preserveLocalFiles) {
+            for (const localPath of localState.keys()) {
+                const isLocallyChanged = locallyChangedPaths.has(localPath);
+                const isInRemote = remoteFilesMap.has(localPath);
+                if (!isLocallyChanged && !isInRemote) {
+                    await unlink(join(contextTreeDir, localPath));
+                    deleted.push(localPath);
+                }
+            }
+        }
+        /* eslint-enable no-await-in-loop */
+        return { added, conflicted, deleted, edited, remoteFileStates, restoredFromRemote };
+    }
+    /**
+     * Handles a true conflict: saves the local content to the conflict dir and as a _N.md
+     * rename, then writes remote content to the original path.
+     *
+     * @returns The _N.md relative path that the local content was saved to.
+     */
+    async writeConflict(params) {
+        const { conflictDir, contextTreeDir, localContent, normalPath, remoteContent, targetPath } = params;
+        // Copy original to conflict dir for review
+        const conflictTargetPath = join(conflictDir, normalPath);
+        await mkdir(dirname(conflictTargetPath), { recursive: true });
+        await writeFile(conflictTargetPath, localContent, 'utf8');
+        // Save local version at _N.md
+        const newRelPath = await this.findAvailableName(contextTreeDir, normalPath);
+        const newTargetPath = join(contextTreeDir, newRelPath);
+        await mkdir(dirname(newTargetPath), { recursive: true });
+        await writeFile(newTargetPath, localContent, 'utf8');
+        // Write remote to original path
+        await mkdir(dirname(targetPath), { recursive: true });
+        await writeFile(targetPath, remoteContent, 'utf8');
+        return newRelPath;
+    }
+}

package/dist/server/infra/context-tree/file-context-tree-service.d.ts

@@ -9,6 +9,7 @@ export type ContextTreeServiceConfig = {
 export declare class FileContextTreeService implements IContextTreeService {
     private readonly config;
     constructor(config?: ContextTreeServiceConfig);
+    delete(directory?: string): Promise<void>;
     exists(directory?: string): Promise<boolean>;
     initialize(directory?: string): Promise<string>;
 }

package/dist/server/infra/context-tree/file-context-tree-service.js

@@ -1,4 +1,4 @@
-import { access, mkdir } from 'node:fs/promises';
+import { access, mkdir, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { BRV_DIR, CONTEXT_TREE_DIR } from '../../constants.js';
 /**
@@ -10,6 +10,11 @@ export class FileContextTreeService {
     constructor(config = {}) {
         this.config = config;
     }
+    async delete(directory) {
+        const baseDir = directory ?? this.config.baseDirectory ?? process.cwd();
+        const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
+        await rm(contextTreeDir, { force: true, recursive: true });
+    }
     async exists(directory) {
         const baseDir = directory ?? this.config.baseDirectory ?? process.cwd();
         const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);

package/dist/server/infra/context-tree/file-context-tree-snapshot-service.d.ts

@@ -12,13 +12,11 @@ export declare class FileContextTreeSnapshotService implements IContextTreeSnaps
     constructor(config?: ContextTreeSnapshotServiceConfig);
     getChanges(directory?: string): Promise<ContextTreeChanges>;
     getCurrentState(directory?: string): Promise<Map<string, FileState>>;
+    getSnapshotState(directory?: string): Promise<Map<string, FileState>>;
     hasSnapshot(directory?: string): Promise<boolean>;
     initEmptySnapshot(directory?: string): Promise<void>;
     saveSnapshot(directory?: string): Promise<void>;
-    /**
-     * Computes SHA-256 hash of file content.
-     */
-    private computeHash;
+    saveSnapshotFromState(state: Map<string, FileState>, directory?: string): Promise<void>;
     /**
      * Loads snapshot from file.
      */

package/dist/server/infra/context-tree/file-context-tree-snapshot-service.js

@@ -1,8 +1,8 @@
-import { createHash } from 'node:crypto';
-import { readdir, readFile, stat, writeFile } from 'node:fs/promises';
-import { join, relative } from 'node:path';
+import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
 import { BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR, README_FILE, SNAPSHOT_FILE } from '../../constants.js';
 import { ContextTreeSnapshot, } from '../../core/domain/entities/context-tree-snapshot.js';
+import { computeContentHash } from './hash-utils.js';
 import { toUnixPath } from './path-utils.js';
 /**
  * File-based implementation of IContextTreeSnapshotService.
@@ -37,6 +37,14 @@ export class FileContextTreeSnapshotService {
         }
         return files;
     }
+    async getSnapshotState(directory) {
+        const baseDir = directory ?? this.config.baseDirectory ?? process.cwd();
+        const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
+        const snapshot = await this.loadSnapshot(contextTreeDir);
+        if (!snapshot)
+            return new Map();
+        return new Map(snapshot.files);
+    }
     async hasSnapshot(directory) {
         const baseDir = directory ?? this.config.baseDirectory ?? process.cwd();
         const snapshotPath = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR, SNAPSHOT_FILE);
@@ -63,11 +71,13 @@ export class FileContextTreeSnapshotService {
         const snapshot = ContextTreeSnapshot.create(currentState);
         await writeFile(snapshotPath, JSON.stringify(snapshot.toJson(), null, 2), 'utf8');
     }
-    /**
-     * Computes SHA-256 hash of file content.
-     */
-    computeHash(content) {
-        return createHash('sha256').update(content).digest('hex');
+    async saveSnapshotFromState(state, directory) {
+        const baseDir = directory ?? this.config.baseDirectory ?? process.cwd();
+        const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
+        const snapshotPath = join(contextTreeDir, SNAPSHOT_FILE);
+        await mkdir(dirname(snapshotPath), { recursive: true });
+        const snapshot = ContextTreeSnapshot.create(state);
+        await writeFile(snapshotPath, JSON.stringify(snapshot.toJson(), null, 2), 'utf8');
     }
     /**
      * Loads snapshot from file.
@@ -90,7 +100,7 @@ export class FileContextTreeSnapshotService {
         const relativePath = toUnixPath(relative(rootDir, fullPath));
         const [content, fileStat] = await Promise.all([readFile(fullPath), stat(fullPath)]);
         files.set(relativePath, {
-            hash: this.computeHash(content),
+            hash: computeContentHash(content),
             size: fileStat.size,
         });
     }

package/dist/server/infra/context-tree/hash-utils.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Computes SHA-256 hash of file content.
+ * Accepts both string (decoded text) and Buffer (raw bytes) so that
+ * all callers produce identical digests for the same content.
+ */
+export declare function computeContentHash(content: Buffer | string): string;

package/dist/server/infra/context-tree/hash-utils.js

@@ -0,0 +1,9 @@
+import { createHash } from 'node:crypto';
+/**
+ * Computes SHA-256 hash of file content.
+ * Accepts both string (decoded text) and Buffer (raw bytes) so that
+ * all callers produce identical digests for the same content.
+ */
+export function computeContentHash(content) {
+    return createHash('sha256').update(content).digest('hex');
+}

package/dist/server/infra/daemon/agent-idle-timeout-policy.d.ts

@@ -0,0 +1,36 @@
+import type { IAgentIdleTimeoutPolicy } from '../../core/interfaces/daemon/i-agent-idle-timeout-policy.js';
+export interface AgentIdleTimeoutPolicyOptions {
+    readonly checkIntervalMs?: number;
+    readonly getQueueLength: (projectPath: string) => number;
+    readonly log: (message: string) => void;
+    readonly onAgentIdle: (projectPath: string, queueLength: number) => void;
+    readonly timeoutMs?: number;
+}
+/**
+ * Tracks agent activity to auto-cleanup idle agents after a period of inactivity.
+ *
+ * Uses recursive setTimeout (not setInterval) for safe cancellation.
+ * Fires callback for all idle agents in a single sweep.
+ */
+export declare class AgentIdleTimeoutPolicy implements IAgentIdleTimeoutPolicy {
+    private readonly agentActivity;
+    private readonly checkIntervalMs;
+    private readonly getQueueLength;
+    private isRunning;
+    private readonly log;
+    private readonly onAgentIdle;
+    private timeoutId;
+    private readonly timeoutMs;
+    constructor(options: AgentIdleTimeoutPolicyOptions);
+    getIdleStatus(): Array<{
+        idleMs: number;
+        projectPath: string;
+        remainingMs: number;
+    }>;
+    onAgentActivity(projectPath: string): void;
+    removeAgent(projectPath: string): void;
+    start(): void;
+    stop(): void;
+    private checkIdleAgents;
+    private scheduleCheck;
+}

package/dist/server/infra/daemon/agent-idle-timeout-policy.js

@@ -0,0 +1,89 @@
+import { AGENT_IDLE_CHECK_INTERVAL_MS, AGENT_IDLE_TIMEOUT_MS } from '../../constants.js';
+/**
+ * Tracks agent activity to auto-cleanup idle agents after a period of inactivity.
+ *
+ * Uses recursive setTimeout (not setInterval) for safe cancellation.
+ * Fires callback for all idle agents in a single sweep.
+ */
+export class AgentIdleTimeoutPolicy {
+    agentActivity = new Map(); // projectPath → lastActivityAt
+    checkIntervalMs;
+    getQueueLength;
+    isRunning = false;
+    log;
+    onAgentIdle;
+    timeoutId;
+    timeoutMs;
+    constructor(options) {
+        this.checkIntervalMs = options.checkIntervalMs ?? AGENT_IDLE_CHECK_INTERVAL_MS;
+        this.getQueueLength = options.getQueueLength;
+        this.log = options.log;
+        this.onAgentIdle = options.onAgentIdle;
+        this.timeoutMs = options.timeoutMs ?? AGENT_IDLE_TIMEOUT_MS;
+    }
+    getIdleStatus() {
+        const now = Date.now();
+        const result = [];
+        for (const [projectPath, lastActivityAt] of this.agentActivity.entries()) {
+            const idleMs = now - lastActivityAt;
+            const remainingMs = Math.max(0, this.timeoutMs - idleMs);
+            result.push({ idleMs, projectPath, remainingMs });
+        }
+        return result;
+    }
+    onAgentActivity(projectPath) {
+        this.agentActivity.set(projectPath, Date.now());
+    }
+    removeAgent(projectPath) {
+        this.agentActivity.delete(projectPath);
+    }
+    start() {
+        if (this.isRunning)
+            return;
+        this.isRunning = true;
+        this.log('Agent idle timeout policy started');
+        this.scheduleCheck();
+    }
+    stop() {
+        if (!this.isRunning)
+            return;
+        this.isRunning = false;
+        this.log('Agent idle timeout policy stopped');
+        if (this.timeoutId !== undefined) {
+            clearTimeout(this.timeoutId);
+            this.timeoutId = undefined;
+        }
+    }
+    checkIdleAgents() {
+        const now = Date.now();
+        const idleProjectPaths = [];
+        // Find all idle agents
+        for (const [projectPath, lastActivityAt] of this.agentActivity.entries()) {
+            const idleTime = now - lastActivityAt;
+            if (idleTime >= this.timeoutMs) {
+                idleProjectPaths.push(projectPath);
+            }
+        }
+        // Fire callback for each idle agent
+        for (const projectPath of idleProjectPaths) {
+            try {
+                const queueLength = this.getQueueLength(projectPath);
+                this.log(`Agent idle timeout (${this.timeoutMs}ms): ${projectPath}`);
+                this.onAgentIdle(projectPath, queueLength);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                this.log(`onAgentIdle callback failed for ${projectPath}: ${message}`);
+                // Continue checking other agents even if one fails
+            }
+        }
+    }
+    scheduleCheck() {
+        if (!this.isRunning)
+            return;
+        this.timeoutId = setTimeout(() => {
+            this.checkIdleAgents();
+            this.scheduleCheck(); // Recursive scheduling
+        }, this.checkIntervalMs);
+    }
+}

package/dist/server/infra/daemon/agent-logger.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Creates a logger function that writes timestamped messages to a log file.
+ *
+ * @param logPath - Absolute path to the log file (from BRV_SESSION_LOG env var).
+ *   If undefined/empty, returns a no-op so that logging never throws.
+ * @param prefix - Label prepended to every message (e.g. "[agent-process:/path]").
+ *
+ * Write failures are swallowed — logging must never block or crash the agent.
+ */
+export declare function createAgentLogger(logPath: string | undefined, prefix: string): (message: string) => void;

package/dist/server/infra/daemon/agent-logger.js

@@ -0,0 +1,22 @@
+import { appendFileSync } from 'node:fs';
+/**
+ * Creates a logger function that writes timestamped messages to a log file.
+ *
+ * @param logPath - Absolute path to the log file (from BRV_SESSION_LOG env var).
+ *   If undefined/empty, returns a no-op so that logging never throws.
+ * @param prefix - Label prepended to every message (e.g. "[agent-process:/path]").
+ *
+ * Write failures are swallowed — logging must never block or crash the agent.
+ */
+export function createAgentLogger(logPath, prefix) {
+    if (!logPath)
+        return () => { };
+    return (message) => {
+        try {
+            appendFileSync(logPath, `${new Date().toISOString()} ${prefix} ${message}\n`);
+        }
+        catch {
+            // ignore — never block on logging
+        }
+    };
+}

package/dist/server/infra/daemon/agent-pool.d.ts

@@ -0,0 +1,112 @@
+/**
+ * AgentPool - Manages up to N forked child process agents.
+ *
+ * Each agent is a separate Node.js process (child_process.fork())
+ * associated with a projectPath. Communicates with agents via the
+ * daemon's transport server (Socket.IO).
+ *
+ * When the pool is full, submitTask() returns an error for new projects.
+ * Existing agents can still queue tasks. Idle agents are automatically
+ * cleaned up by AgentIdleTimeoutPolicy after a period of inactivity.
+ *
+ * Pool is pure lifecycle management — zero knowledge of auth,
+ * project config, or agent internals. Each child process handles
+ * all agent setup independently.
+ *
+ * Consumed by:
+ * - brv-server.ts: instantiation and wiring
+ * - TransportHandlers: delegates task submission via submitTask()
+ * - ClientManager.onProjectEmpty → markIdle() for potential cleanup
+ */
+import type { ChildProcess } from 'node:child_process';
+import type { TaskExecute } from '../../core/domain/transport/schemas.js';
+import type { AgentEntryInfo, IAgentPool, SubmitTaskResult } from '../../core/interfaces/agent/i-agent-pool.js';
+import type { IAgentIdleTimeoutPolicy } from '../../core/interfaces/daemon/i-agent-idle-timeout-policy.js';
+import type { ITransportServer } from '../../core/interfaces/transport/i-transport-server.js';
+/**
+ * Factory function that forks a child process for an agent.
+ * Injected by consumer (brv-server.ts). Pool has no knowledge
+ * of CipherAgent, auth, or agent internals.
+ *
+ * The factory handles fork() invocation with correct module path
+ * and env vars (port, projectPath). Pool only provides projectPath.
+ * The returned ChildProcess must send IPC { type: 'ready', clientId }
+ * once initialized and connected to the transport server.
+ */
+export type AgentProcessFactory = (projectPath: string) => ChildProcess;
+type AgentPoolOptions = {
+    agentIdleTimeoutPolicy?: IAgentIdleTimeoutPolicy;
+    agentProcessFactory: AgentProcessFactory;
+    log?: (message: string) => void;
+    maxConcurrentTasks?: number;
+    maxSize?: number;
+    readyTimeoutMs?: number;
+    stopTimeoutMs?: number;
+    transportServer: ITransportServer;
+};
+export declare class AgentPool implements IAgentPool {
+    private readonly agentIdleTimeoutPolicy?;
+    private readonly agentProcessFactory;
+    private readonly agents;
+    private readonly log;
+    private readonly maxConcurrentTasks;
+    private readonly maxSize;
+    private readonly pendingForks;
+    private readonly readyTimeoutMs;
+    private shutdownRequested;
+    private readonly stopTimeoutMs;
+    private readonly taskQueue;
+    private readonly transportServer;
+    constructor(options: AgentPoolOptions);
+    getEntries(): readonly AgentEntryInfo[];
+    /**
+     * Returns task queue summary for debugging.
+     * Used by daemon:getState handler in brv-server.ts.
+     */
+    getQueueState(): Array<{
+        projectPath: string;
+        queueLength: number;
+    }>;
+    getSize(): number;
+    /**
+     * Handle agent socket disconnection.
+     * Removes the agent entry, best-effort stops the child process,
+     * and re-forks a new agent if queued tasks remain.
+     */
+    handleAgentDisconnected(projectPath: string): void;
+    hasAgent(projectPath: string): boolean;
+    markIdle(projectPath: string): void;
+    /**
+     * Called by TransportHandlers when an agent completes or errors a task.
+     * Decrements active task count and drains queued tasks for the project.
+     */
+    notifyTaskCompleted(projectPath: string): void;
+    shutdown(): Promise<void>;
+    submitTask(task: TaskExecute): Promise<SubmitTaskResult>;
+    private createAgentAndExecute;
+    private drainQueue;
+    /**
+     * Evict the least-recently-used idle agent to make room for a new project.
+     * Only evicts agents that are idle (no more external clients), have no active
+     * tasks, and have no queued tasks. Returns true if an agent was evicted.
+     *
+     * Invariant: evicted agents always have an empty task queue (enforced by the
+     * `getQueueLength === 0` guard), so `removeAgentAndRetryQueue` will never
+     * trigger a re-fork for the evicted project. This is what keeps eviction safe
+     * without going through `submitTask`'s capacity check.
+     */
+    private evictIdleAgent;
+    private forkAgent;
+    /**
+     * Shared cleanup: remove agent entry, stop process, and re-fork
+     * a new agent if queued tasks remain for the project.
+     *
+     * Idempotent: no-op if agent was already removed.
+     */
+    private removeAgentAndRetryQueue;
+    private sendTaskToAgent;
+    private stopChildProcess;
+    private tryCreateAndExecute;
+    private waitForReady;
+}
+export {};