byterover-cli 3.13.0 → 3.15.0

package/dist/server/constants.d.ts

@@ -70,6 +70,11 @@ export declare const TASK_HISTORY_DEFAULT_MAX_ENTRIES = 1000;
 export declare const TASK_HISTORY_DEFAULT_MAX_INDEX_BLOAT_RATIO = 2;
 export declare const TASK_HISTORY_STALE_THRESHOLD_MS = 600000;
 export declare const REVIEW_BACKUPS_DIR = "review-backups";
+export declare const SETTINGS_FILE = "settings.json";
+export declare const SETTINGS_SCHEMA_VERSION = "1";
+export declare const AGENT_LLM_ITERATION_BUDGET_MS = 600000;
+export declare const AGENT_LLM_REQUEST_TIMEOUT_MS = 120000;
+export declare const TASK_HEARTBEAT_INTERVAL_MS = 10000;
 export declare const SUMMARY_INDEX_FILE = "_index.md";
 export declare const ARCHIVE_DIR = "_archived";
 export declare const STUB_EXTENSION = ".stub.md";

package/dist/server/constants.js

@@ -99,6 +99,21 @@ export const TASK_HISTORY_DEFAULT_MAX_INDEX_BLOAT_RATIO = 2;
 export const TASK_HISTORY_STALE_THRESHOLD_MS = 600_000;
 // Review backups (stores pre-curate file content for local HITL review diffs)
 export const REVIEW_BACKUPS_DIR = 'review-backups';
+// User-configurable operational settings (global, restart-required)
+export const SETTINGS_FILE = 'settings.json';
+export const SETTINGS_SCHEMA_VERSION = '1';
+// Default wall-clock budget for the agentic loop (`llm.iterationBudgetMs`).
+// Slow local-LLM users override via `brv settings set llm.iterationBudgetMs <ms>`.
+export const AGENT_LLM_ITERATION_BUDGET_MS = 600_000; // 10 minutes
+// Default per-request HTTP timeout for direct LLM provider calls
+// (`llm.requestTimeoutMs`). A hung Ollama/LM Studio connection aborts at this
+// boundary; the retry layer treats the abort as a transient error.
+export const AGENT_LLM_REQUEST_TIMEOUT_MS = 120_000; // 2 minutes
+// Per-task heartbeat interval. The task router fires `TaskEvents.HEARTBEAT`
+// after this much quiet time so the CLI can distinguish "task is slow but
+// progressing" from "daemon is stuck". Reset by any other task-scoped
+// emission. Internal constant — not user-configurable in M6.
+export const TASK_HEARTBEAT_INTERVAL_MS = 10_000; // 10 seconds
 // === Hierarchical DAG (summary, archive, manifest) ===
 export const SUMMARY_INDEX_FILE = '_index.md';
 export const ARCHIVE_DIR = '_archived';

package/dist/server/core/domain/entities/settings.d.ts

@@ -0,0 +1,55 @@
+/**
+ * High-level concern the setting controls. Drives group headers in CLI
+ * and TUI render output (uppercased). Web docs / WebUI consume this
+ * field to render the same groupings independently of key naming.
+ */
+export type SettingCategory = 'concurrency' | 'llm' | 'task-history';
+/**
+ * Value-kind for dispatch between the duration formatter / parser
+ * (`'ms'`) and the plain integer parser (`'count'`). Both surfaces and
+ * the CLI `settings set` command route on this field; without it,
+ * dispatch would require parsing the key suffix (`*Ms`), which breaks
+ * the day a key doesn't follow that convention.
+ */
+export type SettingUnit = 'count' | 'ms';
+/**
+ * Descriptor for a single user-configurable setting.
+ * Defaults reference the existing constants module so a constant change
+ * automatically updates the setting's default.
+ */
+export type SettingDescriptor = {
+    readonly category?: SettingCategory;
+    readonly default: number;
+    readonly description: string;
+    readonly key: string;
+    readonly max: number;
+    readonly min: number;
+    readonly restartRequired: true;
+    readonly type: 'integer';
+    readonly unit?: SettingUnit;
+};
+/**
+ * View of one setting: the key, the user's current override (or the default
+ * if none is set), and the registered default.
+ */
+export type SettingItem = {
+    readonly current: number;
+    readonly default: number;
+    readonly key: string;
+    readonly restartRequired: true;
+};
+/**
+ * Single source of truth for setting key names. Importers must reference
+ * these constants instead of inline string literals so a rename of one
+ * key is a typecheck error at every call site (validator, bootstrap,
+ * agent snapshot read, CLI tests).
+ */
+export declare const SETTINGS_KEYS: {
+    readonly AGENT_POOL_MAX_CONCURRENT_TASKS: "agentPool.maxConcurrentTasksPerProject";
+    readonly AGENT_POOL_MAX_SIZE: "agentPool.maxSize";
+    readonly LLM_ITERATION_BUDGET_MS: "llm.iterationBudgetMs";
+    readonly LLM_REQUEST_TIMEOUT_MS: "llm.requestTimeoutMs";
+    readonly TASK_HISTORY_MAX_ENTRIES: "taskHistory.maxEntries";
+};
+export declare const SETTINGS_REGISTRY: readonly SettingDescriptor[];
+export declare function findSettingDescriptor(key: string): SettingDescriptor | undefined;

package/dist/server/core/domain/entities/settings.js

@@ -0,0 +1,71 @@
+import { AGENT_LLM_ITERATION_BUDGET_MS, AGENT_LLM_REQUEST_TIMEOUT_MS, AGENT_MAX_CONCURRENT_TASKS, AGENT_POOL_MAX_SIZE, TASK_HISTORY_DEFAULT_MAX_ENTRIES, } from '../../../constants.js';
+/**
+ * Single source of truth for setting key names. Importers must reference
+ * these constants instead of inline string literals so a rename of one
+ * key is a typecheck error at every call site (validator, bootstrap,
+ * agent snapshot read, CLI tests).
+ */
+export const SETTINGS_KEYS = {
+    AGENT_POOL_MAX_CONCURRENT_TASKS: 'agentPool.maxConcurrentTasksPerProject',
+    AGENT_POOL_MAX_SIZE: 'agentPool.maxSize',
+    LLM_ITERATION_BUDGET_MS: 'llm.iterationBudgetMs',
+    LLM_REQUEST_TIMEOUT_MS: 'llm.requestTimeoutMs',
+    TASK_HISTORY_MAX_ENTRIES: 'taskHistory.maxEntries',
+};
+export const SETTINGS_REGISTRY = [
+    {
+        category: 'concurrency',
+        default: AGENT_POOL_MAX_SIZE,
+        description: 'How many projects can be active at the same time',
+        key: SETTINGS_KEYS.AGENT_POOL_MAX_SIZE,
+        max: 100,
+        min: 1,
+        restartRequired: true,
+        type: 'integer',
+    },
+    {
+        category: 'concurrency',
+        default: AGENT_MAX_CONCURRENT_TASKS,
+        description: 'Max parallel curate/query tasks within a single project',
+        key: SETTINGS_KEYS.AGENT_POOL_MAX_CONCURRENT_TASKS,
+        max: 50,
+        min: 1,
+        restartRequired: true,
+        type: 'integer',
+    },
+    {
+        category: 'llm',
+        default: AGENT_LLM_ITERATION_BUDGET_MS,
+        description: 'Max wall-clock budget for one agentic loop, in milliseconds',
+        key: SETTINGS_KEYS.LLM_ITERATION_BUDGET_MS,
+        max: 3_600_000,
+        min: 60_000,
+        restartRequired: true,
+        type: 'integer',
+        unit: 'ms',
+    },
+    {
+        category: 'llm',
+        default: AGENT_LLM_REQUEST_TIMEOUT_MS,
+        description: 'Max wait time per LLM response. Must be less than the agentic loop budget',
+        key: SETTINGS_KEYS.LLM_REQUEST_TIMEOUT_MS,
+        max: 3_600_000,
+        min: 10_000,
+        restartRequired: true,
+        type: 'integer',
+        unit: 'ms',
+    },
+    {
+        category: 'task-history',
+        default: TASK_HISTORY_DEFAULT_MAX_ENTRIES,
+        description: 'Max task records `brv query-log view` retains per project',
+        key: SETTINGS_KEYS.TASK_HISTORY_MAX_ENTRIES,
+        max: 10_000,
+        min: 10,
+        restartRequired: true,
+        type: 'integer',
+    },
+];
+export function findSettingDescriptor(key) {
+    return SETTINGS_REGISTRY.find((d) => d.key === key);
+}

package/dist/server/core/interfaces/storage/i-settings-store.d.ts

@@ -0,0 +1,43 @@
+import type { SettingItem } from '../../domain/entities/settings.js';
+/**
+ * Diagnostic view of the on-disk settings file consumed by the daemon
+ * bootstrap. Returns only valid overrides (caller applies them) plus a
+ * list of rejected entries (caller logs a warning per entry).
+ */
+export type SettingsStartupSnapshot = {
+    readonly invalid: ReadonlyArray<{
+        readonly key: string;
+        readonly reason: string;
+        readonly value: unknown;
+    }>;
+    /**
+     * Set when the file exists but cannot be parsed as `{version, values}`.
+     * Daemon startup logs this once; all values fall back to defaults.
+     */
+    readonly parseError?: string;
+    readonly values: Readonly<Record<string, number>>;
+};
+/**
+ * Persists and reads user-configurable operational settings.
+ *
+ * Errors:
+ * - Unknown keys throw `UnknownSettingKeyError`.
+ * - Invalid values (wrong type, out of range) throw `InvalidSettingValueError`.
+ * Callers at the transport boundary map these to typed transport errors.
+ */
+export interface ISettingsStore {
+    /** Returns the current value (or default if unset) for a single registered key. */
+    get(key: string): Promise<SettingItem>;
+    /** Returns one item per registered key with its current and default values. */
+    list(): Promise<readonly SettingItem[]>;
+    /**
+     * Reads the on-disk file and partitions it into valid overrides plus a
+     * list of rejected entries. Used by daemon startup to log a warning per
+     * invalid entry while still applying the valid keys.
+     */
+    readStartupSnapshot(): Promise<SettingsStartupSnapshot>;
+    /** Removes any user override for `key`. The next read returns the default. */
+    reset(key: string): Promise<void>;
+    /** Validates and persists an override for `key`. */
+    set(key: string, value: unknown): Promise<void>;
+}

package/dist/server/core/interfaces/storage/i-settings-store.js

@@ -0,0 +1 @@
+export {};

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

@@ -27,6 +27,7 @@ import { CipherAgent } from '../../../agent/infra/agent/index.js';
 import { FileSystemService } from '../../../agent/infra/file-system/file-system-service.js';
 import { FolderPackService } from '../../../agent/infra/folder-pack/folder-pack-service.js';
 import { SessionMetadataStore } from '../../../agent/infra/session/session-metadata-store.js';
+import { loadAgentSettingsSnapshot } from '../../../agent/infra/settings/agent-settings-snapshot.js';
 import { FileKeyStorage } from '../../../agent/infra/storage/file-key-storage.js';
 import { runWithReviewDisabled } from '../../../agent/infra/tools/implementations/curate-tool-task-context.js';
 import { createSearchKnowledgeService } from '../../../agent/infra/tools/implementations/search-knowledge-service.js';
@@ -182,6 +183,7 @@ async function start() {
         transport.requestWithAck(TransportStateEventNames.GET_AUTH),
         transport.requestWithAck(TransportStateEventNames.GET_PROVIDER_CONFIG),
         transport.requestWithAck(TransportStateEventNames.GET_BILLING_CONFIG, { projectPath }),
+        loadAgentSettingsSnapshot(transport),
     ]);
     cachedBrvConfig = configResult.brvConfig;
     cachedSpaceId = configResult.spaceId ?? '';
@@ -548,7 +550,13 @@ async function executeTask(task, curateExecutor, folderPackExecutor, queryExecut
             // the response as soon as the agent body finishes.
             agentLog(`task:completed taskId=${taskId}`);
             try {
-                transport.request(TransportTaskEventNames.COMPLETED, { clientId, ...(logId ? { logId } : {}), projectPath, result, taskId });
+                transport.request(TransportTaskEventNames.COMPLETED, {
+                    clientId,
+                    ...(logId ? { logId } : {}),
+                    projectPath,
+                    result,
+                    taskId,
+                });
             }
             catch (error) {
                 agentLog(`task:completed send failed taskId=${taskId}: ${error instanceof Error ? error.message : String(error)}`);

package/dist/server/infra/daemon/brv-server.js

@@ -29,10 +29,11 @@ import { mkdirSync, readdirSync, readFileSync, unlinkSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ReviewEvents } from '../../../shared/transport/events/review-events.js';
-import { AGENT_IDLE_CHECK_INTERVAL_MS, AGENT_IDLE_TIMEOUT_MS, AGENT_POOL_MAX_SIZE, BRV_DIR, HEARTBEAT_FILE, WEBUI_DEFAULT_PORT, } from '../../constants.js';
+import { TaskEvents } from '../../../shared/transport/events/task-events.js';
+import { AGENT_IDLE_CHECK_INTERVAL_MS, AGENT_IDLE_TIMEOUT_MS, BRV_DIR, HEARTBEAT_FILE, TASK_HEARTBEAT_INTERVAL_MS, WEBUI_DEFAULT_PORT, } from '../../constants.js';
 import { TransportStateEventNames, TransportTaskEventNames, } from '../../core/domain/transport/schemas.js';
+import { buildReviewUrl } from '../../utils/build-review-url.js';
 import { getGlobalDataDir } from '../../utils/global-data-path.js';
-import { getProjectDataDir } from '../../utils/path-utils.js';
 import { crashLog, processLog } from '../../utils/process-logger.js';
 import { createBillingStateHandler } from '../billing/billing-state-endpoint.js';
 import { ClientManager } from '../client/client-manager.js';
@@ -40,13 +41,13 @@ import { ProjectConfigStore } from '../config/file-config-store.js';
 import { readContextTreeRemoteUrl } from '../context-tree/read-context-tree-remote.js';
 import { DreamStateService } from '../dream/dream-state-service.js';
 import { DreamTrigger } from '../dream/dream-trigger.js';
-import { createReviewApiRouter } from '../http/review-api-handler.js';
 import { broadcastToProjectRoom } from '../process/broadcast-utils.js';
 import { CurateLogHandler } from '../process/curate-log-handler.js';
 import { setupFeatureHandlers } from '../process/feature-handlers.js';
 import { QueryLogHandler } from '../process/query-log-handler.js';
+import { TaskHeartbeatManager } from '../process/task-heartbeat-manager.js';
 import { TaskHistoryHook } from '../process/task-history-hook.js';
-import { getStore as getTaskHistoryStore } from '../process/task-history-store-cache.js';
+import { configureTaskHistoryStoreCache, getStore as getTaskHistoryStore } from '../process/task-history-store-cache.js';
 import { TransportHandlers } from '../process/transport-handlers.js';
 import { ProjectRegistry } from '../project/project-registry.js';
 import { createProviderOAuthTokenStore } from '../provider-oauth/provider-oauth-token-store.js';
@@ -56,9 +57,8 @@ import { ProjectRouter } from '../routing/project-router.js';
 import { AuthStateStore } from '../state/auth-state-store.js';
 import { ProjectStateLoader } from '../state/project-state-loader.js';
 import { FileBillingConfigStore } from '../storage/file-billing-config-store.js';
-import { FileCurateLogStore } from '../storage/file-curate-log-store.js';
 import { FileProviderConfigStore } from '../storage/file-provider-config-store.js';
-import { FileReviewBackupStore } from '../storage/file-review-backup-store.js';
+import { FileSettingsStore } from '../storage/file-settings-store.js';
 import { createProviderKeychainStore } from '../storage/provider-keychain-store.js';
 import { createTokenStore } from '../storage/token-store.js';
 import { SocketIOTransportServer } from '../transport/socket-io-transport-server.js';
@@ -71,6 +71,7 @@ import { DaemonResilience } from './daemon-resilience.js';
 import { HeartbeatWriter } from './heartbeat.js';
 import { IdleTimeoutPolicy } from './idle-timeout-policy.js';
 import { selectDaemonPort } from './port-selector.js';
+import { bootstrapSettings } from './settings-bootstrap.js';
 import { ShutdownHandler } from './shutdown-handler.js';
 function log(msg) {
     processLog(`[Daemon] ${msg}`);
@@ -180,13 +181,7 @@ async function main() {
             getConfig: () => ({ daemonPort: port, port: webuiPort, projectCwd: process.cwd(), version }),
             webuiDistDir,
         });
-        // Mount review API first so its responses are not subject to the
-        // web UI middleware's CSP (the review page uses inline scripts).
         const app = express();
-        app.use(createReviewApiRouter({
-            curateLogStoreFactory: (projectPath) => new FileCurateLogStore({ baseDir: getProjectDataDir(projectPath) }),
-            reviewBackupStoreFactory: (projectPath) => new FileReviewBackupStore(join(projectPath, BRV_DIR)),
-        }));
         app.use(webuiApp);
         webuiServer = new WebUiServer(app);
         try {
@@ -217,6 +212,12 @@ async function main() {
         });
         daemonResilience.install();
         // 7. Create services (auth, project state, agent pool, handlers)
+        // Settings bootstrap: read settings.json once, apply user overrides to
+        // AgentPool and task-history cache. Missing or invalid entries fall
+        // back to defaults; parseErrors and rejected entries are logged here.
+        const settingsStore = new FileSettingsStore();
+        const resolvedSettings = await bootstrapSettings({ log, store: settingsStore });
+        configureTaskHistoryStoreCache({ maxEntries: resolvedSettings.taskHistoryMaxEntries });
         const projectRegistry = new ProjectRegistry({ log });
         const projectRouter = new ProjectRouter({ transport: transportServer });
         const clientManager = new ClientManager();
@@ -323,15 +324,17 @@ async function main() {
                 return fork(agentProcessPath, [], forkOptions);
             },
             log,
+            maxConcurrentTasks: resolvedSettings.agentMaxConcurrentTasks,
+            maxSize: resolvedSettings.agentPoolMaxSize,
             transportServer,
         });
         // Start agent idle timeout policy
         agentIdleTimeoutPolicy.start();
         const curateLogHandler = new CurateLogHandler(undefined, (info) => {
-            const encoded = Buffer.from(info.projectPath).toString('base64url');
-            const reviewPort = webuiServer?.getPort() ?? port;
-            const reviewUrl = `http://127.0.0.1:${reviewPort}/review?project=${encoded}`;
-            const payload = { pendingCount: info.pendingCount, reviewUrl, taskId: info.taskId };
+            const webuiPort = webuiServer?.getPort();
+            const payload = webuiPort
+                ? { pendingCount: info.pendingCount, reviewUrl: buildReviewUrl(webuiPort, info.projectPath), taskId: info.taskId }
+                : { pendingCount: info.pendingCount, taskId: info.taskId };
             // Send directly to the task originator (covers CLI clients not in the project room)
             transportServer.sendTo(info.clientId, ReviewEvents.NOTIFY, payload);
             // Also broadcast to the project room so TUI and other connected clients are notified
@@ -362,6 +365,18 @@ async function main() {
         await clearStaleProviderConfig(providerConfigStore, providerKeychainStore, providerOAuthTokenStore);
         // State endpoint: provider config — agents request this on startup and after provider:updated
         transportServer.onRequest(TransportStateEventNames.GET_PROVIDER_CONFIG, async () => resolveProviderConfig({ authStateStore, providerConfigStore, providerKeychainStore, tokenRefreshManager }));
+        // Per-task liveness ticker (M6 T1). Fires `TaskEvents.HEARTBEAT` to the
+        // CLI during quiet periods so clients can distinguish "task still
+        // progressing" from "daemon is stuck". Reset by every other task-scoped
+        // emission inside the task router; cleared on the three terminal events.
+        const taskHeartbeatManager = new TaskHeartbeatManager({
+            emit(taskId, clientId, projectPath) {
+                const payload = { lastActivityAt: Date.now(), taskId };
+                transportServer.sendTo(clientId, TaskEvents.HEARTBEAT, payload);
+                broadcastToProjectRoom(projectRegistry, projectRouter, projectPath, TaskEvents.HEARTBEAT, payload, clientId);
+            },
+            intervalMs: TASK_HEARTBEAT_INTERVAL_MS,
+        });
         const billingConfigStoreFactory = (projectPath) => new FileBillingConfigStore({ baseDir: join(projectPath, BRV_DIR) });
         transportServer.onRequest(TransportStateEventNames.GET_BILLING_CONFIG, createBillingStateHandler(billingConfigStoreFactory));
         const transportHandlers = new TransportHandlers({
@@ -415,6 +430,7 @@ async function main() {
                     ...(config.activeProvider ? { provider: config.activeProvider } : {}),
                 };
             },
+            taskHeartbeatManager,
             transport: transportServer,
         });
         transportHandlers.setup();
@@ -527,10 +543,6 @@ async function main() {
                 webuiDistDir,
             });
             const newApp = express();
-            newApp.use(createReviewApiRouter({
-                curateLogStoreFactory: (projectPath) => new FileCurateLogStore({ baseDir: getProjectDataDir(projectPath) }),
-                reviewBackupStoreFactory: (projectPath) => new FileReviewBackupStore(join(projectPath, BRV_DIR)),
-            }));
             newApp.use(newWebuiApp);
             // Start on new port
             webuiServer = new WebUiServer(newApp);
@@ -545,7 +557,7 @@ async function main() {
             agentIdleStatus: agentIdleTimeoutPolicy.getIdleStatus(),
             agentPool: {
                 entries: agentPool.getEntries(),
-                maxSize: AGENT_POOL_MAX_SIZE,
+                maxSize: resolvedSettings.agentPoolMaxSize,
                 queue: agentPool.getQueueState(),
                 size: agentPool.getSize(),
             },
@@ -588,6 +600,7 @@ async function main() {
             providerKeychainStore,
             providerOAuthTokenStore,
             resolveProjectPath: (clientId) => clientManager.getClient(clientId)?.projectPath,
+            settingsStore,
             transport: transportServer,
             webuiPort: webuiServer?.getPort(),
         });

package/dist/server/infra/daemon/settings-bootstrap.d.ts

@@ -0,0 +1,25 @@
+import type { ISettingsStore } from '../../core/interfaces/storage/i-settings-store.js';
+/**
+ * Daemon-side resolved view of every settings key the bootstrap path
+ * consumes. Each field name mirrors the constructor option of the
+ * downstream consumer so wiring at the daemon stays mechanical.
+ */
+export type ResolvedSettings = {
+    /** Feeds `AgentPool({maxConcurrentTasks})`. */
+    readonly agentMaxConcurrentTasks: number;
+    /** Feeds `AgentPool({maxSize})`. */
+    readonly agentPoolMaxSize: number;
+    /** Feeds `FileTaskHistoryStore({maxEntries})` via the per-project cache. */
+    readonly taskHistoryMaxEntries: number;
+};
+export type BootstrapSettingsOptions = {
+    readonly log: (message: string) => void;
+    readonly store: ISettingsStore;
+};
+/**
+ * Reads the on-disk settings file once at daemon startup, logs a warning
+ * for any unparseable file or rejected entries, and returns the resolved
+ * numeric values the daemon hands to its consumers. Missing or invalid
+ * keys silently fall back to the registered defaults from `constants.ts`.
+ */
+export declare function bootstrapSettings(options: BootstrapSettingsOptions): Promise<ResolvedSettings>;

package/dist/server/infra/daemon/settings-bootstrap.js

@@ -0,0 +1,23 @@
+import { AGENT_MAX_CONCURRENT_TASKS, AGENT_POOL_MAX_SIZE, TASK_HISTORY_DEFAULT_MAX_ENTRIES, } from '../../constants.js';
+import { SETTINGS_KEYS } from '../../core/domain/entities/settings.js';
+/**
+ * Reads the on-disk settings file once at daemon startup, logs a warning
+ * for any unparseable file or rejected entries, and returns the resolved
+ * numeric values the daemon hands to its consumers. Missing or invalid
+ * keys silently fall back to the registered defaults from `constants.ts`.
+ */
+export async function bootstrapSettings(options) {
+    const { log, store } = options;
+    const snapshot = await store.readStartupSnapshot();
+    if (snapshot.parseError !== undefined) {
+        log(`[settings] failed to read settings file: ${snapshot.parseError}. Falling back to defaults.`);
+    }
+    for (const entry of snapshot.invalid) {
+        log(`[settings] ignoring invalid entry '${entry.key}': ${entry.reason}. Falling back to default.`);
+    }
+    return {
+        agentMaxConcurrentTasks: snapshot.values[SETTINGS_KEYS.AGENT_POOL_MAX_CONCURRENT_TASKS] ?? AGENT_MAX_CONCURRENT_TASKS,
+        agentPoolMaxSize: snapshot.values[SETTINGS_KEYS.AGENT_POOL_MAX_SIZE] ?? AGENT_POOL_MAX_SIZE,
+        taskHistoryMaxEntries: snapshot.values[SETTINGS_KEYS.TASK_HISTORY_MAX_ENTRIES] ?? TASK_HISTORY_DEFAULT_MAX_ENTRIES,
+    };
+}

package/dist/server/infra/git/isomorphic-git-service.d.ts

@@ -55,7 +55,10 @@ export declare class IsomorphicGitService implements IGitService {
      * Guard against staged changes that would be overwritten by checkout.
      * isomorphic-git's checkout only detects unstaged conflicts — it silently
      * overwrites staged changes, causing data loss. This method fills that gap
-     * to match native git behavior.
+     * to match native git behavior. Accepts `undefined` for the source OID when
+     * HEAD is unborn (or detached without a resolvable ref); in that case every
+     * staged blob is treated as new (sourceBlobOid undefined) so a target blob
+     * with content still triggers a conflict.
      */
     private guardStagedConflicts;
     private hashWorkdirFile;
@@ -83,6 +86,14 @@ export declare class IsomorphicGitService implements IGitService {
      * When filePaths is omitted, unstages all staged files.
      */
     private resetUnstage;
+    /**
+     * Resolve a checkout target's OID, mirroring `git.checkout`'s DWIM for
+     * remote-only branches. Returns undefined if the ref cannot be resolved
+     * anywhere, OR if multiple remotes match the same short name (matches native
+     * git's refuse-on-ambiguity, lets the caller defer to `git.checkout`'s own
+     * error). Caller decides whether to surface or skip.
+     */
+    private resolveCheckoutRef;
     /**
      * Resolves a ref expression that may include ~N ancestry syntax (e.g. HEAD~2).
      * Falls back to git.resolveRef for plain refs.
@@ -100,4 +111,6 @@ export declare class IsomorphicGitService implements IGitService {
      * 2. Ensures `\n` before `=======` and `>>>>>>>` (isomorphic-git omits it when content has no trailing newline)
      */
     private rewriteConflictMarkers;
+    /** Resolve a ref to its OID, returning undefined instead of throwing on missing/unborn refs. */
+    private tryResolveRef;
 }

package/dist/server/infra/git/isomorphic-git-service.js

@@ -113,13 +113,20 @@ export class IsomorphicGitService {
         // isomorphic-git's checkout only restores target files but does NOT remove
         // files that are tracked in the source branch but absent in the target.
         // Native git removes them, so we do it manually after checkout.
+        // When HEAD points at an unborn branch (post-init, pre-commit), the ref does
+        // not resolve — treat as no tracked files and skip the staged-conflict guard.
         const sourceBranch = await this.getCurrentBranch(params);
-        const sourceFiles = sourceBranch ? new Set(await git.listFiles({ dir, fs, ref: sourceBranch })) : new Set();
+        const sourceOid = sourceBranch ? await this.tryResolveRef(dir, sourceBranch) : undefined;
+        const sourceFiles = sourceBranch && sourceOid
+            ? new Set(await git.listFiles({ dir, fs, ref: sourceBranch }))
+            : new Set();
         // isomorphic-git's checkout detects unstaged conflicts (CheckoutConflictError)
         // but silently overwrites staged changes — a data-loss bug. Guard staged
-        // conflicts here to match native git behavior.
-        if (!params.force && sourceBranch) {
-            await this.guardStagedConflicts(dir, sourceBranch, params.ref);
+        // conflicts here to match native git behavior. The guard also covers unborn
+        // HEAD and detached HEAD (sourceOid undefined): every staged blob is treated
+        // as new content, so a conflicting target blob still trips.
+        if (!params.force) {
+            await this.guardStagedConflicts(dir, sourceOid, params.ref);
         }
         try {
             await git.checkout({ dir, force: params.force, fs, ref: params.ref });
@@ -857,21 +864,30 @@ export class IsomorphicGitService {
      * Guard against staged changes that would be overwritten by checkout.
      * isomorphic-git's checkout only detects unstaged conflicts — it silently
      * overwrites staged changes, causing data loss. This method fills that gap
-     * to match native git behavior.
+     * to match native git behavior. Accepts `undefined` for the source OID when
+     * HEAD is unborn (or detached without a resolvable ref); in that case every
+     * staged blob is treated as new (sourceBlobOid undefined) so a target blob
+     * with content still triggers a conflict.
      */
-    async guardStagedConflicts(dir, sourceBranch, targetRef) {
+    async guardStagedConflicts(dir, sourceOid, targetRef) {
         const matrix = await git.statusMatrix({ dir, fs });
         const stagedFiles = matrix
             .filter(([, head, workdir, stage]) => classifyTuple(head, workdir, stage).staged)
             .map(([filepath]) => String(filepath));
         if (stagedFiles.length === 0)
             return;
-        const sourceOid = await git.resolveRef({ dir, fs, ref: sourceBranch });
-        const targetOid = await git.resolveRef({ dir, fs, ref: targetRef });
+        // If our resolver cannot pin the target OID (no direct ref + no unambiguous
+        // remote DWIM match), skip the guard and let `git.checkout` surface the
+        // missing-ref error itself. The trade-off: when isomorphic-git's internal
+        // resolution finds a path we missed, the guard will not have read against
+        // the same tree git.checkout writes — acceptable for single-remote setups.
+        const targetOid = await this.resolveCheckoutRef(dir, targetRef);
+        if (!targetOid)
+            return;
         const conflicting = [];
         /* eslint-disable no-await-in-loop -- sequential file I/O is intentional here */
         for (const filepath of stagedFiles) {
-            const sourceBlobOid = await this.readBlobOid(dir, sourceOid, filepath);
+            const sourceBlobOid = sourceOid ? await this.readBlobOid(dir, sourceOid, filepath) : undefined;
             const targetBlobOid = await this.readBlobOid(dir, targetOid, filepath);
             if (sourceBlobOid !== targetBlobOid) {
                 conflicting.push(filepath);
@@ -1130,6 +1146,29 @@ export class IsomorphicGitService {
             : toUnstage.map((filepath) => git.remove({ dir, filepath, fs })));
         return { filesChanged: toUnstage.length, headSha: headSha ?? '' };
     }
+    /**
+     * Resolve a checkout target's OID, mirroring `git.checkout`'s DWIM for
+     * remote-only branches. Returns undefined if the ref cannot be resolved
+     * anywhere, OR if multiple remotes match the same short name (matches native
+     * git's refuse-on-ambiguity, lets the caller defer to `git.checkout`'s own
+     * error). Caller decides whether to surface or skip.
+     */
+    async resolveCheckoutRef(dir, ref) {
+        const direct = await this.tryResolveRef(dir, ref);
+        if (direct)
+            return direct;
+        const remotes = await git.listRemotes({ dir, fs }).catch(() => []);
+        const matches = [];
+        for (const { remote } of remotes) {
+            // eslint-disable-next-line no-await-in-loop
+            const remoteOid = await this.tryResolveRef(dir, `refs/remotes/${remote}/${ref}`);
+            if (remoteOid)
+                matches.push(remoteOid);
+        }
+        if (matches.length === 1)
+            return matches[0];
+        return undefined;
+    }
     /**
      * Resolves a ref expression that may include ~N ancestry syntax (e.g. HEAD~2).
      * Falls back to git.resolveRef for plain refs.
@@ -1193,4 +1232,13 @@ export class IsomorphicGitService {
             await fs.promises.writeFile(filePath, content);
         }));
     }
+    /** Resolve a ref to its OID, returning undefined instead of throwing on missing/unborn refs. */
+    async tryResolveRef(dir, ref) {
+        try {
+            return await git.resolveRef({ dir, fs, ref });
+        }
+        catch {
+            return undefined;
+        }
+    }
 }

package/dist/server/infra/mcp/mcp-server.d.ts

@@ -43,7 +43,11 @@ export declare class ByteRoverMcpServer {
     /**
      * Stops the MCP server.
      *
-     * Disconnects from the brv instance.
+     * Order: stop background work first (reconnector, heartbeat), then drop
+     * the daemon connection so any in-flight tool handler awaiting daemon work
+     * surfaces a clean MCP error response, THEN close the MCP SDK server so
+     * those error responses still travel back to the parent before the stdio
+     * transport seals.
      */
     stop(): Promise<void>;
     /**

package/dist/server/infra/mcp/mcp-server.js

@@ -128,7 +128,11 @@ export class ByteRoverMcpServer {
     /**
      * Stops the MCP server.
      *
-     * Disconnects from the brv instance.
+     * Order: stop background work first (reconnector, heartbeat), then drop
+     * the daemon connection so any in-flight tool handler awaiting daemon work
+     * surfaces a clean MCP error response, THEN close the MCP SDK server so
+     * those error responses still travel back to the parent before the stdio
+     * transport seals.
      */
     async stop() {
         // Cancel auto-reconnection
@@ -139,10 +143,15 @@ export class ByteRoverMcpServer {
             clearInterval(this.heartbeatInterval);
             this.heartbeatInterval = undefined;
         }
+        // Disconnect daemon first — in-flight tool handlers reject with a clean
+        // "Connection lost" error that can still be delivered over the open MCP
+        // transport (see task-result-waiter onStateChange handler).
         if (this.client) {
             await this.client.disconnect();
             this.client = undefined;
         }
+        // Then close the MCP SDK server (final stdio teardown).
+        await this.server.close();
     }
     /**
      * Returns the project root directory for MCP tool calls.

package/dist/server/infra/process/feature-handlers.d.ts

@@ -10,6 +10,7 @@ import type { IProviderOAuthTokenStore } from '../../core/interfaces/i-provider-
 import type { IProjectRegistry } from '../../core/interfaces/project/i-project-registry.js';
 import type { IAuthStateStore } from '../../core/interfaces/state/i-auth-state-store.js';
 import type { IBillingConfigStore } from '../../core/interfaces/storage/i-billing-config-store.js';
+import type { ISettingsStore } from '../../core/interfaces/storage/i-settings-store.js';
 import type { ITransportServer } from '../../core/interfaces/transport/i-transport-server.js';
 import type { ProjectBroadcaster, ProjectPathResolver } from '../transport/handlers/handler-types.js';
 export interface FeatureHandlersOptions {
@@ -23,6 +24,7 @@ export interface FeatureHandlersOptions {
     providerKeychainStore: IProviderKeychainStore;
     providerOAuthTokenStore: IProviderOAuthTokenStore;
     resolveProjectPath: ProjectPathResolver;
+    settingsStore: ISettingsStore;
     transport: ITransportServer;
     webuiPort?: number;
 }
@@ -30,4 +32,4 @@ export interface FeatureHandlersOptions {
  * Setup all feature handlers on the transport server.
  * These handlers implement the TUI ↔ Server event contract (auth:*, config:*, status:*, etc.).
  */
-export declare function setupFeatureHandlers({ authStateStore, billingConfigStoreFactory, broadcastToProject, getActiveProjectPaths, log, projectRegistry, providerConfigStore, providerKeychainStore, providerOAuthTokenStore, resolveProjectPath, transport, webuiPort, }: FeatureHandlersOptions): Promise<void>;
+export declare function setupFeatureHandlers({ authStateStore, billingConfigStoreFactory, broadcastToProject, getActiveProjectPaths, log, projectRegistry, providerConfigStore, providerKeychainStore, providerOAuthTokenStore, resolveProjectPath, settingsStore, transport, webuiPort, }: FeatureHandlersOptions): Promise<void>;