byterover-cli 3.10.1 → 3.10.2

package/dist/agent/infra/map/abstract-queue.js

@@ -1,7 +1,16 @@
 import { appendFileSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { generateFileAbstracts } from './abstract-generator.js';
+import { isAbsolute, join } from 'node:path';
+import { generateFileAbstractsBatch } from './abstract-generator.js';
+/**
+ * Maximum files combined into a single batched L0/L1 LLM call.
+ *
+ * Two parallel calls fire per cycle: one L0 batch (~80 tok output × N files +
+ * tags), one L1 batch (~1500 tok output × N files + tags). At N=5 the L1
+ * output budget caps at ~8K tokens; raising N further risks output truncation
+ * on smaller-context models. Lowering N reduces savings without quality gain.
+ */
+const BATCH_SIZE_CAP = 5;
 const QUEUE_TRACE_ENABLED = process.env.BRV_QUEUE_TRACE === '1';
 const LOG_PATH = process.env.BRV_SESSION_LOG;
 function queueLog(message) {
@@ -26,6 +35,13 @@ function queueLog(message) {
 export class AbstractGenerationQueue {
     projectRoot;
     maxAttempts;
+    /**
+     * When true, scheduleNext fires the next batch even if pending is below
+     * BATCH_SIZE_CAP. Set by drain(); reset once the queue is fully idle.
+     * Without this, items below the cap would be buffered indefinitely with
+     * no flush trigger when a curate writes fewer files than the cap.
+     */
+    drainRequested = false;
     drainResolvers = [];
     failed = 0;
     generator;
@@ -48,7 +64,12 @@ export class AbstractGenerationQueue {
      */
     async drain() {
         queueLog(`drain:start idle=${this.isIdle()} pending=${this.pending.length} retrying=${this.retrying} processing=${this.processing}`);
+        // Force any buffered (below-cap) pending items to fire as a final batch.
+        // scheduleNext respects drainRequested even when pending < BATCH_SIZE_CAP.
+        this.drainRequested = true;
+        this.scheduleNext();
         if (this.isIdle()) {
+            this.drainRequested = false;
             await this.statusWritePromise.catch(() => { });
             queueLog('drain:resolved-immediate');
             return;
@@ -63,6 +84,17 @@ export class AbstractGenerationQueue {
      * Add a file to the abstract generation queue.
      */
     enqueue(item) {
+        // Background batch writes derive .abstract.md / .overview.md from
+        // contextPath via raw `writeFile`. A relative path would resolve under
+        // process.cwd() rather than the intended context-tree location, and the
+        // failure would be invisible because batch errors are catch-suppressed.
+        // Drop misconfigured items at the entry point with a trace breadcrumb
+        // rather than failing loudly — callers are internal and treat the queue
+        // as fail-open.
+        if (!isAbsolute(item.contextPath)) {
+            queueLog(`enqueue:dropped non-absolute path=${item.contextPath}`);
+            return;
+        }
         // Guard against paths that must never trigger abstract generation:
         // - derived artifacts (.abstract.md, .overview.md) — would produce .abstract.abstract.md
         // - summary index files (_index.md) — domain/topic summaries, not knowledge nodes
@@ -77,7 +109,13 @@ export class AbstractGenerationQueue {
         this.pending.push({ attempts: 0, contextPath: item.contextPath, fullContent: item.fullContent });
         queueLog(`enqueue path=${item.contextPath} pending=${this.pending.length} retrying=${this.retrying} processing=${this.processing}`);
         this.queueStatusWrite();
-        this.scheduleNext();
+        // Buffer until cap is reached; drain() will trigger the final flush
+        // for partial batches at curate-end. Without this gating, the first
+        // enqueue starts a 1-item batch before the curate finishes writing
+        // the rest of its files.
+        if (this.pending.length >= BATCH_SIZE_CAP || this.drainRequested) {
+            this.scheduleNext();
+        }
     }
     /**
      * Return current queue status snapshot.
@@ -110,14 +148,25 @@ export class AbstractGenerationQueue {
         return this.pending.length === 0 && !this.processing && this.retrying === 0;
     }
     async processNext() {
-        if (!this.generator || this.processing || this.pending.length === 0) {
+        // Capture the generator in a local const so type narrowing survives the
+        // `await` boundary below — TS won't keep `this.generator` narrow across
+        // suspensions because another async path could reassign the property.
+        const { generator } = this;
+        if (!generator || this.processing || this.pending.length === 0) {
             this.resolveDrainersIfIdle();
             return;
         }
         this.processing = true;
         this.queueStatusWrite();
-        const item = this.pending.shift();
-        queueLog(`process:start path=${item.contextPath} remaining=${this.pending.length} retrying=${this.retrying}`);
+        // Drain up to BATCH_SIZE_CAP items into a single batch. Items beyond the
+        // cap stay pending for the next cycle. Note: `maxAttempts` counts BATCH
+        // attempts for this item, not individual-call attempts — a transient
+        // failure on attempt 1 consumes one retry token for every item in the
+        // batch, including ones whose content was unrelated to the failure.
+        // Acceptable: batches are small (cap=5) and the per-item re-enqueue on
+        // batch failure preserves attempts independently across cycles.
+        const batch = this.pending.splice(0, BATCH_SIZE_CAP);
+        queueLog(`process:start batchSize=${batch.length} remaining=${this.pending.length} retrying=${this.retrying}`);
         try {
             // Refresh credentials before each generation (OAuth tokens may expire)
             try {
@@ -127,23 +176,40 @@ export class AbstractGenerationQueue {
                 const msg = error instanceof Error ? error.message : String(error);
                 console.debug(`[AbstractQueue] token refresh failed, proceeding with existing generator: ${msg}`);
             }
-            const { abstractContent, overviewContent } = await generateFileAbstracts(item.fullContent, this.generator);
-            // Derive sibling paths: replace .md with .abstract.md and .overview.md
-            const abstractPath = item.contextPath.replace(/\.md$/, '.abstract.md');
-            const overviewPath = item.contextPath.replace(/\.md$/, '.overview.md');
-            await Promise.all([
-                writeFile(abstractPath, abstractContent, 'utf8'),
-                writeFile(overviewPath, overviewContent, 'utf8'),
-            ]);
-            this.processed++;
-            queueLog(`process:success path=${item.contextPath} processed=${this.processed}`);
+            const results = await generateFileAbstractsBatch(batch.map((it) => ({ contextPath: it.contextPath, fullContent: it.fullContent })), generator);
+            // Write all batched outputs in parallel. Empty strings are valid (model
+            // produced no content for that path) — preserves existing fail-open.
+            await Promise.all(results.flatMap((r) => {
+                const abstractPath = r.contextPath.replace(/\.md$/, '.abstract.md');
+                const overviewPath = r.contextPath.replace(/\.md$/, '.overview.md');
+                return [
+                    writeFile(abstractPath, r.abstractContent, 'utf8'),
+                    writeFile(overviewPath, r.overviewContent, 'utf8'),
+                ];
+            }));
+            this.processed += batch.length;
+            queueLog(`process:success batchSize=${batch.length} processed=${this.processed}`);
         }
         catch (error) {
+            // Batch-level failure → re-enqueue each item individually with its own
+            // attempts counter, mirroring per-item retry semantics. Items past
+            // maxAttempts count as failed.
             const msg = error instanceof Error ? error.message : String(error);
-            console.debug(`[AbstractQueue] ${item.contextPath} attempt ${item.attempts + 1}/${this.maxAttempts}: ${msg}`);
-            item.attempts++;
-            if (item.attempts < this.maxAttempts) {
-                // Exponential backoff: 500ms, 1000ms, 2000ms, ...
+            const failedThisCycle = [];
+            const retryThisCycle = [];
+            for (const item of batch) {
+                item.attempts++;
+                if (item.attempts < this.maxAttempts) {
+                    retryThisCycle.push(item);
+                }
+                else {
+                    this.failed++;
+                    failedThisCycle.push(item);
+                    queueLog(`process:failed path=${item.contextPath} failed=${this.failed}`);
+                }
+            }
+            console.debug(`[AbstractQueue] batch attempt failed (${msg}); retrying=${retryThisCycle.length}, exhausted=${failedThisCycle.length}`);
+            for (const item of retryThisCycle) {
                 const delay = 500 * 2 ** (item.attempts - 1);
                 this.retrying++;
                 this.queueStatusWrite();
@@ -155,14 +221,10 @@ export class AbstractGenerationQueue {
                     this.scheduleNext();
                 }, delay);
             }
-            else {
-                this.failed++;
-                queueLog(`process:failed path=${item.contextPath} failed=${this.failed}`);
-            }
         }
         finally {
             this.processing = false;
-            queueLog(`process:finally path=${item.contextPath} pending=${this.pending.length} retrying=${this.retrying} processed=${this.processed} failed=${this.failed}`);
+            queueLog(`process:finally batchSize=${batch.length} pending=${this.pending.length} retrying=${this.retrying} processed=${this.processed} failed=${this.failed}`);
             this.queueStatusWrite();
         }
         this.scheduleNext();
@@ -177,6 +239,9 @@ export class AbstractGenerationQueue {
         if (!this.isIdle() || this.drainResolvers.length === 0) {
             return;
         }
+        // Reset drain state once the queue settles — next curate's enqueue burst
+        // should buffer normally up to BATCH_SIZE_CAP again.
+        this.drainRequested = false;
         queueLog(`drain:idle pending=${this.pending.length} retrying=${this.retrying} processed=${this.processed} failed=${this.failed}`);
         const resolvers = this.drainResolvers.splice(0);
         const settledStatusWrite = this.statusWritePromise.catch(() => { });
@@ -185,10 +250,19 @@ export class AbstractGenerationQueue {
         }
     }
     scheduleNext() {
-        if (!this.generator || this.processing || this.pending.length === 0) {
+        if (!this.generator || this.processing) {
+            return;
+        }
+        if (this.pending.length === 0) {
             this.resolveDrainersIfIdle();
             return;
         }
+        // Buffer items below the cap unless drain has been requested (curate-end
+        // signal). This keeps the queue from firing partial 1-item batches in the
+        // middle of a multi-file curate.
+        if (this.pending.length < BATCH_SIZE_CAP && !this.drainRequested) {
+            return;
+        }
         // eslint-disable-next-line no-void
         setImmediate(() => { void this.processNext(); });
     }

package/dist/agent/infra/system-prompt/contributors/file-contributor.js

@@ -110,12 +110,16 @@ export class FileContributor {
      */
     renderTemplateVariables(template, context) {
         let result = template;
-        // Build variables from context
+        // Build variables from context.
+        // Note: a `datetime` template variable is intentionally NOT exposed here.
+        // Per-call timestamps must never enter the system prompt — they would
+        // poison the prefix cache from that byte onward. The current date/time
+        // is injected once into the iter-0 user message instead (see
+        // agent-llm-service.ts).
         /* eslint-disable camelcase */
         const variables = {
             available_markers: context.availableMarkers ? Object.keys(context.availableMarkers).join(', ') : '',
             available_tools: context.availableTools?.join(', ') ?? '',
-            datetime: `<dateTime>Current date and time: ${new Date().toISOString()}</dateTime>`,
         };
         /* eslint-enable camelcase */
         // Replace {{variable}} with values

package/dist/agent/infra/tools/tool-manager.d.ts

@@ -31,12 +31,21 @@ export declare class ToolManager {
     /**
      * Tools allowed for curate operations.
      * Uses code_exec only - curate operations available via tools.curate() in sandbox.
+     *
+     * NOTE: Insertion order is load-bearing for Anthropic prompt caching.
+     * `toAiSdkTools` attaches `cacheControl: ephemeral` to the LAST tool in
+     * iteration order, which becomes the cache breakpoint. Reordering this
+     * list (or the per-call sort in `filterToolsForCommand`) silently shifts
+     * the breakpoint and can halve cache hit-rate. Append new tools at the end.
      */
     private static readonly CURATE_TOOL_NAMES;
     /**
      * Tools allowed for query operations - only code_exec for programmatic search
      * All search operations (searchKnowledge, glob, grep, readFile) are available
-     * via tools.* SDK inside the sandbox
+     * via tools.* SDK inside the sandbox.
+     *
+     * Same insertion-order contract as CURATE_TOOL_NAMES (Anthropic cache
+     * breakpoint lands on the last tool).
      */
     private static readonly QUERY_TOOL_NAMES;
     private cacheValid;

package/dist/agent/infra/tools/tool-manager.js

@@ -27,6 +27,12 @@ export class ToolManager {
     /**
      * Tools allowed for curate operations.
      * Uses code_exec only - curate operations available via tools.curate() in sandbox.
+     *
+     * NOTE: Insertion order is load-bearing for Anthropic prompt caching.
+     * `toAiSdkTools` attaches `cacheControl: ephemeral` to the LAST tool in
+     * iteration order, which becomes the cache breakpoint. Reordering this
+     * list (or the per-call sort in `filterToolsForCommand`) silently shifts
+     * the breakpoint and can halve cache hit-rate. Append new tools at the end.
      */
     static CURATE_TOOL_NAMES = [
         'agentic_map',
@@ -37,7 +43,10 @@ export class ToolManager {
     /**
      * Tools allowed for query operations - only code_exec for programmatic search
      * All search operations (searchKnowledge, glob, grep, readFile) are available
-     * via tools.* SDK inside the sandbox
+     * via tools.* SDK inside the sandbox.
+     *
+     * Same insertion-order contract as CURATE_TOOL_NAMES (Anthropic cache
+     * breakpoint lands on the last tool).
      */
     static QUERY_TOOL_NAMES = [
         'code_exec',

package/dist/server/infra/dream/dream-state-schema.d.ts

@@ -15,6 +15,22 @@ export declare const PendingMergeSchema: z.ZodObject<{
     sourceFile: string;
     suggestedByDreamId: string;
 }>;
+/**
+ * One entry in the stale-summary queue drained at the next dream cycle.
+ * `enqueuedAt` is preserved across dedup'd re-enqueues so future telemetry
+ * (e.g., "oldest waiting path") can read meaningful wait times even though
+ * no consumer reads it today.
+ */
+export declare const StaleSummaryEntrySchema: z.ZodObject<{
+    enqueuedAt: z.ZodNumber;
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    enqueuedAt: number;
+}, {
+    path: string;
+    enqueuedAt: number;
+}>;
 export declare const DreamStateSchema: z.ZodObject<{
     curationsSinceDream: z.ZodNumber;
     lastDreamAt: z.ZodNullable<z.ZodString>;
@@ -35,6 +51,16 @@ export declare const DreamStateSchema: z.ZodObject<{
         sourceFile: string;
         suggestedByDreamId: string;
     }>, "many">>>;
+    staleSummaryPaths: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        enqueuedAt: z.ZodNumber;
+        path: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        enqueuedAt: number;
+    }, {
+        path: string;
+        enqueuedAt: number;
+    }>, "many">>>;
     totalDreams: z.ZodNumber;
     version: z.ZodLiteral<1>;
 }, "strip", z.ZodTypeAny, {
@@ -48,6 +74,10 @@ export declare const DreamStateSchema: z.ZodObject<{
         sourceFile: string;
         suggestedByDreamId: string;
     }[];
+    staleSummaryPaths: {
+        path: string;
+        enqueuedAt: number;
+    }[];
     totalDreams: number;
 }, {
     version: 1;
@@ -61,7 +91,12 @@ export declare const DreamStateSchema: z.ZodObject<{
         sourceFile: string;
         suggestedByDreamId: string;
     }[] | undefined;
+    staleSummaryPaths?: {
+        path: string;
+        enqueuedAt: number;
+    }[] | undefined;
 }>;
 export type DreamState = z.infer<typeof DreamStateSchema>;
 export type PendingMerge = z.infer<typeof PendingMergeSchema>;
+export type StaleSummaryEntry = z.infer<typeof StaleSummaryEntrySchema>;
 export declare const EMPTY_DREAM_STATE: DreamState;

package/dist/server/infra/dream/dream-state-schema.js

@@ -5,11 +5,25 @@ export const PendingMergeSchema = z.object({
     sourceFile: z.string(),
     suggestedByDreamId: z.string(),
 });
+/**
+ * One entry in the stale-summary queue drained at the next dream cycle.
+ * `enqueuedAt` is preserved across dedup'd re-enqueues so future telemetry
+ * (e.g., "oldest waiting path") can read meaningful wait times even though
+ * no consumer reads it today.
+ */
+export const StaleSummaryEntrySchema = z.object({
+    enqueuedAt: z.number().int().nonnegative(),
+    // Empty paths indicate a bug at the call site (a malformed diff entry would
+    // resolve to an empty parent dir); reject them at the schema boundary so
+    // garbage cannot persist into dream-state.json.
+    path: z.string().min(1),
+});
 export const DreamStateSchema = z.object({
     curationsSinceDream: z.number().int().min(0),
     lastDreamAt: z.string().datetime().nullable(),
     lastDreamLogId: z.string().nullable(),
     pendingMerges: z.array(PendingMergeSchema).optional().default([]),
+    staleSummaryPaths: z.array(StaleSummaryEntrySchema).optional().default([]),
     totalDreams: z.number().int().min(0),
     version: z.literal(1),
 });
@@ -18,6 +32,7 @@ export const EMPTY_DREAM_STATE = {
     lastDreamAt: null,
     lastDreamLogId: null,
     pendingMerges: [],
+    staleSummaryPaths: [],
     totalDreams: 0,
     version: 1,
 };

package/dist/server/infra/dream/dream-state-service.d.ts

@@ -11,6 +11,28 @@ type DreamStateServiceOptions = {
 export declare class DreamStateService {
     private readonly stateFilePath;
     constructor(opts: DreamStateServiceOptions);
+    /**
+     * Atomic drain — reads the current queue and clears it in a single RMW,
+     * returning the deduped path list. The caller is responsible for retrying
+     * (re-enqueueing the returned snapshot) if the downstream work fails.
+     *
+     * Atomicity is the load-bearing property: any enqueue that runs after the
+     * drain returns sees an empty queue, so it always appends a fresh entry
+     * that survives independently of whether the downstream propagation succeeds
+     * or fails. Earlier "snapshot + clear-later" approaches lost same-path
+     * enqueues: the dedup check on enqueue saw the still-present snapshot entry
+     * and skipped, then `clear()` removed it.
+     */
+    drainStaleSummaryPaths(): Promise<string[]>;
+    /**
+     * Append the given file paths to the stale-summary queue, deduping by path.
+     * A path already in the queue keeps its original `enqueuedAt` timestamp so
+     * "how long has this been waiting?" telemetry stays meaningful.
+     *
+     * Serialized through {@link update} so concurrent enqueues from parallel
+     * curate tasks do not lose entries. Empty input is a no-op (no write).
+     */
+    enqueueStaleSummaryPaths(paths: string[]): Promise<void>;
     /**
      * Read-modify-write under a per-file mutex. Serializes concurrent increments
      * from parallel curate tasks within the same agent process so no updates are lost.

package/dist/server/infra/dream/dream-state-service.js

@@ -37,6 +37,57 @@ export class DreamStateService {
     constructor(opts) {
         this.stateFilePath = join(opts.baseDir, STATE_FILENAME);
     }
+    /**
+     * Atomic drain — reads the current queue and clears it in a single RMW,
+     * returning the deduped path list. The caller is responsible for retrying
+     * (re-enqueueing the returned snapshot) if the downstream work fails.
+     *
+     * Atomicity is the load-bearing property: any enqueue that runs after the
+     * drain returns sees an empty queue, so it always appends a fresh entry
+     * that survives independently of whether the downstream propagation succeeds
+     * or fails. Earlier "snapshot + clear-later" approaches lost same-path
+     * enqueues: the dedup check on enqueue saw the still-present snapshot entry
+     * and skipped, then `clear()` removed it.
+     */
+    async drainStaleSummaryPaths() {
+        let snapshot = [];
+        await this.update((state) => {
+            snapshot = state.staleSummaryPaths.map((e) => e.path);
+            if (snapshot.length === 0)
+                return state;
+            return { ...state, staleSummaryPaths: [] };
+        });
+        return snapshot;
+    }
+    /**
+     * Append the given file paths to the stale-summary queue, deduping by path.
+     * A path already in the queue keeps its original `enqueuedAt` timestamp so
+     * "how long has this been waiting?" telemetry stays meaningful.
+     *
+     * Serialized through {@link update} so concurrent enqueues from parallel
+     * curate tasks do not lose entries. Empty input is a no-op (no write).
+     */
+    async enqueueStaleSummaryPaths(paths) {
+        if (paths.length === 0)
+            return;
+        // Dedup the input itself before checking against the queue — callers may
+        // pass non-unique arrays (e.g. multiple changed paths within a single
+        // curate that round-trip through the same parent dir).
+        const incoming = [...new Set(paths)];
+        const enqueuedAt = Date.now();
+        await this.update((state) => {
+            const existing = new Set(state.staleSummaryPaths.map((e) => e.path));
+            const additions = incoming
+                .filter((p) => !existing.has(p))
+                .map((p) => ({ enqueuedAt, path: p }));
+            if (additions.length === 0)
+                return state;
+            return {
+                ...state,
+                staleSummaryPaths: [...state.staleSummaryPaths, ...additions],
+            };
+        });
+    }
     /**
      * Read-modify-write under a per-file mutex. Serializes concurrent increments
      * from parallel curate tasks within the same agent process so no updates are lost.
@@ -49,11 +100,11 @@ export class DreamStateService {
             const raw = await readFile(this.stateFilePath, 'utf8');
             const parsed = DreamStateSchema.safeParse(JSON.parse(raw));
             if (!parsed.success)
-                return { ...EMPTY_DREAM_STATE, pendingMerges: [] };
+                return { ...EMPTY_DREAM_STATE };
             return parsed.data;
         }
         catch {
-            return { ...EMPTY_DREAM_STATE, pendingMerges: [] };
+            return { ...EMPTY_DREAM_STATE };
         }
     }
     /**
@@ -68,7 +119,15 @@ export class DreamStateService {
         return mutex.withLock(async () => {
             const state = await this.read();
             const next = updater(state);
-            await this.write(next);
+            // Skip the write when the updater returned the same state reference.
+            // Existing call sites (drainStaleSummaryPaths on empty queue,
+            // enqueueStaleSummaryPaths with all-duplicate input) already follow
+            // this convention by returning `state` unchanged — making the no-op
+            // contract observable at the disk level avoids a tmpfile + rename on
+            // every empty drain.
+            if (next !== state) {
+                await this.write(next);
+            }
             return next;
         });
     }

package/dist/server/infra/dream/dream-trigger.js

@@ -48,8 +48,12 @@ export class DreamTrigger {
                 return { eligible: false, reason: `Too recent (${hoursSince.toFixed(1)}h < ${minHours}h)` };
             }
         }
-        // Gate 2: Activity
-        if (state.curationsSinceDream < minCurations) {
+        // Gate 2: Activity. Bypassed when the stale-summary queue has deferred
+        // work — leaving entries indefinitely strands `_index.md` regeneration
+        // in low-activity projects (the very projects ENG-2485 most affects,
+        // since 1–2 curates over a 12h window otherwise sit under minCurations
+        // forever). Dream is the canonical drain point; if it has work, run.
+        if (state.curationsSinceDream < minCurations && state.staleSummaryPaths.length === 0) {
             return {
                 eligible: false,
                 reason: `Not enough activity (${state.curationsSinceDream} < ${minCurations} curations)`,

package/dist/server/infra/executor/curate-executor.d.ts

@@ -69,4 +69,20 @@ export declare class CurateExecutor implements ICurateExecutor {
      * @throws {FileValidationError} If all files fail validation
      */
     private processFileReferences;
+    /**
+     * Phase 4: snapshot diff → enqueue stale paths for dream → rebuild manifest.
+     *
+     * Summary cascade regeneration (the LLM-driven `propagateStaleness` walk) is
+     * deferred to the next dream cycle to keep curate's hot path free of LLM
+     * calls. The manifest is rebuilt inline because it is a pure file scan (no
+     * LLM) and keeps newly-curated leaf files immediately discoverable via
+     * manifest-driven retrieval.
+     *
+     * Two independent fail-open concerns: (a) enqueue the deferred summary-cascade
+     * work to dream's queue; (b) rebuild the search manifest. They share
+     * `changedPaths` but otherwise are unrelated — a transient disk error on the
+     * dream-state write must not skip the pure-filesystem manifest scan. Each
+     * runs in its own try block so one failure cannot mask the other's work.
+     */
+    private propagateAndRebuild;
 }

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

@@ -1,10 +1,12 @@
 import path from 'node:path';
+import { recon as reconHelper } from '../../../agent/infra/sandbox/curation-helpers.js';
 import { BRV_DIR } from '../../constants.js';
 import { FileValidationError } from '../../core/domain/errors/task-error.js';
 import { createFileContentReader, } from '../../utils/file-content-reader.js';
 import { validateFileForCurate } from '../../utils/file-validator.js';
+import { FileContextTreeManifestService } from '../context-tree/file-context-tree-manifest-service.js';
 import { FileContextTreeSnapshotService } from '../context-tree/file-context-tree-snapshot-service.js';
-import { propagateSummariesUnderLock } from '../context-tree/propagate-summaries.js';
+import { diffStates } from '../context-tree/snapshot-diff.js';
 import { DreamStateService } from '../dream/dream-state-service.js';
 import { PreCompactionService } from './pre-compaction/pre-compaction-service.js';
 /**
@@ -94,12 +96,30 @@ export class CurateExecutor {
                 preview: effectiveContext.slice(0, 500),
                 type: 'string',
             };
-            // Inject context, metadata, empty history, and taskId into the TASK session's sandbox
+            // Pre-pipeline the recon step (deterministic helper) so the agent loop
+            // doesn't spend its first iteration calling tools.curation.recon. The
+            // result is injected as a sandbox variable for code-exec access AND
+            // its key findings are surfaced inline in the prompt so the agent's
+            // first iteration can proceed directly to extraction. recon is pure
+            // JS — no LLM judgment is needed for whether to call it; the answer
+            // is always "yes, first thing." Surfacing it as an agent-tool meant
+            // paying a full LLM iteration just to invoke a deterministic helper.
+            const initialHistory = { entries: [], totalProcessed: 0 };
+            // The `metadata` arg is currently unused by `recon` — the helper
+            // recomputes char/line/message counts from `effectiveContext`
+            // directly. Passed through here to match the helper's existing
+            // signature; do NOT assume changing `metadata` will alter
+            // `reconResult`.
+            const reconResult = reconHelper(effectiveContext, metadata, initialHistory);
+            const reconVar = `__recon_result_${taskIdSafe}`;
+            // Inject context, metadata, empty history, taskId, and pre-computed
+            // recon result into the TASK session's sandbox.
             const taskIdVar = `__taskId_${taskIdSafe}`;
             agent.setSandboxVariableOnSession(taskSessionId, ctxVar, effectiveContext);
-            agent.setSandboxVariableOnSession(taskSessionId, histVar, { entries: [], totalProcessed: 0 });
+            agent.setSandboxVariableOnSession(taskSessionId, histVar, initialHistory);
             agent.setSandboxVariableOnSession(taskSessionId, metaVar, metadata);
             agent.setSandboxVariableOnSession(taskSessionId, taskIdVar, taskId);
+            agent.setSandboxVariableOnSession(taskSessionId, reconVar, reconResult);
             // Prompt with curation helpers guidance (tools.curation.* replaces manual infrastructure code)
             const prompt = [
                 `Curate using RLM approach.`,
@@ -107,7 +127,8 @@ export class CurateExecutor {
                 `History variable: ${histVar}`,
                 `Metadata variable: ${metaVar}`,
                 `Task ID variable: ${taskIdVar} (pass as bare variable, not a string)`,
-                `IMPORTANT: Do NOT print raw context. Start with tools.curation.recon(${ctxVar}, ${metaVar}, ${histVar}) to assess.`,
+                `Recon already computed in ${reconVar}: suggestedMode=${reconResult.suggestedMode}, suggestedChunkCount=${reconResult.suggestedChunkCount}, charCount=${reconResult.meta.charCount}, lineCount=${reconResult.meta.lineCount}, messageCount=${reconResult.meta.messageCount}.`,
+                `IMPORTANT: Do NOT print raw context. Do NOT call tools.curation.recon — it has been pre-computed. Proceed directly to extraction.`,
                 `For chunked extraction use tools.curation.mapExtract(). Pass taskId: ${taskIdVar} (bare variable).`,
                 `IMPORTANT: Any code_exec call containing mapExtract MUST use timeout: 300000 on the code_exec tool call itself (not inside mapExtract options).`,
                 `Use tools.curation.groupBySubject() and tools.curation.dedup() to organize extractions.`,
@@ -129,7 +150,7 @@ export class CurateExecutor {
         }
         const finalize = async () => {
             try {
-                await propagateSummariesUnderLock({ agent, baseDir, preState, snapshotService, taskId });
+                await this.propagateAndRebuild({ baseDir, preState, snapshotService });
                 await this.incrementDreamCounter(baseDir);
                 await agent.drainBackgroundWork?.();
             }
@@ -273,4 +294,54 @@ export class CurateExecutor {
         // Format with actual content
         return this.formatFileContentsForPrompt(readResults, skippedFiles, projectRoot);
     }
+    /**
+     * Phase 4: snapshot diff → enqueue stale paths for dream → rebuild manifest.
+     *
+     * Summary cascade regeneration (the LLM-driven `propagateStaleness` walk) is
+     * deferred to the next dream cycle to keep curate's hot path free of LLM
+     * calls. The manifest is rebuilt inline because it is a pure file scan (no
+     * LLM) and keeps newly-curated leaf files immediately discoverable via
+     * manifest-driven retrieval.
+     *
+     * Two independent fail-open concerns: (a) enqueue the deferred summary-cascade
+     * work to dream's queue; (b) rebuild the search manifest. They share
+     * `changedPaths` but otherwise are unrelated — a transient disk error on the
+     * dream-state write must not skip the pure-filesystem manifest scan. Each
+     * runs in its own try block so one failure cannot mask the other's work.
+     */
+    async propagateAndRebuild(args) {
+        const { baseDir, preState, snapshotService } = args;
+        if (!preState)
+            return;
+        let changedPaths = [];
+        try {
+            const postState = await snapshotService.getCurrentState(baseDir);
+            changedPaths = diffStates(preState, postState);
+        }
+        catch {
+            // Fail-open: snapshot errors leave changedPaths empty → no enqueue,
+            // no manifest rebuild. Next curate's snapshot will pick up the diff.
+        }
+        if (changedPaths.length === 0)
+            return;
+        try {
+            const dreamStateService = new DreamStateService({ baseDir: path.join(baseDir, BRV_DIR) });
+            await dreamStateService.enqueueStaleSummaryPaths(changedPaths);
+        }
+        catch {
+            // Fail-open: queue write errors never block curation. If this write
+            // fails the changed paths are lost from the deferred queue; they will
+            // only be re-captured if the same files are modified in a later curate
+            // (diffStates compares a fresh pre/post snapshot pair, not a persistent
+            // accumulator) or picked up by dream's own snapshot diff if dream
+            // touches them.
+        }
+        try {
+            const manifestService = new FileContextTreeManifestService({ baseDirectory: baseDir });
+            await manifestService.buildManifest(baseDir);
+        }
+        catch {
+            // Fail-open: manifest rebuild is best-effort pre-warming.
+        }
+    }
 }