byterover-cli 3.10.0 → 3.10.2

package/dist/server/core/domain/entities/brv-config.js

@@ -50,6 +50,8 @@ const isBrvConfigJson = (json) => {
         return false;
     if (obj.version !== undefined && typeof obj.version !== 'string')
         return false;
+    if (obj.reviewDisabled !== undefined && typeof obj.reviewDisabled !== 'boolean')
+        return false;
     return true;
 };
 /**
@@ -64,6 +66,7 @@ export class BrvConfig {
     createdAt;
     cwd;
     ide;
+    reviewDisabled;
     spaceId;
     spaceName;
     teamId;
@@ -80,6 +83,7 @@ export class BrvConfig {
         this.createdAt = params.createdAt;
         this.cwd = params.cwd;
         this.ide = params.ide;
+        this.reviewDisabled = params.reviewDisabled;
         this.spaceId = params.spaceId;
         this.spaceName = params.spaceName;
         this.teamId = params.teamId;
@@ -163,6 +167,7 @@ export class BrvConfig {
             createdAt: this.createdAt,
             cwd: this.cwd,
             ide: this.ide,
+            reviewDisabled: this.reviewDisabled,
             spaceId: this.spaceId,
             spaceName: this.spaceName,
             teamId: this.teamId,
@@ -182,6 +187,26 @@ export class BrvConfig {
             teamName: undefined,
         });
     }
+    /**
+     * Creates a new BrvConfig with the reviewDisabled flag updated, preserving all other fields.
+     */
+    withReviewDisabled(reviewDisabled) {
+        return new BrvConfig({
+            chatLogPath: this.chatLogPath,
+            cipherAgentContext: this.cipherAgentContext,
+            cipherAgentModes: this.cipherAgentModes,
+            cipherAgentSystemPrompt: this.cipherAgentSystemPrompt,
+            createdAt: this.createdAt,
+            cwd: this.cwd,
+            ide: this.ide,
+            reviewDisabled,
+            spaceId: this.spaceId,
+            spaceName: this.spaceName,
+            teamId: this.teamId,
+            teamName: this.teamName,
+            version: this.version,
+        });
+    }
     /**
      * Creates a new BrvConfig with space fields replaced, preserving all other fields.
      */
@@ -194,6 +219,7 @@ export class BrvConfig {
             createdAt: new Date().toISOString(),
             cwd: this.cwd,
             ide: this.ide,
+            reviewDisabled: this.reviewDisabled,
             spaceId: space.id,
             spaceName: space.name,
             teamId: space.teamId,
@@ -213,6 +239,7 @@ export class BrvConfig {
             createdAt: this.createdAt,
             cwd: this.cwd,
             ide: this.ide,
+            reviewDisabled: this.reviewDisabled,
             spaceId: this.spaceId,
             spaceName: this.spaceName,
             teamId: this.teamId,

package/dist/server/core/domain/entities/provider-registry.js

@@ -186,7 +186,6 @@ export const PROVIDER_REGISTRY = {
     'openai-compatible': {
         baseUrl: '',
         category: 'other',
-        defaultModel: 'llama3',
         description: 'OpenAI-compatible endpoint (Ollama, LM Studio, etc.)',
         envVars: ['OPENAI_COMPATIBLE_API_KEY'],
         headers: {},

package/dist/server/core/domain/transport/schemas.d.ts

@@ -515,6 +515,12 @@ export declare const TaskExecuteSchema: z.ZodObject<{
     force: z.ZodOptional<z.ZodBoolean>;
     /** Project path this task belongs to (for multi-project routing) */
     projectPath: z.ZodOptional<z.ZodString>;
+    /**
+     * Snapshot of the project's review-disabled flag captured at task-create time.
+     * Stamped by the daemon so the agent does not re-read .brv/config.json and
+     * race with mid-task toggles.
+     */
+    reviewDisabled: z.ZodOptional<z.ZodBoolean>;
     /** Unique task identifier */
     taskId: z.ZodString;
     /** Dream trigger source — how this dream was initiated */
@@ -530,6 +536,7 @@ export declare const TaskExecuteSchema: z.ZodObject<{
     clientId: string;
     files?: string[] | undefined;
     force?: boolean | undefined;
+    reviewDisabled?: boolean | undefined;
     clientCwd?: string | undefined;
     folderPath?: string | undefined;
     projectPath?: string | undefined;
@@ -542,6 +549,7 @@ export declare const TaskExecuteSchema: z.ZodObject<{
     clientId: string;
     files?: string[] | undefined;
     force?: boolean | undefined;
+    reviewDisabled?: boolean | undefined;
     clientCwd?: string | undefined;
     folderPath?: string | undefined;
     projectPath?: string | undefined;

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

@@ -318,6 +318,12 @@ export const TaskExecuteSchema = z.object({
     force: z.boolean().optional(),
     /** Project path this task belongs to (for multi-project routing) */
     projectPath: z.string().optional(),
+    /**
+     * Snapshot of the project's review-disabled flag captured at task-create time.
+     * Stamped by the daemon so the agent does not re-read .brv/config.json and
+     * race with mid-task toggles.
+     */
+    reviewDisabled: z.boolean().optional(),
     /** Unique task identifier */
     taskId: z.string(),
     /** Dream trigger source — how this dream was initiated */

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

@@ -22,6 +22,13 @@ export type TaskInfo = {
     projectPath?: string;
     /** Set on successful completion */
     result?: string;
+    /**
+     * Snapshot of the project's review-disabled flag captured at task-create time.
+     * Stamped once at the daemon boundary so daemon (CurateLogHandler) and agent
+     * (curate-tool backups, dream review entries) observe the same value even if
+     * the user toggles the flag mid-task.
+     */
+    reviewDisabled?: boolean;
     /** Set when agent picks up the task */
     startedAt?: number;
     /** Lifecycle status — defaults to 'created' on construction */

package/dist/server/core/interfaces/i-provider-config-store.d.ts

@@ -8,13 +8,17 @@ export interface IProviderConfigStore {
      * Marks a provider as connected.
      *
      * @param providerId The provider ID to mark as connected
-     * @param options Optional settings like default model
+     * @param options Optional settings like default model. Pass `setAsActive: false`
+     *   to skip flipping the active provider (used when the provider has no
+     *   active model yet — activating it would put the app in a half-configured
+     *   state that the welcome view interprets as "needs setup").
      */
     connectProvider: (providerId: string, options?: {
         activeModel?: string;
         authMethod?: 'api-key' | 'oauth';
         baseUrl?: string;
         oauthAccountId?: string;
+        setAsActive?: boolean;
     }) => Promise<void>;
     /**
      * Removes a provider connection.

package/dist/server/infra/context-tree/propagate-summaries.d.ts

@@ -0,0 +1,18 @@
+import type { ICipherAgent } from '../../../agent/core/interfaces/i-cipher-agent.js';
+import type { FileState } from '../../core/domain/entities/context-tree-snapshot.js';
+import type { FileContextTreeSnapshotService } from './file-context-tree-snapshot-service.js';
+export type PropagateSummariesUnderLockOptions = {
+    agent: ICipherAgent;
+    baseDir: string;
+    preState: Map<string, FileState> | undefined;
+    snapshotService: FileContextTreeSnapshotService;
+    taskId: string;
+};
+/**
+ * Phase 4 write block shared by curate and folder-pack post-work: snapshot
+ * diff → `propagateStaleness` → opportunistic manifest rebuild. Holds the
+ * dream lock around the writes so a concurrent dream cannot interleave on
+ * `_index.md` / `_manifest.json`; if the lock is held, this skips because
+ * dream's own propagation covers the same diff. Fail-open.
+ */
+export declare function propagateSummariesUnderLock(options: PropagateSummariesUnderLockOptions): Promise<void>;

package/dist/server/infra/context-tree/propagate-summaries.js

@@ -0,0 +1,52 @@
+import path from 'node:path';
+import { BRV_DIR } from '../../constants.js';
+import { DreamLockService } from '../dream/dream-lock-service.js';
+import { FileContextTreeManifestService } from './file-context-tree-manifest-service.js';
+import { FileContextTreeSummaryService } from './file-context-tree-summary-service.js';
+import { diffStates } from './snapshot-diff.js';
+/**
+ * Phase 4 write block shared by curate and folder-pack post-work: snapshot
+ * diff → `propagateStaleness` → opportunistic manifest rebuild. Holds the
+ * dream lock around the writes so a concurrent dream cannot interleave on
+ * `_index.md` / `_manifest.json`; if the lock is held, this skips because
+ * dream's own propagation covers the same diff. Fail-open.
+ */
+export async function propagateSummariesUnderLock(options) {
+    const { agent, baseDir, preState, snapshotService, taskId } = options;
+    if (!preState)
+        return;
+    const dreamLockService = new DreamLockService({ baseDir: path.join(baseDir, BRV_DIR) });
+    let acquireResult;
+    try {
+        acquireResult = await dreamLockService.tryAcquire();
+    }
+    catch {
+        return;
+    }
+    if (!acquireResult.acquired)
+        return;
+    let succeeded = false;
+    try {
+        const postState = await snapshotService.getCurrentState(baseDir);
+        const changedPaths = diffStates(preState, postState);
+        if (changedPaths.length === 0) {
+            succeeded = true;
+            return;
+        }
+        const summaryService = new FileContextTreeSummaryService();
+        const results = await summaryService.propagateStaleness(changedPaths, agent, baseDir, taskId);
+        if (results.some((result) => result.actionTaken)) {
+            const manifestService = new FileContextTreeManifestService({ baseDirectory: baseDir });
+            await manifestService.buildManifest(baseDir);
+        }
+        succeeded = true;
+    }
+    catch {
+        // Fail-open: summary/manifest errors never block the caller.
+    }
+    finally {
+        await (succeeded
+            ? dreamLockService.release()
+            : dreamLockService.rollback(acquireResult.priorMtime)).catch(() => { });
+    }
+}

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

@@ -28,6 +28,7 @@ import { FileSystemService } from '../../../agent/infra/file-system/file-system-
 import { FolderPackService } from '../../../agent/infra/folder-pack/folder-pack-service.js';
 import { SessionMetadataStore } from '../../../agent/infra/session/session-metadata-store.js';
 import { FileKeyStorage } from '../../../agent/infra/storage/file-key-storage.js';
+import { runWithReviewDisabled } from '../../../agent/infra/tools/implementations/curate-tool-task-context.js';
 import { createSearchKnowledgeService } from '../../../agent/infra/tools/implementations/search-knowledge-service.js';
 import { AuthEvents } from '../../../shared/transport/events/auth-events.js';
 import { decodeSearchContent } from '../../../shared/transport/search-content.js';
@@ -51,6 +52,7 @@ import { FileCurateLogStore } from '../storage/file-curate-log-store.js';
 import { FileReviewBackupStore } from '../storage/file-review-backup-store.js';
 import { AgentInstanceDiscovery } from '../transport/agent-instance-discovery.js';
 import { createAgentLogger } from './agent-logger.js';
+import { PostWorkRegistry } from './post-work-registry.js';
 import { resolveSessionId } from './session-resolver.js';
 import { validateProviderForTask } from './task-validation.js';
 // ============================================================================
@@ -73,6 +75,15 @@ if (!portEnv || !projectPathEnv) {
 const port = portEnv;
 const projectPath = projectPathEnv;
 const agentLog = createAgentLogger(process.env.BRV_SESSION_LOG, `[agent-process:${projectPath}]`);
+/**
+ * Holds detached post-curate work so `task:completed` can fire as soon as
+ * the agent body finishes. Drained on shutdown to avoid truncated writes.
+ */
+const postWorkRegistry = new PostWorkRegistry({
+    onError(_projectPath, error) {
+        agentLog(`post-work error: ${error instanceof Error ? error.message : String(error)}`);
+    },
+});
 /**
  * Persist a brand-new session's metadata and set it as active.
  * Best-effort — failures are logged but never block the caller.
@@ -345,7 +356,7 @@ async function start() {
     agentLog('Ready — listening for tasks');
 }
 async function executeTask(task, curateExecutor, folderPackExecutor, queryExecutor, searchExecutor, searchKnowledgeService, storagePath, runtimeSignalStore) {
-    const { clientCwd, clientId, content, files, folderPath, force, taskId, trigger, type, worktreeRoot } = task;
+    const { clientCwd, clientId, content, files, folderPath, force, reviewDisabled, taskId, trigger, type, worktreeRoot } = task;
     if (!transport || !agent)
         return;
     // Search tasks are pure BM25 retrieval — no LLM, no provider needed.
@@ -359,7 +370,19 @@ async function executeTask(task, curateExecutor, folderPackExecutor, queryExecut
         }
     }
     activeTaskCount++;
-    try {
+    // Body of the task — extracted so the daemon-stamped reviewDisabled snapshot can be
+    // opened as an AsyncLocalStorage scope around it. Tools that run inside this task
+    // (curate-tool.executeCurate, including the sandbox `tools.curate(...)` path via
+    // CurateService where _context.taskId is not threaded through) read the snapshot
+    // from the ALS scope instead of re-reading .brv/config.json — that read can race
+    // with mid-task user toggles, which is exactly the inconsistency we are eliminating.
+    // We only open the scope when the daemon stamped a value; otherwise consumers fall
+    // back to the file read, preserving behavior for legacy clients without a stamp.
+    const runTaskBody = async () => {
+        // Re-narrow inside the closure: TypeScript loses the function-scope narrowing
+        // from the early-return guard above once we hand control to a callback.
+        if (!transport || !agent)
+            return;
         // Only refresh config and hot-swap provider when this is the first concurrent task.
         // Subsequent concurrent tasks reuse cached config to avoid race conditions
         // on provider hot-swap (which replaces SessionManager).
@@ -412,12 +435,23 @@ async function executeTask(task, curateExecutor, folderPackExecutor, queryExecut
             agentLog(`task:started send failed taskId=${taskId}: ${error instanceof Error ? error.message : String(error)}`);
             // Socket dropped — continue executing so we can still emit task:completed/error when socket reconnects
         }
+        // Block new tree-writers until any detached Phase 4 from a prior task
+        // on this project drains. `query` / `search` are intentionally NOT
+        // gated — they read the manifest and tolerate a stale snapshot via
+        // `readManifestIfFresh` + rebuild fallback, so blocking them would
+        // be a needless latency hit.
+        if (type === 'curate' || type === 'curate-folder' || type === 'dream') {
+            await postWorkRegistry.awaitProject(projectPath);
+        }
         try {
             let result;
             let logId;
+            // Captured during curate / curate-folder; submitted to the registry
+            // after `task:completed` so the user does not wait on Phase 4.
+            let postWork;
             switch (type) {
                 case 'curate': {
-                    result = await curateExecutor.executeWithAgent(agent, {
+                    const curateResult = await curateExecutor.runAgentBody(agent, {
                         clientCwd,
                         content,
                         files,
@@ -425,10 +459,12 @@ async function executeTask(task, curateExecutor, folderPackExecutor, queryExecut
                         taskId,
                         worktreeRoot,
                     });
+                    result = curateResult.response;
+                    postWork = curateResult.finalize;
                     break;
                 }
                 case 'curate-folder': {
-                    result = await folderPackExecutor.executeWithAgent(agent, {
+                    const folderResult = await folderPackExecutor.runAgentBody(agent, {
                         clientCwd,
                         content,
                         folderPath: folderPath,
@@ -436,6 +472,8 @@ async function executeTask(task, curateExecutor, folderPackExecutor, queryExecut
                         taskId,
                         worktreeRoot,
                     });
+                    result = folderResult.response;
+                    postWork = folderResult.finalize;
                     break;
                 }
                 case 'dream': {
@@ -470,6 +508,7 @@ async function executeTask(task, curateExecutor, folderPackExecutor, queryExecut
                     const dreamResult = await dreamExecutor.executeWithAgent(agent, {
                         priorMtime: eligibility.priorMtime,
                         projectRoot: projectPath,
+                        ...(reviewDisabled === undefined ? {} : { reviewDisabled }),
                         taskId,
                         trigger: trigger ?? 'cli',
                     });
@@ -503,7 +542,8 @@ async function executeTask(task, curateExecutor, folderPackExecutor, queryExecut
                     break;
                 }
             }
-            // Emit task:completed
+            // Emit task:completed BEFORE the detached Phase 4 so the user sees
+            // the response as soon as the agent body finishes.
             agentLog(`task:completed taskId=${taskId}`);
             try {
                 transport.request(TransportTaskEventNames.COMPLETED, { clientId, ...(logId ? { logId } : {}), projectPath, result, taskId });
@@ -511,6 +551,12 @@ async function executeTask(task, curateExecutor, folderPackExecutor, queryExecut
             catch (error) {
                 agentLog(`task:completed send failed taskId=${taskId}: ${error instanceof Error ? error.message : String(error)}`);
             }
+            // Submit detached post-curate work to the registry. Mutex'd per project
+            // and drained on shutdown so SIGTERM mid-work cannot truncate `_index.md`.
+            if (postWork) {
+                agentLog(`post-work queued taskId=${taskId}`);
+                postWorkRegistry.submit(projectPath, postWork);
+            }
         }
         catch (error) {
             // Emit task:error
@@ -526,13 +572,27 @@ async function executeTask(task, curateExecutor, folderPackExecutor, queryExecut
         finally {
             cleanupForwarding?.();
         }
+    };
+    try {
+        await (reviewDisabled === undefined ? runTaskBody() : runWithReviewDisabled(reviewDisabled, runTaskBody));
     }
     finally {
         activeTaskCount--;
-        // Deferred hot-swap: if provider changed while tasks were in-flight,
-        // trigger swap now that all tasks are done
+        // Deferred hot-swap when provider changed mid-task. Wait on detached
+        // Phase 4 first — rebuilding SessionManager during an in-flight
+        // `propagateStaleness` LLM call would silently corrupt Phase 4.
+        // Reserve the swap slot synchronously by clearing the dirty flag now;
+        // a task arriving during the awaitAll wait then sees a clean flag and
+        // skips its inline swap, so only the deferred chain runs hotSwap.
         if (activeTaskCount === 0 && providerConfigDirty && agent && transport) {
-            hotSwapProvider(agent, transport).catch((error) => {
+            providerConfigDirty = false;
+            const swapAgent = agent;
+            const swapTransport = transport;
+            postWorkRegistry
+                .awaitAll()
+                .then(() => hotSwapProvider(swapAgent, swapTransport))
+                .catch((error) => {
+                providerConfigDirty = true;
                 agentLog(`deferred hotSwapProvider failed: ${error instanceof Error ? error.message : String(error)}`);
             });
         }
@@ -663,6 +723,16 @@ async function hotSwapProvider(currentAgent, transportClient) {
 // ============================================================================
 async function shutdown() {
     agentLog('Shutting down...');
+    // Drain detached Phase 4 BEFORE stopping the agent — `propagateStaleness`
+    // mid-write would otherwise leave `_index.md` truncated on SIGTERM.
+    try {
+        const drainStart = Date.now();
+        const drainResult = await postWorkRegistry.drain(30_000);
+        agentLog(`post-work drain (${Date.now() - drainStart}ms): drained=${drainResult.drained} abandoned=${drainResult.abandoned}`);
+    }
+    catch (error) {
+        agentLog(`post-work drain failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
     try {
         if (agent) {
             await agent.stop();

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

@@ -224,6 +224,15 @@ async function main() {
         });
         // Shared queue-length resolver — used by both idle timeout policy and dream trigger
         const getQueueLength = (projectPath) => agentPool?.getQueueState().find((q) => q.projectPath === projectPath)?.queueLength ?? 0;
+        // Shared project-config resolver — used by the idle-dream dispatch and the
+        // task-router resolver wired into TransportHandlers below. Both paths must
+        // stamp the same reviewDisabled value so review semantics are consistent
+        // regardless of dispatch source (CLI task:create vs idle trigger).
+        const curateConfigStore = new ProjectConfigStore();
+        const resolveReviewDisabled = async (projectPath) => {
+            const config = await curateConfigStore.read(projectPath);
+            return config?.reviewDisabled === true;
+        };
         // Shared dream pre-check trigger factory.
         // The lock service explicitly throws if invoked — gate 4 (lock) is the agent's job;
         // the daemon must only ever evaluate gates 1-3 via checkEligibility().
@@ -259,11 +268,18 @@ async function main() {
                     const result = await makeDreamPreCheckTrigger(projectPath).checkEligibility(projectPath);
                     if (result.eligible) {
                         log(`Dream eligible, dispatching dream task: ${projectPath}`);
+                        // Idle dispatch bypasses TaskRouter.handleTaskCreate, so the
+                        // reviewDisabled snapshot that the task-router stamps for the CLI
+                        // path must be reproduced inline here. Without it, idle dreams
+                        // would always default to review-enabled regardless of project
+                        // setting (see resolveReviewDisabled above).
+                        const reviewDisabled = await resolveReviewDisabled(projectPath);
                         agentPool?.submitTask({
                             clientId: 'daemon',
                             content: 'Memory consolidation (idle trigger)',
                             force: false,
                             projectPath,
+                            reviewDisabled,
                             taskId: randomUUID(),
                             trigger: 'agent-idle',
                             type: 'dream',
@@ -321,6 +337,13 @@ async function main() {
         const transportHandlers = new TransportHandlers({
             agentPool,
             clientManager,
+            // 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
+            // single value across the daemon→agent process boundary. Shared with the
+            // 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],
             // 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

package/dist/server/infra/daemon/post-work-registry.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Per-project serialized fire-and-forget queue with bounded shutdown drain.
+ * Different projects run concurrently; same project runs serially so two
+ * writers cannot race on `_index.md`. Thunk errors are swallowed (via
+ * `onError`) so one bad thunk cannot block the chain.
+ */
+export type PostWorkThunk = () => Promise<void>;
+export type PostWorkRegistryOptions = {
+    onError?: (projectPath: string, error: unknown) => void;
+};
+export declare class PostWorkRegistry {
+    /** Optional logger called when a thunk throws. */
+    private readonly onError?;
+    /**
+     * Per-project tail promise. Each `submit(project, thunk)` chains the new
+     * thunk after the previous tail. The tail is replaced atomically so the
+     * next submission picks up the latest one without races.
+     */
+    private readonly tails;
+    constructor(options?: PostWorkRegistryOptions);
+    /**
+     * Wait on the snapshot of tails captured at call time across all projects.
+     * Submissions arriving during the await are not awaited.
+     */
+    awaitAll(): Promise<void>;
+    /**
+     * Wait on the project's tail captured at call time. Submissions arriving
+     * during the await are not awaited — keeps `--wait-finalize` deterministic.
+     */
+    awaitProject(projectPath: string): Promise<void>;
+    /**
+     * Wait up to `timeoutMs` for in-flight work across all projects.
+     * Errored thunks count as `drained` (work resolved, surfaced to onError);
+     * thunks still running at the deadline count as `abandoned`.
+     */
+    drain(timeoutMs: number): Promise<{
+        abandoned: number;
+        drained: number;
+    }>;
+    /**
+     * Submit a thunk to run after any prior work for `projectPath` finishes.
+     * Returns synchronously; the thunk runs on the microtask queue.
+     */
+    submit(projectPath: string, thunk: PostWorkThunk): void;
+}

package/dist/server/infra/daemon/post-work-registry.js

@@ -0,0 +1,82 @@
+/**
+ * Per-project serialized fire-and-forget queue with bounded shutdown drain.
+ * Different projects run concurrently; same project runs serially so two
+ * writers cannot race on `_index.md`. Thunk errors are swallowed (via
+ * `onError`) so one bad thunk cannot block the chain.
+ */
+export class PostWorkRegistry {
+    /** Optional logger called when a thunk throws. */
+    onError;
+    /**
+     * Per-project tail promise. Each `submit(project, thunk)` chains the new
+     * thunk after the previous tail. The tail is replaced atomically so the
+     * next submission picks up the latest one without races.
+     */
+    tails = new Map();
+    constructor(options = {}) {
+        this.onError = options.onError;
+    }
+    /**
+     * Wait on the snapshot of tails captured at call time across all projects.
+     * Submissions arriving during the await are not awaited.
+     */
+    async awaitAll() {
+        const tails = [...this.tails.values()];
+        if (tails.length === 0)
+            return;
+        await Promise.all(tails);
+    }
+    /**
+     * Wait on the project's tail captured at call time. Submissions arriving
+     * during the await are not awaited — keeps `--wait-finalize` deterministic.
+     */
+    async awaitProject(projectPath) {
+        const tail = this.tails.get(projectPath);
+        if (tail) {
+            await tail;
+        }
+    }
+    /**
+     * Wait up to `timeoutMs` for in-flight work across all projects.
+     * Errored thunks count as `drained` (work resolved, surfaced to onError);
+     * thunks still running at the deadline count as `abandoned`.
+     */
+    async drain(timeoutMs) {
+        const tails = [...this.tails.values()];
+        if (tails.length === 0) {
+            return { abandoned: 0, drained: 0 };
+        }
+        let timeoutHandle;
+        const timeoutPromise = new Promise((resolve) => {
+            timeoutHandle = setTimeout(() => resolve('timeout'), timeoutMs);
+        });
+        const results = await Promise.all(tails.map(async (tail) => {
+            const outcome = await Promise.race([tail.then(() => 'done'), timeoutPromise]);
+            return outcome;
+        }));
+        if (timeoutHandle !== undefined)
+            clearTimeout(timeoutHandle);
+        const drained = results.filter((r) => r === 'done').length;
+        const abandoned = results.filter((r) => r === 'timeout').length;
+        return { abandoned, drained };
+    }
+    /**
+     * Submit a thunk to run after any prior work for `projectPath` finishes.
+     * Returns synchronously; the thunk runs on the microtask queue.
+     */
+    submit(projectPath, thunk) {
+        const previousTail = this.tails.get(projectPath) ?? Promise.resolve();
+        const newTail = previousTail
+            .then(thunk)
+            .catch((error) => {
+            this.onError?.(projectPath, error);
+        })
+            .finally(() => {
+            // Drop the map entry only if no follow-up submission appended.
+            if (this.tails.get(projectPath) === newTail) {
+                this.tails.delete(projectPath);
+            }
+        });
+        this.tails.set(projectPath, newTail);
+    }
+}

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

@@ -3,10 +3,9 @@ type DreamLockServiceOptions = {
     staleTimeoutMs?: number;
 };
 /**
- * PID-based lock for dream execution.
- *
- * Lock file contains the owning process PID. Staleness is determined by mtime.
- * Uses write-then-verify to handle race conditions between concurrent acquirers.
+ * PID-based file lock for context-tree writers (dream and curate's detached
+ * post-work). Lock file holds the owner PID; staleness is mtime-based. Uses
+ * write-then-verify to settle races between concurrent acquirers.
  */
 export declare class DreamLockService {
     private readonly lockFilePath;

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

@@ -3,10 +3,9 @@ import { dirname, join } from 'node:path';
 const LOCK_FILENAME = 'dream.lock';
 const DEFAULT_STALE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
 /**
- * PID-based lock for dream execution.
- *
- * Lock file contains the owning process PID. Staleness is determined by mtime.
- * Uses write-then-verify to handle race conditions between concurrent acquirers.
+ * PID-based file lock for context-tree writers (dream and curate's detached
+ * post-work). Lock file holds the owner PID; staleness is mtime-based. Uses
+ * write-then-verify to settle races between concurrent acquirers.
  */
 export class DreamLockService {
     lockFilePath;