byterover-cli 3.5.0 → 3.6.0

package/dist/server/infra/executor/query-executor.js

@@ -1,5 +1,6 @@
 import { join, relative } from 'node:path';
 import { ABSTRACT_EXTENSION, BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR } from '../../constants.js';
+import { TIER_DIRECT_SEARCH, TIER_EXACT_CACHE, TIER_FULL_AGENTIC, TIER_FUZZY_CACHE, TIER_OPTIMIZED_LLM, } from '../../core/domain/entities/query-log-entry.js';
 import { loadSources } from '../../core/domain/source/source-schema.js';
 import { isDerivedArtifact } from '../context-tree/derived-artifact.js';
 import { FileContextTreeManifestService } from '../context-tree/file-context-tree-manifest-service.js';
@@ -7,6 +8,10 @@ import { canRespondDirectly, formatDirectResponse, formatNotFoundResponse, } fro
 import { QueryResultCache } from './query-result-cache.js';
 /** Attribution footer appended to all query responses */
 const ATTRIBUTION_FOOTER = '\n\n---\nSource: ByteRover Knowledge Base';
+/** Map search results to the matchedDocs shape for QueryExecutorResult. */
+function buildMatchedDocs(sr) {
+    return (sr?.results ?? []).map((r) => ({ path: r.path, score: r.score, title: r.title }));
+}
 /** Minimum normalized score to consider a result high-confidence for pre-fetching */
 const SMART_ROUTING_SCORE_THRESHOLD = 0.7;
 /** Maximum number of documents to pre-fetch and inject into the prompt */
@@ -46,6 +51,7 @@ export class QueryExecutor {
         }
     }
     async executeWithAgent(agent, options) {
+        const startTime = Date.now();
         const { query, taskId, worktreeRoot } = options;
         const workspaceScope = this.deriveWorkspaceScope(worktreeRoot);
         // Start search early — runs in parallel with fingerprint computation (independent operations)
@@ -58,14 +64,24 @@ export class QueryExecutor {
             fingerprint = await this.computeContextTreeFingerprint(worktreeRoot);
             const cached = this.cache.get(query, fingerprint);
             if (cached) {
-                return cached + ATTRIBUTION_FOOTER;
+                return {
+                    matchedDocs: [],
+                    response: cached + ATTRIBUTION_FOOTER,
+                    tier: TIER_EXACT_CACHE,
+                    timing: { durationMs: Date.now() - startTime },
+                };
             }
         }
         // === Tier 1: Fuzzy cache match (~50ms) ===
         if (this.cache && fingerprint) {
             const fuzzyHit = this.cache.findSimilar(query, fingerprint);
             if (fuzzyHit) {
-                return fuzzyHit + ATTRIBUTION_FOOTER;
+                return {
+                    matchedDocs: [],
+                    response: fuzzyHit + ATTRIBUTION_FOOTER,
+                    tier: TIER_FUZZY_CACHE,
+                    timing: { durationMs: Date.now() - startTime },
+                };
             }
         }
         // Await search result (already started in parallel with fingerprint computation)
@@ -86,7 +102,13 @@ export class QueryExecutor {
             if (this.cache && fingerprint) {
                 this.cache.set(query, response, fingerprint);
             }
-            return response + ATTRIBUTION_FOOTER;
+            return {
+                matchedDocs: [],
+                response: response + ATTRIBUTION_FOOTER,
+                searchMetadata: { resultCount: 0, topScore: 0, totalFound: 0 },
+                tier: TIER_DIRECT_SEARCH,
+                timing: { durationMs: Date.now() - startTime },
+            };
         }
         // === Tier 2: Direct search response (~100-200ms) ===
         if (searchResult && this.fileSystem) {
@@ -95,7 +117,18 @@ export class QueryExecutor {
                 if (this.cache && fingerprint) {
                     this.cache.set(query, directResult, fingerprint);
                 }
-                return directResult + ATTRIBUTION_FOOTER;
+                return {
+                    matchedDocs: buildMatchedDocs(searchResult),
+                    response: directResult + ATTRIBUTION_FOOTER,
+                    searchMetadata: {
+                        cacheFingerprint: fingerprint,
+                        resultCount: searchResult.results.length,
+                        topScore: searchResult.results[0]?.score ?? 0,
+                        totalFound: searchResult.totalFound,
+                    },
+                    tier: TIER_DIRECT_SEARCH,
+                    timing: { durationMs: Date.now() - startTime },
+                };
             }
         }
         // === Tier 3/4: LLM call with RLM pattern (variable-based search results) ===
@@ -115,9 +148,7 @@ export class QueryExecutor {
                 if (manifest) {
                     const resolved = await manifestService.resolveForInjection(manifest, query, this.baseDirectory);
                     if (resolved.length > 0) {
-                        manifestContext = resolved
-                            .map((e) => `[${e.type} ${e.path}]\n${e.content}`)
-                            .join('\n\n---\n\n');
+                        manifestContext = resolved.map((e) => `[${e.type} ${e.path}]\n${e.content}`).join('\n\n---\n\n');
                     }
                 }
             }
@@ -169,7 +200,19 @@ export class QueryExecutor {
             if (this.cache && fingerprint) {
                 this.cache.set(query, response, fingerprint);
             }
-            return response + ATTRIBUTION_FOOTER;
+            const tier = prefetchedContext ? TIER_OPTIMIZED_LLM : TIER_FULL_AGENTIC;
+            return {
+                matchedDocs: buildMatchedDocs(searchResult),
+                response: response + ATTRIBUTION_FOOTER,
+                searchMetadata: {
+                    cacheFingerprint: fingerprint,
+                    resultCount: searchResult?.results.length ?? 0,
+                    topScore: searchResult?.results[0]?.score ?? 0,
+                    totalFound: searchResult?.totalFound ?? 0,
+                },
+                tier,
+                timing: { durationMs: Date.now() - startTime },
+            };
         }
         finally {
             // Clean up entire task session (sandbox + history) in one call
@@ -188,9 +231,7 @@ export class QueryExecutor {
         if (highConfidenceResults.length === 0)
             return undefined;
         const sections = highConfidenceResults.map((r) => {
-            const source = r.origin === 'shared' && r.originAlias
-                ? `[${r.originAlias}]:${r.path}`
-                : `.brv/context-tree/${r.path}`;
+            const source = r.origin === 'shared' && r.originAlias ? `[${r.originAlias}]:${r.path}` : `.brv/context-tree/${r.path}`;
             return `### ${r.title}\n**Source**: ${source}\n\n${r.excerpt}`;
         });
         return sections.join('\n\n---\n\n');
@@ -274,9 +315,10 @@ ${responseFormat}`;
     async computeContextTreeFingerprint(worktreeRoot) {
         // Fast path: return cached fingerprint if still valid (avoids globFiles I/O)
         // Invalidate if worktreeRoot changed or knowledge source validity changed
-        if (this.cachedFingerprint && Date.now() < this.cachedFingerprint.expiresAt
-            && this.cachedFingerprint.worktreeRoot === worktreeRoot
-            && this.cachedFingerprint.sourceValidityHash === this.computeSourceValidityHash()) {
+        if (this.cachedFingerprint &&
+            Date.now() < this.cachedFingerprint.expiresAt &&
+            this.cachedFingerprint.worktreeRoot === worktreeRoot &&
+            this.cachedFingerprint.sourceValidityHash === this.computeSourceValidityHash()) {
             return this.cachedFingerprint.value;
         }
         try {
@@ -298,7 +340,7 @@ ${responseFormat}`;
             }));
             // Include shared source state in fingerprint so edits in shared
             // projects invalidate cached query answers.
-            const loaded = this.baseDirectory ? loadSources(this.baseDirectory) : null;
+            const loaded = this.baseDirectory ? loadSources(this.baseDirectory) : undefined;
             if (loaded) {
                 // sources-file mtime detects source additions/removals
                 if (loaded.mtime) {
@@ -357,7 +399,10 @@ ${responseFormat}`;
         const loaded = loadSources(this.baseDirectory);
         if (!loaded)
             return 'no-sources';
-        return loaded.origins.map((o) => o.originKey).sort().join(',');
+        return loaded.origins
+            .map((o) => o.originKey)
+            .sort()
+            .join(',');
     }
     /**
      * Derive a workspace scope for search from the worktreeRoot.
@@ -385,9 +430,36 @@ ${responseFormat}`;
      */
     extractQueryEntities(query) {
         const stopwords = new Set([
-            'a', 'about', 'an', 'and', 'by', 'did', 'do', 'does', 'for', 'from',
-            'how', 'in', 'is', 'my', 'of', 'or', 'our', 'that', 'the', 'their',
-            'this', 'to', 'was', 'were', 'what', 'when', 'where', 'which', 'who', 'with',
+            'a',
+            'about',
+            'an',
+            'and',
+            'by',
+            'did',
+            'do',
+            'does',
+            'for',
+            'from',
+            'how',
+            'in',
+            'is',
+            'my',
+            'of',
+            'or',
+            'our',
+            'that',
+            'the',
+            'their',
+            'this',
+            'to',
+            'was',
+            'were',
+            'what',
+            'when',
+            'where',
+            'which',
+            'who',
+            'with',
         ]);
         const words = query.toLowerCase().split(/\s+/);
         return words.filter((w) => w.length >= 3 && !stopwords.has(w));
@@ -461,9 +533,7 @@ ${responseFormat}`;
                     // Use excerpt if full read fails
                 }
                 // Include source attribution in path for shared results
-                const displayPath = result.origin === 'shared' && result.originAlias
-                    ? `[${result.originAlias}]:${result.path}`
-                    : result.path;
+                const displayPath = result.origin === 'shared' && result.originAlias ? `[${result.originAlias}]:${result.path}` : result.path;
                 return { content, path: displayPath, score: result.score, title: result.title };
             }));
             if (!canRespondDirectly(fullResults))

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

@@ -39,6 +39,9 @@ export class ByteRoverMcpServer {
         this.server = new McpServer({
             name: 'byterover',
             version: config.version,
+        }, {
+            instructions: 'ByteRover MCP — curate and query project context trees. ' +
+                'See the `cwd` parameter description on each tool for how to provide the project path correctly.',
         });
         this.connectOptions = {
             clientType: 'mcp',

package/dist/server/infra/mcp/tools/brv-curate-tool.js

@@ -2,19 +2,15 @@ import { waitForConnectedClient } from '@campfirein/brv-transport-client';
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { TransportTaskEventNames } from '../../../core/domain/transport/schemas.js';
-import { associateProjectWithRetry, resolveMcpTaskContext, } from './mcp-project-context.js';
+import { associateProjectWithRetry, resolveMcpTaskContext } from './mcp-project-context.js';
 import { resolveClientCwd } from './resolve-client-cwd.js';
+import { cwdField } from './shared-schema.js';
 export const BrvCurateInputSchema = z.object({
     context: z
         .string()
         .optional()
         .describe('Knowledge to store: patterns, decisions, errors, or insights about the codebase. Required unless files or folder are provided.'),
-    cwd: z
-        .string()
-        .optional()
-        .describe('Working directory of the project (absolute path). ' +
-        'Required when the MCP server runs in global mode (e.g., Windsurf). ' +
-        'Optional in project mode — defaults to the project directory.'),
+    cwd: cwdField,
     files: z
         .array(z.string())
         .max(5)

package/dist/server/infra/mcp/tools/brv-query-tool.js

@@ -2,16 +2,12 @@ import { waitForConnectedClient } from '@campfirein/brv-transport-client';
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { TransportTaskEventNames } from '../../../core/domain/transport/schemas.js';
-import { associateProjectWithRetry, resolveMcpTaskContext, } from './mcp-project-context.js';
+import { associateProjectWithRetry, resolveMcpTaskContext } from './mcp-project-context.js';
 import { resolveClientCwd } from './resolve-client-cwd.js';
+import { cwdField } from './shared-schema.js';
 import { waitForTaskResult } from './task-result-waiter.js';
 export const BrvQueryInputSchema = z.object({
-    cwd: z
-        .string()
-        .optional()
-        .describe('Working directory of the project (absolute path). ' +
-        'Required when the MCP server runs in global mode (e.g., Windsurf). ' +
-        'Optional in project mode — defaults to the project directory.'),
+    cwd: cwdField,
     query: z.string().describe('Natural language question about the codebase or project'),
 });
 /**

package/dist/server/infra/mcp/tools/index.d.ts

@@ -1,4 +1,5 @@
 export { registerBrvCurateTool } from './brv-curate-tool.js';
 export { registerBrvQueryTool } from './brv-query-tool.js';
 export { resolveClientCwd } from './resolve-client-cwd.js';
+export { CWD_DESCRIPTION, cwdField } from './shared-schema.js';
 export { waitForTaskResult } from './task-result-waiter.js';

package/dist/server/infra/mcp/tools/index.js

@@ -1,4 +1,5 @@
 export { registerBrvCurateTool } from './brv-curate-tool.js';
 export { registerBrvQueryTool } from './brv-query-tool.js';
 export { resolveClientCwd } from './resolve-client-cwd.js';
+export { CWD_DESCRIPTION, cwdField } from './shared-schema.js';
 export { waitForTaskResult } from './task-result-waiter.js';

package/dist/server/infra/mcp/tools/shared-schema.d.ts

@@ -0,0 +1,3 @@
+import { z } from 'zod';
+export declare const CWD_DESCRIPTION: string;
+export declare const cwdField: z.ZodOptional<z.ZodString>;

package/dist/server/infra/mcp/tools/shared-schema.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export const CWD_DESCRIPTION = 'Absolute path to the project root — selects which ByteRover context tree to use ' +
+    String.raw `(e.g., "/Users/me/code/myapp", "C:\\code\\myapp").` +
+    '\n\n' +
+    'When to provide:\n' +
+    '- If your runtime does NOT expose any workspace/project context to you ' +
+    '(e.g., Claude Desktop, hosted MCP, global Windsurf): you MUST provide cwd. ' +
+    'Use the path the user mentions, or ASK the user for the absolute path if unknown.\n' +
+    '- If your runtime DOES expose an open workspace/project root to you ' +
+    '(e.g., Cursor, Cline, Zed, Claude Code): you can OMIT this field — ' +
+    'the MCP server was launched from that same project and already knows the cwd. ' +
+    'Providing it is harmless but unnecessary.\n' +
+    '\n' +
+    'If you omit cwd and the tool returns an error about the project not being resolved or cwd being required, retry with cwd explicitly set to the project root path.\n' +
+    '\n' +
+    'Never guess, never invent paths, never use relative paths.';
+export const cwdField = z.string().optional().describe(CWD_DESCRIPTION);

package/dist/server/infra/process/feature-handlers.js

@@ -9,7 +9,7 @@ import { join } from 'node:path';
 import { ReviewEvents } from '../../../shared/transport/events/review-events.js';
 import { getAuthConfig } from '../../config/auth.config.js';
 import { getCurrentConfig } from '../../config/environment.js';
-import { BRV_DIR } from '../../constants.js';
+import { API_V1_PATH, BRV_DIR } from '../../constants.js';
 import { getProjectDataDir } from '../../utils/path-utils.js';
 import { OAuthService } from '../auth/oauth-service.js';
 import { OidcDiscoveryService } from '../auth/oidc-discovery-service.js';
@@ -48,9 +48,12 @@ export async function setupFeatureHandlers({ authStateStore, broadcastToProject,
     const envConfig = getCurrentConfig();
     const tokenStore = createTokenStore();
     const projectConfigStore = new ProjectConfigStore();
-    const userService = new HttpUserService({ apiBaseUrl: envConfig.apiBaseUrl });
-    const teamService = new HttpTeamService({ apiBaseUrl: envConfig.apiBaseUrl });
-    const spaceService = new HttpSpaceService({ apiBaseUrl: envConfig.apiBaseUrl });
+    // API version paths appended at point of use.
+    // Note: IAM and Cogit currently share this version path, but may version independently in the future.
+    const iamApiV1 = `${envConfig.iamBaseUrl}${API_V1_PATH}`;
+    const userService = new HttpUserService({ apiBaseUrl: iamApiV1 });
+    const teamService = new HttpTeamService({ apiBaseUrl: iamApiV1 });
+    const spaceService = new HttpSpaceService({ apiBaseUrl: iamApiV1 });
     // Auth handler requires async OIDC discovery
     const discoveryService = new OidcDiscoveryService();
     const authConfig = await getAuthConfig(discoveryService);
@@ -86,8 +89,9 @@ export async function setupFeatureHandlers({ authStateStore, broadcastToProject,
     const contextTreeWriterService = new FileContextTreeWriterService({ snapshotService: contextTreeSnapshotService });
     const contextTreeMerger = new FileContextTreeMerger({ snapshotService: contextTreeSnapshotService });
     const contextFileReader = new FileContextFileReader();
-    const cogitPushService = new HttpCogitPushService({ apiBaseUrl: envConfig.cogitApiBaseUrl });
-    const cogitPullService = new HttpCogitPullService({ apiBaseUrl: envConfig.cogitApiBaseUrl });
+    const cogitApiV1 = `${envConfig.cogitBaseUrl}${API_V1_PATH}`;
+    const cogitPushService = new HttpCogitPushService({ apiBaseUrl: cogitApiV1 });
+    const cogitPullService = new HttpCogitPullService({ apiBaseUrl: cogitApiV1 });
     // ConnectorManager factory — creates per-project instances since constructor binds to projectRoot
     const fileService = new FsFileService();
     const templateLoader = new FsTemplateLoader(fileService);

package/dist/server/infra/process/query-log-handler.d.ts

@@ -0,0 +1,42 @@
+import type { TaskInfo } from '../../core/domain/transport/task-info.js';
+import type { QueryExecutorResult } from '../../core/interfaces/executor/i-query-executor.js';
+import type { ITaskLifecycleHook } from '../../core/interfaces/process/i-task-lifecycle-hook.js';
+import type { IQueryLogStore } from '../../core/interfaces/storage/i-query-log-store.js';
+/** Query metadata without the response string (response arrives via task:completed). */
+type QueryResultMetadata = Omit<QueryExecutorResult, 'response'>;
+/**
+ * Lifecycle hook that transparently logs query task execution.
+ *
+ * Wired into TaskRouter via lifecycleHooks[]. Writes log entries to
+ * per-project FileQueryLogStore. All I/O errors are swallowed — logging
+ * must never block or affect query task execution.
+ *
+ * Key difference from CurateLogHandler: no onToolResult accumulation.
+ * Query metadata (tier, timing, matchedDocs, searchMetadata) arrives via
+ * setQueryResult() called after QueryExecutor.executeWithAgent() returns.
+ */
+export declare class QueryLogHandler implements ITaskLifecycleHook {
+    private readonly createStore?;
+    /** Active task count per projectPath — used to evict idle stores. */
+    private readonly activeTaskCount;
+    /** Per-project store cache (one store per projectPath). Evicted when no active tasks remain. */
+    private readonly stores;
+    /** In-memory state per active task. Cleared on cleanup(). */
+    private readonly tasks;
+    constructor(createStore?: ((projectPath: string) => IQueryLogStore) | undefined);
+    cleanup(taskId: string): void;
+    onTaskCancelled(taskId: string, _task: TaskInfo): Promise<void>;
+    onTaskCompleted(taskId: string, result: string, _task: TaskInfo): Promise<void>;
+    onTaskCreate(task: TaskInfo): Promise<void | {
+        logId?: string;
+    }>;
+    onTaskError(taskId: string, errorMessage: string, _task: TaskInfo): Promise<void>;
+    /**
+     * Store query execution metadata for later finalization.
+     * Called by agent-process after QueryExecutor.executeWithAgent() returns.
+     * Synchronous — no I/O. Metadata is merged into the final entry on completion.
+     */
+    setQueryResult(taskId: string, result: QueryResultMetadata): void;
+    private getOrCreateStore;
+}
+export {};

package/dist/server/infra/process/query-log-handler.js

@@ -0,0 +1,150 @@
+import { getProjectDataDir } from '../../utils/path-utils.js';
+import { transportLog } from '../../utils/process-logger.js';
+import { FileQueryLogStore } from '../storage/file-query-log-store.js';
+const QUERY_TASK_TYPES = new Set(['query']);
+// ── QueryLogHandler ──────────────────────────────────────────────────────────
+/**
+ * Lifecycle hook that transparently logs query task execution.
+ *
+ * Wired into TaskRouter via lifecycleHooks[]. Writes log entries to
+ * per-project FileQueryLogStore. All I/O errors are swallowed — logging
+ * must never block or affect query task execution.
+ *
+ * Key difference from CurateLogHandler: no onToolResult accumulation.
+ * Query metadata (tier, timing, matchedDocs, searchMetadata) arrives via
+ * setQueryResult() called after QueryExecutor.executeWithAgent() returns.
+ */
+export class QueryLogHandler {
+    createStore;
+    /** Active task count per projectPath — used to evict idle stores. */
+    activeTaskCount = new Map();
+    /** Per-project store cache (one store per projectPath). Evicted when no active tasks remain. */
+    stores = new Map();
+    /** In-memory state per active task. Cleared on cleanup(). */
+    tasks = new Map();
+    constructor(createStore) {
+        this.createStore = createStore;
+    }
+    cleanup(taskId) {
+        const state = this.tasks.get(taskId);
+        this.tasks.delete(taskId);
+        if (state) {
+            const remaining = (this.activeTaskCount.get(state.projectPath) ?? 1) - 1;
+            if (remaining <= 0) {
+                this.activeTaskCount.delete(state.projectPath);
+                this.stores.delete(state.projectPath);
+            }
+            else {
+                this.activeTaskCount.set(state.projectPath, remaining);
+            }
+        }
+    }
+    async onTaskCancelled(taskId, _task) {
+        const state = this.tasks.get(taskId);
+        if (!state)
+            return;
+        const store = this.getOrCreateStore(state.projectPath);
+        const updated = {
+            ...state.entry,
+            completedAt: Date.now(),
+            matchedDocs: state.queryResult?.matchedDocs ?? state.entry.matchedDocs,
+            searchMetadata: state.queryResult?.searchMetadata,
+            status: 'cancelled',
+            tier: state.queryResult?.tier,
+            timing: state.queryResult?.timing,
+        };
+        await store.save(updated).catch((error) => {
+            transportLog(`QueryLogHandler: failed to save cancelled entry for ${taskId}: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    }
+    async onTaskCompleted(taskId, result, _task) {
+        const state = this.tasks.get(taskId);
+        if (!state)
+            return;
+        const store = this.getOrCreateStore(state.projectPath);
+        const updated = {
+            ...state.entry,
+            completedAt: Date.now(),
+            matchedDocs: state.queryResult?.matchedDocs ?? state.entry.matchedDocs,
+            response: result.length > 0 ? result : undefined,
+            searchMetadata: state.queryResult?.searchMetadata,
+            status: 'completed',
+            tier: state.queryResult?.tier,
+            timing: state.queryResult?.timing,
+        };
+        await store.save(updated).catch((error) => {
+            transportLog(`QueryLogHandler: failed to save completed entry for ${taskId}: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    }
+    async onTaskCreate(task) {
+        if (!QUERY_TASK_TYPES.has(task.type))
+            return;
+        if (!task.projectPath)
+            return;
+        const store = this.getOrCreateStore(task.projectPath);
+        const logId = await store.getNextId().catch((error) => {
+            transportLog(`QueryLogHandler: getNextId failed for ${task.taskId}: ${error instanceof Error ? error.message : String(error)}`);
+        });
+        if (!logId)
+            return;
+        const entry = {
+            id: logId,
+            matchedDocs: [],
+            query: task.content,
+            startedAt: task.createdAt,
+            status: 'processing',
+            taskId: task.taskId,
+        };
+        // MEMORY-FIRST: Set in-memory state BEFORE disk write so setQueryResult can access it immediately.
+        // Caching `entry` here lets onTaskCompleted/onTaskError rebuild the final entry
+        // without a getById round-trip — so completion is never lost even if this initial
+        // save fails.
+        this.tasks.set(task.taskId, { entry, projectPath: task.projectPath });
+        this.activeTaskCount.set(task.projectPath, (this.activeTaskCount.get(task.projectPath) ?? 0) + 1);
+        // Fire-and-forget disk I/O — logId is already known and returned.
+        store.save(entry).catch((error) => {
+            transportLog(`QueryLogHandler: failed to save processing entry for ${task.taskId}: ${error instanceof Error ? error.message : String(error)}`);
+        });
+        return { logId };
+    }
+    async onTaskError(taskId, errorMessage, _task) {
+        const state = this.tasks.get(taskId);
+        if (!state)
+            return;
+        const store = this.getOrCreateStore(state.projectPath);
+        const updated = {
+            ...state.entry,
+            completedAt: Date.now(),
+            error: errorMessage,
+            matchedDocs: state.queryResult?.matchedDocs ?? state.entry.matchedDocs,
+            searchMetadata: state.queryResult?.searchMetadata,
+            status: 'error',
+            tier: state.queryResult?.tier,
+            timing: state.queryResult?.timing,
+        };
+        await store.save(updated).catch((error) => {
+            transportLog(`QueryLogHandler: failed to save error entry for ${taskId}: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    }
+    /**
+     * Store query execution metadata for later finalization.
+     * Called by agent-process after QueryExecutor.executeWithAgent() returns.
+     * Synchronous — no I/O. Metadata is merged into the final entry on completion.
+     */
+    setQueryResult(taskId, result) {
+        const state = this.tasks.get(taskId);
+        if (!state)
+            return;
+        state.queryResult = result;
+    }
+    getOrCreateStore(projectPath) {
+        const existing = this.stores.get(projectPath);
+        if (existing)
+            return existing;
+        const store = this.createStore
+            ? this.createStore(projectPath)
+            : new FileQueryLogStore({ baseDir: getProjectDataDir(projectPath) });
+        this.stores.set(projectPath, store);
+        return store;
+    }
+}

package/dist/server/infra/process/task-router.d.ts

@@ -14,18 +14,41 @@
  *
  * Consumed by TransportHandlers (orchestrator).
  */
+import type { TaskCreateRequest } from '../../core/domain/transport/schemas.js';
 import type { IAgentPool } from '../../core/interfaces/agent/i-agent-pool.js';
 import type { ITaskLifecycleHook } from '../../core/interfaces/process/i-task-lifecycle-hook.js';
 import type { IProjectRegistry } from '../../core/interfaces/project/i-project-registry.js';
 import type { IProjectRouter } from '../../core/interfaces/routing/i-project-router.js';
 import type { ITransportServer } from '../../core/interfaces/transport/i-transport-server.js';
 import type { TaskInfo } from './types.js';
+/**
+ * Outcome of the daemon-side pre-dispatch check.
+ *
+ * `skipResult` is the full string sent to the client as the task:completed `result`.
+ * The callback owns the message format so task-router stays task-type-agnostic
+ * (e.g. dream uses "Dream skipped: <reason>"; future task types can use their own).
+ */
+export type PreDispatchCheckResult = {
+    eligible: false;
+    skipResult: string;
+} | {
+    eligible: true;
+};
+export type PreDispatchCheck = (task: TaskCreateRequest, projectPath?: string) => Promise<PreDispatchCheckResult>;
 type TaskRouterOptions = {
     agentPool?: IAgentPool;
     /** Function to resolve agent clientId for a given project */
     getAgentForProject: (projectPath?: string) => string | undefined;
     /** Lifecycle hooks for task events (e.g. CurateLogHandler). */
     lifecycleHooks?: ITaskLifecycleHook[];
+    /**
+     * Optional daemon-side gate run before dispatching to the agent pool. If it
+     * resolves ineligible, task-router short-circuits with task:completed carrying
+     * the skip reason and never submits the task to an agent.
+     * Used for dream task type to enforce gates 1-3 (time, activity, queue) even
+     * on the CLI dispatch path — mirrors the idle-trigger pre-check pattern.
+     */
+    preDispatchCheck?: PreDispatchCheck;
     projectRegistry?: IProjectRegistry;
     projectRouter?: IProjectRouter;
     /** Resolves the projectPath a client registered with (from client:register). */
@@ -41,6 +64,7 @@ export declare class TaskRouter {
     private completedTasks;
     private readonly getAgentForProject;
     private readonly lifecycleHooks;
+    private readonly preDispatchCheck;
     private readonly projectRegistry;
     private readonly projectRouter;
     private readonly resolveClientProjectPath;
@@ -100,6 +124,22 @@ export declare class TaskRouter {
      */
     private handleTaskCreate;
     private handleTaskError;
+    /**
+     * Emit `task:completed` for a task that the daemon's pre-dispatch gate skipped
+     * before it ever reached `AgentPool.submitTask`.
+     *
+     * Distinct from {@link handleTaskCompleted}:
+     *   - does NOT call `agentPool.notifyTaskCompleted` (the pool's `activeTasks`
+     *     counter was never incremented, so decrementing here would undercount real
+     *     load and let `drainQueue` dispatch an extra queued task)
+     *   - does NOT fire `onTaskCompleted` lifecycle hooks (counters/metrics that
+     *     act on completed tasks should not see pre-check skips as completions)
+     *
+     * Still emits the event to the client and the project room so REPL/TUI
+     * receive the skip result, and still calls `moveToCompleted` so the task is
+     * removed from the active set.
+     */
+    private handleTaskSkippedByPreCheck;
     private handleTaskStarted;
     /**
      * Move a task to the completed tasks map with grace period cleanup.