byterover-cli 3.10.3 → 3.12.0

package/dist/server/core/domain/transport/schemas.js

@@ -9,6 +9,7 @@
  */
 import { z } from 'zod';
 import { QUERY_LOG_TIERS } from '../../domain/entities/query-log-entry.js';
+import { TaskHistoryEntrySchema } from '../entities/task-history-entry.js';
 // ============================================================================
 // Zod Schemas for Runtime Validation (mirrors domain types)
 // ============================================================================
@@ -211,12 +212,22 @@ export const TransportTaskEventNames = {
     CANCEL: 'task:cancel',
     // Task terminal states
     CANCELLED: 'task:cancelled',
+    // Bulk delete terminal entries (M2.09)
+    CLEAR_COMPLETED: 'task:clearCompleted',
     COMPLETED: 'task:completed',
     CREATE: 'task:create',
     CREATED: 'task:created',
+    // Single delete (M2.09)
+    DELETE: 'task:delete',
+    // Multi delete (M2.09)
+    DELETE_BULK: 'task:deleteBulk',
+    // Broadcast on successful removal (M2.09)
+    DELETED: 'task:deleted',
     ERROR: 'task:error',
     // Internal (Transport → Agent)
     EXECUTE: 'task:execute',
+    // Single-task detail fetch (M2.09)
+    GET: 'task:get',
     // Snapshot query (Client → Transport)
     LIST: 'task:list',
     // Query metadata (Agent → Daemon, before task:completed)
@@ -386,6 +397,10 @@ export const TaskCreatedSchema = z.object({
     files: z.array(z.string()).optional(),
     /** Folder path for curate-folder task type */
     folderPath: z.string().optional(),
+    /** Active model id at task creation time */
+    model: z.string().optional(),
+    /** Active provider id at task creation time */
+    provider: z.string().optional(),
     /** Unique task identifier */
     taskId: z.string(),
     /** Task type */
@@ -443,7 +458,9 @@ export const TaskQueryResultEventSchema = z.object({
     })
         .optional(),
     taskId: z.string(),
-    tier: z.custom((val) => new Set(QUERY_LOG_TIERS).has(val), { message: 'Invalid query log tier' }),
+    tier: z.custom((val) => new Set(QUERY_LOG_TIERS).has(val), {
+        message: 'Invalid query log tier',
+    }),
     timing: z.object({ durationMs: z.number() }),
 });
 /**
@@ -563,11 +580,38 @@ export const TaskCancelResponseSchema = z.object({
 /**
  * task:list - Snapshot of active and recently-completed tasks for a project.
  * Used by the web UI Tasks tab to populate state without replaying history.
- */
-export const TaskListRequestSchema = z.object({
-    /** Optional project filter — defaults to caller's registered project */
+ *
+ * M2.16: cursor pagination dropped; numbered pagination (page/pageSize) +
+ * full filter dimensions (search/provider/model/time/duration).
+ */
+export const TaskListRequestSchema = z
+    .object({
+    /** Created at >= this epoch ms (M2.16). */
+    createdAfter: z.number().optional(),
+    /** Created at <= this epoch ms (M2.16). */
+    createdBefore: z.number().optional(),
+    /** Maximum elapsed time (ms) for terminal tasks (M2.16). */
+    maxDurationMs: z.number().optional(),
+    /** Minimum elapsed time (ms) for terminal tasks; only matches startedAt+completedAt rows (M2.16). */
+    minDurationMs: z.number().optional(),
+    /** Optional model id filter (M2.16). */
+    model: z.array(z.string()).optional(),
+    /** 1-based page index — server clamps to >= 1; defaults to 1 (M2.16). */
+    page: z.number().int().min(1).optional(),
+    /** Page size — server clamps to 1..1000; defaults to 50 (M2.16). */
+    pageSize: z.number().int().min(1).max(1000).optional(),
+    /** Optional project filter — defaults to caller's registered project. */
     projectPath: z.string().optional(),
-});
+    /** Optional provider id filter (M2.16). */
+    provider: z.array(z.string()).optional(),
+    /** Case-insensitive substring search over content + result + error.message (M2.16). */
+    searchText: z.string().optional(),
+    /** Optional status filter — return only tasks whose status matches one of these. */
+    status: z.array(z.enum(['cancelled', 'completed', 'created', 'error', 'started'])).optional(),
+    /** Optional task-type filter — e.g. ['curate'], ['query']. */
+    type: z.array(z.string()).optional(),
+})
+    .strict();
 export const TaskListItemStatusSchema = z.enum(['cancelled', 'completed', 'created', 'error', 'started']);
 export const TaskListItemSchema = z.object({
     completedAt: z.number().optional(),
@@ -578,15 +622,122 @@ export const TaskListItemSchema = z.object({
     files: z.array(z.string()).optional(),
     /** Folder path for `curate-folder` tasks */
     folderPath: z.string().optional(),
+    /** Active model id at task creation time */
+    model: z.string().optional(),
     projectPath: z.string().optional(),
+    /** Active provider id at task creation time */
+    provider: z.string().optional(),
+    /**
+     * Result string. Only present for in-memory completed tasks (toListItem
+     * populates from TaskInfo.result). Persisted entries from the index do not
+     * carry result by 2-tier design — detail panel uses task:get for full text.
+     */
     result: z.string().optional(),
     startedAt: z.number().optional(),
     status: TaskListItemStatusSchema,
     taskId: z.string(),
     type: z.string(),
 });
-export const TaskListResponseSchema = z.object({
+/** Status histogram used by FE filter-bar breakdown (M2.16). */
+export const TaskListCountsSchema = z.object({
+    all: z.number().int().nonnegative(),
+    cancelled: z.number().int().nonnegative(),
+    completed: z.number().int().nonnegative(),
+    /** Tasks with status === 'error'. */
+    failed: z.number().int().nonnegative(),
+    /** Tasks with status === 'created' || 'started'. */
+    running: z.number().int().nonnegative(),
+});
+/** (providerId, modelId) pair from history (M2.16). */
+export const TaskListAvailableModelSchema = z.object({
+    modelId: z.string(),
+    providerId: z.string(),
+});
+export const TaskListResponseSchema = z
+    .object({
+    /** Distinct (providerId, modelId) pairs in candidate set. History-derived. */
+    availableModels: z.array(TaskListAvailableModelSchema),
+    /** Distinct providerId values in candidate set. History-derived (includes uninstalled). */
+    availableProviders: z.array(z.string()),
+    /**
+     * Status histogram matching current filter scope (Model A — post-filter,
+     * `counts.all === total` invariant). FE filter-bar chip count = visible
+     * row count.
+     */
+    counts: TaskListCountsSchema,
+    /**
+     * 1-based page index, echoed back as-sent. Server clamps lower bound only
+     * (page < 1 → 1). NOT clamped against `pageCount`: a request for `page=9999`
+     * against a 1-page result returns `{page: 9999, tasks: []}` so the caller
+     * can detect an out-of-range page and correct itself.
+     */
+    page: z.number().int().min(1),
+    /** Total page count = max(ceil(total/pageSize), 1). */
+    pageCount: z.number().int().min(1),
+    /** Page size echoed back, clamped to [1, 1000]. */
+    pageSize: z.number().int().min(1).max(1000),
+    /** Page slice of items after all filters. */
     tasks: z.array(TaskListItemSchema),
+    /** Total count of items matching ALL filters (incl. status). */
+    total: z.number().int().nonnegative(),
+})
+    .strict();
+/**
+ * task:get — fetch full Level 2 detail for a single persisted task.
+ * Returns null when the task is unknown or its data file is corrupt.
+ */
+export const TaskGetRequestSchema = z.object({
+    taskId: z.string(),
+});
+export const TaskGetResponseSchema = z.object({
+    task: TaskHistoryEntrySchema.nullable(),
+});
+/**
+ * task:delete — remove a single task from the per-project history store.
+ * Idempotent: deleting a non-existent task returns success: true.
+ */
+export const TaskDeleteRequestSchema = z.object({
+    taskId: z.string(),
+});
+export const TaskDeleteResponseSchema = z.object({
+    error: z.string().optional(),
+    /**
+     * `true` when the task was actually removed (was live in-memory or persisted),
+     * `false` when the call was a no-op (taskId unknown or already tombstoned).
+     * Idempotent semantics on `success` are preserved — `success: true` indicates
+     * the request was valid; `removed` distinguishes "actually removed" from
+     * "no-op". `task:deleteBulk` uses this to compute an accurate `deletedCount`.
+     */
+    removed: z.boolean().optional(),
+    success: z.boolean(),
+});
+/**
+ * task:deleteBulk — delete many tasks at once. `deletedCount` reports actual removals.
+ */
+export const TaskDeleteBulkRequestSchema = z.object({
+    taskIds: z.array(z.string()),
+});
+export const TaskDeleteBulkResponseSchema = z.object({
+    deletedCount: z.number(),
+    error: z.string().optional(),
+});
+/**
+ * task:clearCompleted — remove all terminal-state tasks (completed/error/cancelled)
+ * from the project's history. Active tasks (created/started) are preserved.
+ */
+export const TaskClearCompletedRequestSchema = z.object({
+    projectPath: z.string().optional(),
+});
+export const TaskClearCompletedResponseSchema = z.object({
+    deletedCount: z.number(),
+    error: z.string().optional(),
+});
+/**
+ * task:deleted — broadcast to project room when a task is removed from history.
+ * Lets other clients (TUI, other webui tabs) drop the row from their local view.
+ */
+export const TaskDeletedEventSchema = z.object({
+    taskId: z.string(),
 });
 // ============================================================================
 // Session Schemas (client → server commands)

package/dist/server/core/domain/transport/task-info.d.ts

@@ -1,7 +1,13 @@
+import type { ReasoningContentItem, ToolCallEvent } from '../../../../shared/transport/events/task-events.js';
 import type { TaskErrorData, TaskListItemStatus, TaskType } from './schemas.js';
 /**
  * Tracked task metadata used by TaskRouter for routing events
  * and by ConnectionCoordinator for agent disconnect cleanup.
+ *
+ * Level 2 fields (`responseContent`, `reasoningContents`, `toolCalls`,
+ * `sessionId`) are accumulated from `llmservice:*` events and persisted
+ * by `TaskHistoryHook` so a tab refresh mid-stream can render the in-flight
+ * state.
  */
 export type TaskInfo = {
     /** Client's working directory for file validation */
@@ -18,8 +24,16 @@ export type TaskInfo = {
     folderPath?: string;
     /** Log entry ID set by lifecycle hook after onTaskCreate */
     logId?: string;
+    /** Active model id at task creation time */
+    model?: string;
     /** Project path this task belongs to (for multi-project routing) */
     projectPath?: string;
+    /** Active provider id at task creation time */
+    provider?: string;
+    /** Accumulated reasoning/thinking entries from `llmservice:thinking` + `llmservice:chunk` (type=reasoning). */
+    reasoningContents?: ReasoningContentItem[];
+    /** Final assistant response set by `llmservice:response` (overwrites on multi-step). */
+    responseContent?: string;
     /** Set on successful completion */
     result?: string;
     /**
@@ -29,11 +43,15 @@ export type TaskInfo = {
      * the user toggles the flag mid-task.
      */
     reviewDisabled?: boolean;
+    /** LLM session id set alongside `responseContent` */
+    sessionId?: string;
     /** Set when agent picks up the task */
     startedAt?: number;
     /** Lifecycle status — defaults to 'created' on construction */
     status?: TaskListItemStatus;
     taskId: string;
+    /** Accumulated tool-call lifecycle entries from `llmservice:toolCall` + `:toolResult`. */
+    toolCalls?: ToolCallEvent[];
     type: TaskType;
     /** Workspace root (linked subdir or projectRoot if unlinked) */
     worktreeRoot?: string;

package/dist/server/core/interfaces/process/i-task-lifecycle-hook.d.ts

@@ -28,6 +28,13 @@ export interface ITaskLifecycleHook {
     }>;
     /** Called when a task fails with an error. */
     onTaskError?(taskId: string, errorMessage: string, task: TaskInfo): Promise<void>;
+    /**
+     * Called by the throttled flush (~100ms window) for in-flight task mutations
+     * — `task:started` transition + every `llmservice:*` accumulator update.
+     * Optional: existing handlers (CurateLogHandler, QueryLogHandler) don't
+     * implement it. Implementations must never throw.
+     */
+    onTaskUpdate?(task: TaskInfo): Promise<void>;
     /** Called when an LLM tool result event is received for an ACTIVE task (not grace-period). */
     onToolResult?(taskId: string, payload: LlmToolResultEvent): void;
 }

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

@@ -0,0 +1,62 @@
+import type { TaskListItem } from '../../../../shared/transport/events/task-events.js';
+import type { TaskHistoryEntry, TaskHistoryStatus } from '../../domain/entities/task-history-entry.js';
+export type { TaskHistoryEntry, TaskHistoryStatus } from '../../domain/entities/task-history-entry.js';
+export interface ITaskHistoryStore {
+    /**
+     * Tombstone all matching entries. Defaults to terminal statuses
+     * (`'cancelled' | 'completed' | 'error'`) when `statuses` is omitted,
+     * so active tasks are preserved.
+     * Returns the list of removed taskIds (caller broadcasts `task:deleted` per id).
+     */
+    clear(options?: {
+        projectPath?: string;
+        statuses?: TaskHistoryStatus[];
+    }): Promise<{
+        deletedCount: number;
+        taskIds: string[];
+    }>;
+    /** Remove a single entry by taskId. Idempotent — returns false on missing/already-deleted. */
+    delete(taskId: string): Promise<boolean>;
+    /**
+     * Bulk-delete by taskIds. Returns the subset of input ids that were live
+     * (and have now been tombstoned) — invalid, unknown, and already-tombstoned
+     * ids are dropped. Callers can rely on the returned array length as the
+     * `deletedCount` and on the array contents for per-id broadcasts.
+     */
+    deleteMany(taskIds: string[]): Promise<string[]>;
+    /** Retrieve an entry's full Level 2 detail by taskId. Returns undefined if not found or corrupt. */
+    getById(taskId: string): Promise<TaskHistoryEntry | undefined>;
+    /**
+     * List entries (summary shape) sorted newest-first.
+     *
+     * Returns the wire-friendly `TaskListItem` shape — no `responseContent`, `toolCalls`,
+     * `reasoningContents`, `sessionId`, or `result`. Callers fetch full detail via `getById`.
+     *
+     * M2.16: param names align with the wire schema (`createdAfter` / `createdBefore`
+     * instead of legacy `after` / `before`). Pagination moved to the handler — store
+     * returns ALL matches; no `limit`.
+     *
+     * Note on `provider` / `model` / `status` filters: `handleTaskList` does NOT push
+     * these down — pivot filters run at the handler so derivative sets (counts,
+     * availableProviders, availableModels) can apply their exclusion rules. The
+     * options remain on the interface for direct store callers (tests, future CLI
+     * commands like `brv query-log`-style scans) that don't need pivot semantics.
+     */
+    list(options?: {
+        /** Include only entries with createdAt >= this epoch ms. */
+        createdAfter?: number;
+        /** Include only entries with createdAt <= this epoch ms. */
+        createdBefore?: number;
+        /** Include only entries matching these model ids. Direct-caller use only. */
+        model?: string[];
+        projectPath?: string;
+        /** Include only entries matching these provider ids. Direct-caller use only. */
+        provider?: string[];
+        /** Include only entries matching these statuses. Direct-caller use only. */
+        status?: TaskHistoryStatus[];
+        /** Include only entries matching these task types. */
+        type?: string[];
+    }): Promise<TaskListItem[]>;
+    /** Persist (create or overwrite) a history entry. Validates with Zod — throws on invalid shape. */
+    save(entry: TaskHistoryEntry): Promise<void>;
+}

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

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

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

@@ -44,6 +44,8 @@ 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 { TaskHistoryHook } from '../process/task-history-hook.js';
+import { 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';
@@ -334,6 +336,30 @@ async function main() {
             broadcastToProjectRoom(projectRegistry, projectRouter, info.projectPath, ReviewEvents.NOTIFY, payload, info.clientId);
         });
         const queryLogHandler = new QueryLogHandler();
+        // Task-history hook — persists every lifecycle transition + accumulated
+        // llmservice events to a per-project FileTaskHistoryStore. The store
+        // factory is module-scoped so M2.09 wire handlers can read from the
+        // same instances this hook writes to.
+        const taskHistoryHook = new TaskHistoryHook({ getStore: getTaskHistoryStore });
+        // Provider config/keychain stores — shared between feature handlers and state endpoint.
+        // Hoisted ahead of `new TransportHandlers` so the resolveActiveProvider callback below
+        // can close over them and call resolveProviderConfig synchronously at task-create time.
+        const providerConfigStore = new FileProviderConfigStore();
+        const providerKeychainStore = createProviderKeychainStore();
+        const providerOAuthTokenStore = createProviderOAuthTokenStore();
+        // Token refresh manager — transparently refreshes OAuth tokens before they expire
+        const tokenRefreshManager = new TokenRefreshManager({
+            providerConfigStore,
+            providerKeychainStore,
+            providerOAuthTokenStore,
+            transport: transportServer,
+        });
+        // Clear stale provider config on startup (e.g. migration from v1 system keychain to v2 file keystore).
+        // If a provider is configured but its API key is no longer accessible, disconnect it so the user
+        // is returned to the onboarding flow rather than hitting a cryptic API key error mid-task.
+        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 }));
         const transportHandlers = new TransportHandlers({
             agentPool,
             clientManager,
@@ -341,6 +367,7 @@ async function main() {
             // so peer clients (TUI / MCP) can render drift indicators without an
             // extra round-trip.
             daemonVersion: version,
+            getTaskHistoryStore,
             // Resolves the project's review-disabled flag once at task-create. The result
             // is stamped onto TaskInfo + TaskExecute so daemon hooks (CurateLogHandler) and
             // the agent process (curate-tool backups, dream review entries) all observe a
@@ -348,7 +375,7 @@ async function main() {
             // idle-dream dispatch above so review semantics are identical regardless of
             // dispatch source (CLI task:create vs agent-idle trigger).
             isReviewDisabled: resolveReviewDisabled,
-            lifecycleHooks: [curateLogHandler, queryLogHandler],
+            lifecycleHooks: [curateLogHandler, queryLogHandler, taskHistoryHook],
             // Daemon-side gate for dream task:create — mirrors the idle-trigger pre-check
             // in this file so the CLI path (brv dream without --force) actually honors
             // gate 3 (queue). The agent-side check kept gate 3 hardcoded to skip,
@@ -369,6 +396,21 @@ async function main() {
             },
             projectRegistry,
             projectRouter,
+            // Stamp the active provider/model snapshot onto every created task so the
+            // Web UI can display which provider handled which task. Failures are
+            // swallowed by TaskRouter's safeResolveActiveProvider — never blocks dispatch.
+            async resolveActiveProvider() {
+                const config = await resolveProviderConfig({
+                    authStateStore,
+                    providerConfigStore,
+                    providerKeychainStore,
+                    tokenRefreshManager,
+                });
+                return {
+                    ...(config.activeModel ? { model: config.activeModel } : {}),
+                    ...(config.activeProvider ? { provider: config.activeProvider } : {}),
+                };
+            },
             transport: transportServer,
         });
         transportHandlers.setup();
@@ -526,23 +568,6 @@ async function main() {
                 running: transportServer.isRunning(),
             },
         }));
-        // Provider config/keychain stores — shared between feature handlers and state endpoint
-        const providerConfigStore = new FileProviderConfigStore();
-        const providerKeychainStore = createProviderKeychainStore();
-        const providerOAuthTokenStore = createProviderOAuthTokenStore();
-        // Token refresh manager — transparently refreshes OAuth tokens before they expire
-        const tokenRefreshManager = new TokenRefreshManager({
-            providerConfigStore,
-            providerKeychainStore,
-            providerOAuthTokenStore,
-            transport: transportServer,
-        });
-        // Clear stale provider config on startup (e.g. migration from v1 system keychain to v2 file keystore).
-        // If a provider is configured but its API key is no longer accessible, disconnect it so the user
-        // is returned to the onboarding flow rather than hitting a cryptic API key error mid-task.
-        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 }));
         // Feature handlers (auth, init, status, push, pull, etc.) require async OIDC discovery.
         // Placed after daemon:getState so the debug endpoint is available immediately,
         // without waiting for OIDC discovery (~400ms).

package/dist/server/infra/dream/dream-response-schemas.d.ts

@@ -86,10 +86,16 @@ export declare const SynthesisCandidateSchema: z.ZodObject<{
         domain: string;
         fact: string;
     }>, "many">;
+    keywords: z.ZodArray<z.ZodString, "many">;
     placement: z.ZodString;
+    summary: z.ZodString;
+    tags: z.ZodArray<z.ZodString, "many">;
     title: z.ZodString;
 }, "strip", z.ZodTypeAny, {
+    summary: string;
+    tags: string[];
     title: string;
+    keywords: string[];
     confidence: number;
     claim: string;
     evidence: {
@@ -98,7 +104,10 @@ export declare const SynthesisCandidateSchema: z.ZodObject<{
     }[];
     placement: string;
 }, {
+    summary: string;
+    tags: string[];
     title: string;
+    keywords: string[];
     confidence: number;
     claim: string;
     evidence: {
@@ -121,10 +130,16 @@ export declare const SynthesizeResponseSchema: z.ZodObject<{
             domain: string;
             fact: string;
         }>, "many">;
+        keywords: z.ZodArray<z.ZodString, "many">;
         placement: z.ZodString;
+        summary: z.ZodString;
+        tags: z.ZodArray<z.ZodString, "many">;
         title: z.ZodString;
     }, "strip", z.ZodTypeAny, {
+        summary: string;
+        tags: string[];
         title: string;
+        keywords: string[];
         confidence: number;
         claim: string;
         evidence: {
@@ -133,7 +148,10 @@ export declare const SynthesizeResponseSchema: z.ZodObject<{
         }[];
         placement: string;
     }, {
+        summary: string;
+        tags: string[];
         title: string;
+        keywords: string[];
         confidence: number;
         claim: string;
         evidence: {
@@ -144,7 +162,10 @@ export declare const SynthesizeResponseSchema: z.ZodObject<{
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     syntheses: {
+        summary: string;
+        tags: string[];
         title: string;
+        keywords: string[];
         confidence: number;
         claim: string;
         evidence: {
@@ -155,7 +176,10 @@ export declare const SynthesizeResponseSchema: z.ZodObject<{
     }[];
 }, {
     syntheses: {
+        summary: string;
+        tags: string[];
         title: string;
+        keywords: string[];
         confidence: number;
         claim: string;
         evidence: {

package/dist/server/infra/dream/dream-response-schemas.js

@@ -13,6 +13,10 @@ export const ConsolidateResponseSchema = z.object({
     actions: z.array(ConsolidationActionSchema),
 });
 // ── Synthesize ───────────────────────────────────────────────────────────────
+// Bounds are slightly above the prompt's soft targets (200 chars / 3-5 tags /
+// 5-10 keywords) so a model that goes a little over still produces a usable
+// synthesis instead of being rejected outright; the caps still prevent a
+// runaway model from landing oversized text directly in card-mode YAML.
 export const SynthesisCandidateSchema = z.object({
     claim: z.string(),
     confidence: z.number().min(0).max(1),
@@ -20,7 +24,10 @@ export const SynthesisCandidateSchema = z.object({
         domain: z.string(),
         fact: z.string(),
     })),
+    keywords: z.array(z.string()).max(15),
     placement: z.string(),
+    summary: z.string().max(500),
+    tags: z.array(z.string()).max(8),
     title: z.string(),
 });
 export const SynthesizeResponseSchema = z.object({

package/dist/server/infra/dream/operations/consolidate.js

@@ -15,6 +15,7 @@ import { randomUUID } from 'node:crypto';
 import { access, mkdir, readdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { warnSidecarFailure } from '../../../core/domain/knowledge/sidecar-logging.js';
+import { isExcludedFromSync } from '../../context-tree/derived-artifact.js';
 import { ConsolidateResponseSchema } from '../dream-response-schemas.js';
 import { parseDreamResponse } from '../parse-dream-response.js';
 /**
@@ -226,7 +227,7 @@ function addFrontmatterFields(content, fields) {
                 if (parsed && typeof parsed === 'object') {
                     // Spread preserves existing key order; new fields are appended at end.
                     const merged = { ...parsed, ...fields };
-                    const newYaml = yamlDump(merged, { flowLevel: 2, lineWidth: -1, sortKeys: false }).trimEnd();
+                    const newYaml = yamlDump(merged, { flowLevel: 1, lineWidth: -1, sortKeys: false }).trimEnd();
                     return `---\n${newYaml}\n---\n${body}`;
                 }
             }
@@ -236,7 +237,7 @@ function addFrontmatterFields(content, fields) {
         }
     }
     // No valid frontmatter — prepend
-    const yaml = yamlDump(fields, { flowLevel: 2, lineWidth: -1, sortKeys: false }).trimEnd();
+    const yaml = yamlDump(fields, { flowLevel: 1, lineWidth: -1, sortKeys: false }).trimEnd();
     return `---\n${yaml}\n---\n${content}`;
 }
 // ── Helpers ──────────────────────────────────────────────────────────────────
@@ -458,8 +459,10 @@ async function executeCrossReference(action, ctx) {
         await Promise.all(Object.entries(previousTexts).map(([file, content]) => reviewBackupStore.save(file, content).catch(() => { })));
     }
     // For each file, add the other files to its related frontmatter
-    await Promise.all(action.files.map((file) => {
-        const otherFiles = action.files.filter((f) => f !== file);
+    // Skip derived-artifact targets so we never write related: onto them.
+    const eligibleFiles = action.files.filter((f) => !isExcludedFromSync(f));
+    await Promise.all(eligibleFiles.map((file) => {
+        const otherFiles = eligibleFiles.filter((f) => f !== file);
         return addRelatedLinks(join(contextTreeDir, file), otherFiles);
     }));
     return {
@@ -472,6 +475,8 @@ async function executeCrossReference(action, ctx) {
     };
 }
 async function addRelatedLinks(filePath, relatedPaths) {
+    // Skip paths that won't be pushed — they'd be dangling refs on remote.
+    const incoming = relatedPaths.filter((p) => !isExcludedFromSync(p));
     let content;
     try {
         content = await readFile(filePath, 'utf8');
@@ -491,8 +496,14 @@ async function addRelatedLinks(filePath, relatedPaths) {
             try {
                 const parsed = yamlLoad(yamlBlock);
                 if (parsed && typeof parsed === 'object') {
-                    const existing = Array.isArray(parsed.related) ? parsed.related : [];
-                    parsed.related = [...new Set([...existing, ...relatedPaths])];
+                    const hadRelated = Array.isArray(parsed.related);
+                    const existing = (Array.isArray(parsed.related) ? parsed.related : [])
+                        .filter((p) => !isExcludedFromSync(p));
+                    const merged = [...new Set([...existing, ...incoming])];
+                    // Don't introduce a related: [] key into a file that didn't have one.
+                    if (!hadRelated && merged.length === 0)
+                        return;
+                    parsed.related = merged;
                     const newYaml = yamlDump(parsed, { flowLevel: 1, lineWidth: -1, sortKeys: false }).trimEnd();
                     await atomicWrite(filePath, `---\n${newYaml}\n---\n${body}`);
                     return;
@@ -503,8 +514,10 @@ async function addRelatedLinks(filePath, relatedPaths) {
             }
         }
     }
-    // No existing frontmatter — add one with related field
-    const yaml = yamlDump({ related: relatedPaths }, { flowLevel: 1, lineWidth: -1, sortKeys: false }).trimEnd();
+    // No existing frontmatter — add one with related field, unless filter left nothing to add.
+    if (incoming.length === 0)
+        return;
+    const yaml = yamlDump({ related: incoming }, { flowLevel: 1, lineWidth: -1, sortKeys: false }).trimEnd();
     await atomicWrite(filePath, `---\n${yaml}\n---\n${content}`);
 }
 async function determineNeedsReview(actionType, files, opts) {