byterover-cli 3.5.1 → 3.6.0

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

@@ -0,0 +1,91 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { AsyncMutex } from '../../../agent/infra/llm/context/async-mutex.js';
+import { DreamStateSchema, EMPTY_DREAM_STATE } from './dream-state-schema.js';
+const STATE_FILENAME = 'dream-state.json';
+// Module-level mutex registry keyed by absolute state file path.
+// The agent process can hold up to AGENT_MAX_CONCURRENT_TASKS concurrent curate tasks
+// AND a dream task running concurrently, so read-modify-write on dream-state.json must
+// be serialized across all writers — incrementCurationCount, dream-executor's step 7
+// reset, and consolidate's pendingMerges clear all share this mutex via update().
+// Independent DreamStateService instances pointing at the same file share a mutex.
+//
+// Note: this Map grows monotonically — one entry per unique absolute state-file
+// path ever instantiated. In practice it is bounded by the number of registered
+// projects in the agent process (typically single digits), so memory growth is
+// negligible. If the daemon ever needs to support project unregister, evict
+// entries here on unregister to keep the registry tight.
+const stateMutexes = new Map();
+function getStateMutex(stateFilePath) {
+    const key = resolve(stateFilePath);
+    let mutex = stateMutexes.get(key);
+    if (!mutex) {
+        mutex = new AsyncMutex();
+        stateMutexes.set(key, mutex);
+    }
+    return mutex;
+}
+/**
+ * File-based persistence for dream state.
+ *
+ * Reads return EMPTY_DREAM_STATE on missing/corrupt files (fail-open).
+ * Writes are atomic (tmp → rename) and validate with Zod before persisting.
+ */
+export class DreamStateService {
+    stateFilePath;
+    constructor(opts) {
+        this.stateFilePath = join(opts.baseDir, STATE_FILENAME);
+    }
+    /**
+     * 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.
+     */
+    async incrementCurationCount() {
+        await this.update((state) => ({ ...state, curationsSinceDream: state.curationsSinceDream + 1 }));
+    }
+    async read() {
+        try {
+            const raw = await readFile(this.stateFilePath, 'utf8');
+            const parsed = DreamStateSchema.safeParse(JSON.parse(raw));
+            if (!parsed.success)
+                return { ...EMPTY_DREAM_STATE, pendingMerges: [] };
+            return parsed.data;
+        }
+        catch {
+            return { ...EMPTY_DREAM_STATE, pendingMerges: [] };
+        }
+    }
+    /**
+     * Generic read-modify-write under the same per-file mutex used by
+     * incrementCurationCount. All writers that mutate dream-state.json based on
+     * its current contents (e.g. dream-executor step 7's reset, consolidate's
+     * pendingMerges clear) MUST go through this method, otherwise concurrent
+     * increments can be silently overwritten.
+     */
+    async update(updater) {
+        const mutex = getStateMutex(this.stateFilePath);
+        return mutex.withLock(async () => {
+            const state = await this.read();
+            const next = updater(state);
+            await this.write(next);
+            return next;
+        });
+    }
+    /**
+     * Atomic write (tmp file → rename). Does NOT acquire the per-file mutex.
+     *
+     * Direct callers that perform a logical read-modify-write by pairing
+     * {@link read} + write bypass serialization and may lose updates from
+     * concurrent writers. Use {@link update} for any RMW that depends on the
+     * current state.
+     */
+    async write(state) {
+        DreamStateSchema.parse(state);
+        const dir = dirname(this.stateFilePath);
+        await mkdir(dir, { recursive: true });
+        const tmpPath = `${this.stateFilePath}.${randomUUID()}.tmp`;
+        await writeFile(tmpPath, JSON.stringify(state, null, 2), 'utf8');
+        await rename(tmpPath, this.stateFilePath);
+    }
+}

package/dist/server/infra/dream/dream-trigger.d.ts

@@ -0,0 +1,46 @@
+import type { DreamLockService } from './dream-lock-service.js';
+import type { DreamStateService } from './dream-state-service.js';
+type DreamTriggerDeps = {
+    dreamLockService: Pick<DreamLockService, 'tryAcquire'>;
+    dreamStateService: Pick<DreamStateService, 'read'>;
+    getQueueLength: (projectPath: string) => number;
+};
+type DreamTriggerOptions = {
+    minCurations?: number;
+    minHours?: number;
+};
+export type DreamEligibility = {
+    eligible: false;
+    reason: string;
+} | {
+    eligible: true;
+    priorMtime: number;
+};
+type PreCheckResult = {
+    eligible: false;
+    reason: string;
+} | {
+    eligible: true;
+};
+/**
+ * Four-gate trigger for dream eligibility.
+ *
+ * Gates 1-3 (time, activity, queue) are skipped with force=true.
+ * Gate 4 (lock) always runs — prevents concurrent dreams.
+ */
+export declare class DreamTrigger {
+    private readonly deps;
+    private readonly options;
+    constructor(deps: DreamTriggerDeps, options?: DreamTriggerOptions);
+    /**
+     * Lightweight eligibility pre-check (gates 1-3 only, no lock).
+     *
+     * Used by the daemon to decide whether to dispatch a dream task
+     * without acquiring the PID-based lock (which must be acquired
+     * by the agent process that actually runs the dream).
+     */
+    checkEligibility(projectPath: string): Promise<PreCheckResult>;
+    tryStartDream(projectPath: string, force?: boolean): Promise<DreamEligibility>;
+    private checkGates1to3;
+}
+export {};

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

@@ -0,0 +1,65 @@
+const DEFAULT_MIN_HOURS = 12;
+const DEFAULT_MIN_CURATIONS = 3;
+/**
+ * Four-gate trigger for dream eligibility.
+ *
+ * Gates 1-3 (time, activity, queue) are skipped with force=true.
+ * Gate 4 (lock) always runs — prevents concurrent dreams.
+ */
+export class DreamTrigger {
+    deps;
+    options;
+    constructor(deps, options = {}) {
+        this.deps = deps;
+        this.options = options;
+    }
+    /**
+     * Lightweight eligibility pre-check (gates 1-3 only, no lock).
+     *
+     * Used by the daemon to decide whether to dispatch a dream task
+     * without acquiring the PID-based lock (which must be acquired
+     * by the agent process that actually runs the dream).
+     */
+    async checkEligibility(projectPath) {
+        return this.checkGates1to3(projectPath);
+    }
+    async tryStartDream(projectPath, force = false) {
+        if (!force) {
+            const preCheck = await this.checkGates1to3(projectPath);
+            if (!preCheck.eligible)
+                return preCheck;
+        }
+        // Gate 4: Lock (NEVER skipped, even with force)
+        const lockResult = await this.deps.dreamLockService.tryAcquire();
+        if (!lockResult.acquired) {
+            return { eligible: false, reason: 'Lock held by another dream process' };
+        }
+        return { eligible: true, priorMtime: lockResult.priorMtime };
+    }
+    async checkGates1to3(projectPath) {
+        const minHours = this.options.minHours ?? DEFAULT_MIN_HOURS;
+        const minCurations = this.options.minCurations ?? DEFAULT_MIN_CURATIONS;
+        // Gates 1+2: time and activity (share one file read)
+        const state = await this.deps.dreamStateService.read();
+        // Gate 1: Time
+        if (state.lastDreamAt !== null) {
+            const hoursSince = (Date.now() - new Date(state.lastDreamAt).getTime()) / (1000 * 60 * 60);
+            if (hoursSince < minHours) {
+                return { eligible: false, reason: `Too recent (${hoursSince.toFixed(1)}h < ${minHours}h)` };
+            }
+        }
+        // Gate 2: Activity
+        if (state.curationsSinceDream < minCurations) {
+            return {
+                eligible: false,
+                reason: `Not enough activity (${state.curationsSinceDream} < ${minCurations} curations)`,
+            };
+        }
+        // Gate 3: Queue
+        const queueLength = this.deps.getQueueLength(projectPath);
+        if (queueLength > 0) {
+            return { eligible: false, reason: `Queue not empty (${queueLength} tasks pending)` };
+        }
+        return { eligible: true };
+    }
+}

package/dist/server/infra/dream/dream-undo.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Dream Undo — reverts the last dream's file changes using previousTexts from the dream log.
+ *
+ * Runs directly from CLI (no daemon/agent needed). Pure file I/O.
+ * Only undoes the LAST dream — not a history stack.
+ */
+import type { ICurateLogStore } from '../../core/interfaces/storage/i-curate-log-store.js';
+import type { IReviewBackupStore } from '../../core/interfaces/storage/i-review-backup-store.js';
+import type { DreamLogEntry } from './dream-log-schema.js';
+import type { DreamState } from './dream-state-schema.js';
+export type DreamUndoDeps = {
+    archiveService?: {
+        restoreEntry(stubPath: string, directory?: string): Promise<string>;
+    };
+    contextTreeDir: string;
+    curateLogStore?: Pick<ICurateLogStore, 'batchUpdateOperationReviewStatus' | 'list'>;
+    dreamLogStore: {
+        getById(id: string): Promise<DreamLogEntry | null>;
+        save(entry: DreamLogEntry): Promise<void>;
+    };
+    dreamStateService: {
+        read(): Promise<DreamState>;
+        write(state: DreamState): Promise<void>;
+    };
+    manifestService: {
+        buildManifest(dir?: string): Promise<unknown>;
+    };
+    projectRoot?: string;
+    reviewBackupStore?: Pick<IReviewBackupStore, 'delete'>;
+};
+export type DreamUndoResult = {
+    deletedFiles: string[];
+    dreamId: string;
+    errors: string[];
+    restoredArchives: string[];
+    restoredFiles: string[];
+};
+export declare function undoLastDream(deps: DreamUndoDeps): Promise<DreamUndoResult>;

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

@@ -0,0 +1,293 @@
+/**
+ * Dream Undo — reverts the last dream's file changes using previousTexts from the dream log.
+ *
+ * Runs directly from CLI (no daemon/agent needed). Pure file I/O.
+ * Only undoes the LAST dream — not a history stack.
+ */
+import { mkdir, unlink, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { isDescendantOf } from '../../utils/path-utils.js';
+export async function undoLastDream(deps) {
+    const { contextTreeDir, dreamLogStore, dreamStateService, manifestService } = deps;
+    // ── Precondition checks ─────────────────────────────────────────────────
+    const state = await dreamStateService.read();
+    if (!state.lastDreamLogId) {
+        throw new Error('No dream to undo');
+    }
+    const log = await dreamLogStore.getById(state.lastDreamLogId);
+    if (!log) {
+        throw new Error(`Dream log not found: ${state.lastDreamLogId}`);
+    }
+    if (log.status === 'undone') {
+        throw new Error(`Dream already undone: ${state.lastDreamLogId}`);
+    }
+    if (log.status !== 'completed' && log.status !== 'partial') {
+        throw new Error(`Cannot undo dream with status: ${log.status}`);
+    }
+    // ── Reverse operations ──────────────────────────────────────────────────
+    const result = {
+        deletedFiles: [],
+        dreamId: log.id,
+        errors: [],
+        restoredArchives: [],
+        restoredFiles: [],
+    };
+    // Track pending merges to remove (for PRUNE/SUGGEST_MERGE)
+    const mergesToRemove = [];
+    const reversed = [...log.operations].reverse();
+    for (const op of reversed) {
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            await undoOperation(op, { contextTreeDir, deps, mergesToRemove, result });
+        }
+        catch (error) {
+            result.errors.push(error instanceof Error ? error.message : String(error));
+        }
+    }
+    // ── Post-undo: clean up review entries and backups ──────────────────────
+    await cleanupReviewEntries(log, deps);
+    // ── Post-undo: rebuild manifest ─────────────────────────────────────────
+    try {
+        await manifestService.buildManifest();
+    }
+    catch (error) {
+        result.errors.push(`Manifest rebuild failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // ── Post-undo: mark log as undone ───────────────────────────────────────
+    const undoneLog = {
+        completedAt: log.completedAt,
+        id: log.id,
+        operations: log.operations,
+        startedAt: log.startedAt,
+        status: 'undone',
+        summary: log.summary,
+        taskId: log.taskId,
+        trigger: log.trigger,
+        undoneAt: Date.now(),
+    };
+    await dreamLogStore.save(undoneLog);
+    // ── Post-undo: rewind dream state ───────────────────────────────────────
+    let { pendingMerges } = state;
+    if (mergesToRemove.length > 0) {
+        pendingMerges = (pendingMerges ?? []).filter((pm) => !mergesToRemove.some((rm) => rm.sourceFile === pm.sourceFile && rm.mergeTarget === pm.mergeTarget));
+    }
+    // Undo runs in the CLI process. The in-process mutex guarding
+    // update() lives in the daemon, so using update() here wouldn't
+    // synchronize with a concurrent daemon-side incrementCurationCount anyway —
+    // write() is acceptable. If daemon-side undo is ever added, switch to
+    // update() to serialize with other writers in that process.
+    await dreamStateService.write({
+        ...state,
+        lastDreamAt: null,
+        pendingMerges,
+        totalDreams: Math.max(0, state.totalDreams - 1),
+    });
+    return result;
+}
+/** Unlink a file, ignoring ENOENT (already gone) but rethrowing other errors. */
+async function unlinkSafe(filePath) {
+    try {
+        await unlink(filePath);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}
+/** Resolve a relative path within contextTreeDir, rejecting traversal outside the tree. */
+function safePath(contextTreeDir, relativePath) {
+    const full = resolve(contextTreeDir, relativePath);
+    if (!isDescendantOf(full, contextTreeDir)) {
+        throw new Error(`Path traversal blocked: ${relativePath}`);
+    }
+    return full;
+}
+async function undoOperation(op, ctx) {
+    switch (op.type) {
+        case 'CONSOLIDATE': {
+            await undoConsolidate(op, ctx.contextTreeDir, ctx.result);
+            break;
+        }
+        case 'PRUNE': {
+            await undoPrune(op, ctx);
+            break;
+        }
+        case 'SYNTHESIZE': {
+            await undoSynthesize(op, ctx.contextTreeDir, ctx.result);
+            break;
+        }
+    }
+}
+async function undoConsolidate(op, contextTreeDir, result) {
+    switch (op.action) {
+        case 'CROSS_REFERENCE': {
+            if (!op.previousTexts || Object.keys(op.previousTexts).length === 0)
+                break;
+            for (const [filePath, content] of Object.entries(op.previousTexts)) {
+                const fullPath = safePath(contextTreeDir, filePath);
+                // eslint-disable-next-line no-await-in-loop
+                await mkdir(dirname(fullPath), { recursive: true });
+                // eslint-disable-next-line no-await-in-loop
+                await writeFile(fullPath, content, 'utf8');
+                result.restoredFiles.push(filePath);
+            }
+            break;
+        }
+        case 'MERGE': {
+            if (!op.previousTexts || Object.keys(op.previousTexts).length === 0) {
+                throw new Error(`Cannot undo MERGE: missing previousTexts for ${op.outputFile ?? op.inputFiles[0]}`);
+            }
+            // Restore all source files from previousTexts
+            for (const [filePath, content] of Object.entries(op.previousTexts)) {
+                const fullPath = safePath(contextTreeDir, filePath);
+                // eslint-disable-next-line no-await-in-loop
+                await mkdir(dirname(fullPath), { recursive: true });
+                // eslint-disable-next-line no-await-in-loop
+                await writeFile(fullPath, content, 'utf8');
+                result.restoredFiles.push(filePath);
+            }
+            // Delete merged output if it wasn't an original source
+            if (op.outputFile && !op.previousTexts[op.outputFile]) {
+                await unlinkSafe(safePath(contextTreeDir, op.outputFile));
+                result.deletedFiles.push(op.outputFile);
+            }
+            break;
+        }
+        case 'TEMPORAL_UPDATE': {
+            if (!op.previousTexts || Object.keys(op.previousTexts).length === 0) {
+                throw new Error(`Cannot undo TEMPORAL_UPDATE: missing previousTexts for ${op.inputFiles[0]}`);
+            }
+            for (const [filePath, content] of Object.entries(op.previousTexts)) {
+                const fullPath = safePath(contextTreeDir, filePath);
+                // eslint-disable-next-line no-await-in-loop
+                await mkdir(dirname(fullPath), { recursive: true });
+                // eslint-disable-next-line no-await-in-loop
+                await writeFile(fullPath, content, 'utf8');
+                result.restoredFiles.push(filePath);
+            }
+            break;
+        }
+    }
+}
+async function undoSynthesize(op, contextTreeDir, result) {
+    // UPDATE modified a pre-existing file — can't undo without previousTexts (not captured by SYNTHESIZE)
+    if (op.action === 'UPDATE') {
+        throw new Error(`Cannot undo SYNTHESIZE/UPDATE: previousTexts not captured for ${op.outputFile}`);
+    }
+    // CREATE — delete the synthesized file
+    await unlinkSafe(safePath(contextTreeDir, op.outputFile));
+    result.deletedFiles.push(op.outputFile);
+}
+function reviewTargetKey(target) {
+    return `${target.type}:${target.path}`;
+}
+function collectReviewTargets(operations) {
+    const targets = [];
+    for (const op of operations) {
+        if (!op.needsReview)
+            continue;
+        if (op.type === 'PRUNE' && op.action === 'ARCHIVE') {
+            targets.push({ path: op.file, type: 'DELETE' });
+            continue;
+        }
+        if (op.type === 'CONSOLIDATE' && op.action === 'MERGE') {
+            targets.push({ path: op.outputFile ?? op.inputFiles[0], type: 'MERGE' });
+            continue;
+        }
+        if (op.type === 'CONSOLIDATE') {
+            targets.push({ path: op.inputFiles[0], type: 'UPDATE' });
+            continue;
+        }
+        if (op.type === 'SYNTHESIZE') {
+            targets.push({ path: op.outputFile, type: op.action === 'CREATE' ? 'ADD' : 'UPDATE' });
+        }
+    }
+    return targets;
+}
+function buildReviewStatusUpdates(entry) {
+    return entry.operations
+        .map((op, operationIndex) => op.reviewStatus && op.reviewStatus !== 'rejected'
+        ? { operationIndex, reviewStatus: 'rejected' }
+        : null)
+        .filter((update) => update !== null);
+}
+function matchLegacyDreamReviewEntry(entries, operations) {
+    const expected = collectReviewTargets(operations).map((target) => reviewTargetKey(target)).sort();
+    if (expected.length === 0)
+        return [];
+    const matches = entries.filter((entry) => {
+        const actual = entry.operations.map((op) => reviewTargetKey({ path: op.path, type: op.type })).sort();
+        return actual.length === expected.length && actual.every((value, index) => value === expected[index]);
+    });
+    return matches.length === 1 ? matches : [];
+}
+async function cleanupReviewEntries(log, deps) {
+    const hasReviewOps = log.operations.some((op) => op.needsReview);
+    // Mark curate log entries from dream as rejected.
+    // Runs whenever the dream had any needsReview ops — even if previousTexts is absent
+    // (e.g. legacy CROSS_REFERENCE entries), so the pending review task is always cleaned up.
+    if (deps.curateLogStore && hasReviewOps) {
+        try {
+            const entries = await deps.curateLogStore.list({ status: ['completed'] });
+            const dreamEntries = entries.filter((entry) => entry.input.context === 'dream');
+            const matchedEntries = log.taskId
+                ? dreamEntries.filter((entry) => entry.taskId === log.taskId)
+                : matchLegacyDreamReviewEntry(dreamEntries, log.operations);
+            for (const entry of matchedEntries) {
+                const updates = buildReviewStatusUpdates(entry);
+                if (updates.length === 0)
+                    continue;
+                // eslint-disable-next-line no-await-in-loop
+                await deps.curateLogStore.batchUpdateOperationReviewStatus(entry.id, updates);
+            }
+        }
+        catch {
+            // Fail-open: review cleanup must not block undo
+        }
+    }
+    // Delete review backups for affected files (collected from previousTexts keys,
+    // which mirror what the backup store received during the dream).
+    if (deps.reviewBackupStore) {
+        const reviewFilePaths = new Set();
+        for (const op of log.operations) {
+            if (!op.needsReview)
+                continue;
+            if (op.type === 'PRUNE')
+                reviewFilePaths.add(op.file);
+            if (op.type === 'CONSOLIDATE' && op.previousTexts) {
+                for (const file of Object.keys(op.previousTexts))
+                    reviewFilePaths.add(file);
+            }
+            if (op.type === 'SYNTHESIZE')
+                reviewFilePaths.add(op.outputFile);
+        }
+        if (reviewFilePaths.size > 0) {
+            await Promise.all([...reviewFilePaths].map((file) => deps.reviewBackupStore.delete(file).catch(() => { })));
+        }
+    }
+}
+async function undoPrune(op, ctx) {
+    switch (op.action) {
+        case 'ARCHIVE': {
+            if (!ctx.deps.archiveService) {
+                throw new Error(`Cannot undo PRUNE/ARCHIVE: no archive service available for ${op.file}`);
+            }
+            if (!op.stubPath) {
+                throw new Error(`Cannot undo PRUNE/ARCHIVE: missing stubPath for ${op.file}`);
+            }
+            const restored = await ctx.deps.archiveService.restoreEntry(op.stubPath, ctx.deps.projectRoot);
+            ctx.result.restoredArchives.push(restored);
+            break;
+        }
+        case 'KEEP': {
+            // No-op — nothing was changed
+            break;
+        }
+        case 'SUGGEST_MERGE': {
+            if (op.mergeTarget) {
+                ctx.mergesToRemove.push({ mergeTarget: op.mergeTarget, sourceFile: op.file });
+            }
+            break;
+        }
+    }
+}

package/dist/server/infra/dream/operations/consolidate.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Consolidate operation — merges, updates, and cross-references related context tree files.
+ *
+ * Flow:
+ * 1. Group changed files by domain (first path segment)
+ * 2. Per domain: find related files via BM25 search + path siblings
+ * 3. Per domain: LLM classifies file relationships → returns actions
+ * 4. Execute actions: MERGE (combine + delete source), TEMPORAL_UPDATE (rewrite),
+ *    CROSS_REFERENCE (add related links in frontmatter), SKIP (no-op)
+ *
+ * Never throws — returns partial results on errors.
+ */
+import type { ICipherAgent } from '../../../../agent/core/interfaces/i-cipher-agent.js';
+import type { DreamOperation } from '../dream-log-schema.js';
+import type { DreamState } from '../dream-state-schema.js';
+export type ConsolidateDeps = {
+    agent: ICipherAgent;
+    contextTreeDir: string;
+    /**
+     * Optional. When present, pendingMerges from prior dreams (written by prune's
+     * SUGGEST_MERGE) are consumed at the start of consolidate: source files are
+     * added to changedFiles, their target/reason is passed to the LLM as a hint,
+     * and the pendingMerges list is cleared.
+     */
+    dreamStateService?: {
+        read(): Promise<DreamState>;
+        update(updater: (state: DreamState) => DreamState): Promise<DreamState>;
+        write(state: DreamState): Promise<void>;
+    };
+    reviewBackupStore?: {
+        save(relativePath: string, content: string): Promise<void>;
+    };
+    searchService: {
+        search(query: string, options?: {
+            limit?: number;
+            scope?: string;
+        }): Promise<{
+            results: Array<{
+                path: string;
+                score: number;
+                title: string;
+            }>;
+        }>;
+    };
+    signal?: AbortSignal;
+    taskId: string;
+};
+/**
+ * Run the consolidation operation on changed files.
+ * Returns DreamOperation results (never throws).
+ */
+export declare function consolidate(changedFiles: string[], deps: ConsolidateDeps): Promise<DreamOperation[]>;