byterover-cli 3.10.3 → 3.12.0

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

@@ -200,15 +200,36 @@ async function writeSynthesisFile(candidate, contextTreeDir, runtimeSignalStore,
         // ENOENT — good, proceed
     }
     const sources = candidate.evidence.map((e) => `${e.domain}/_index.md`);
+    // Normalize tags to lowercase kebab-case so card chips and BM25 search see
+    // a consistent label regardless of whether the model honored the prompt's
+    // formatting rule. Empty entries (post-trim) are dropped.
+    const normalizedTags = candidate.tags
+        .map((t) => t.toLowerCase().trim().replaceAll(/\s+/g, '-'))
+        .filter((t) => t.length > 0);
+    const now = new Date().toISOString();
+    // Field order is enforced by insertion order (yamlDump uses sortKeys:false).
+    // Synthesis markers (confidence, sources, synthesized_at, type) come first
+    // in the order pre-existing synthesized files use on disk, so re-generating
+    // an old file does not produce a mechanical reorder diff. The seven
+    // semantic fields below mirror the order in markdown-writer.ts's
+    // generateFrontmatter so the on-disk shape matches regular `brv save`
+    // files; cogit then exposes them in DtoV3MemoryCardResource for card-mode
+    // display in the web UI.
     /* eslint-disable camelcase */
-    const frontmatter = {
-        confidence: candidate.confidence,
-        sources,
-        synthesized_at: new Date().toISOString(),
-        type: 'synthesis',
-    };
+    const frontmatter = {};
+    frontmatter.confidence = candidate.confidence;
+    frontmatter.sources = sources;
+    frontmatter.synthesized_at = now;
+    frontmatter.type = 'synthesis';
+    frontmatter.title = candidate.title;
+    frontmatter.summary = candidate.summary;
+    frontmatter.tags = normalizedTags;
+    frontmatter.related = [];
+    frontmatter.keywords = candidate.keywords;
+    frontmatter.createdAt = now;
+    frontmatter.updatedAt = now;
     /* eslint-enable camelcase */
-    const yaml = yamlDump(frontmatter, { lineWidth: -1, sortKeys: false }).trimEnd();
+    const yaml = yamlDump(frontmatter, { flowLevel: 1, lineWidth: -1, sortKeys: false }).trimEnd();
     const body = [
         `# ${candidate.title}`,
         '',
@@ -280,11 +301,17 @@ function buildPrompt(domains, existingSyntheses) {
         '- Do NOT report trivial or obvious connections (e.g., "both domains use TypeScript").',
         '- Each synthesis must reference at least 2 domains with specific evidence.',
         '- For "placement", choose the domain where this insight is MOST actionable.',
+        '- "summary" is one sentence (≤ 200 chars) describing the insight; this is what the UI shows as a card preview.',
+        '- "tags" are 3-5 short topical labels drawn from the source domains (e.g., "auth", "caching"). Lowercase, kebab-case.',
+        '- "keywords" are 5-10 single words a developer would search for to surface this synthesis.',
         '- If nothing meaningful is found, return an empty array. That is fine — but missing a clear cross-domain pattern is a failure.',
         '',
+        // Keep the JSON shape below in sync with SynthesisCandidateSchema in
+        // dream-response-schemas.ts; the schema rejects responses that omit any
+        // listed field, so adding a field there requires updating this example.
         'Respond with JSON:',
         '```',
-        '{ "syntheses": [{ "title": "...", "claim": "...", "evidence": [{"domain": "...", "fact": "..."}], "confidence": 0.0-1.0, "placement": "..." }] }',
+        '{ "syntheses": [{ "title": "...", "summary": "...", "claim": "...", "evidence": [{"domain": "...", "fact": "..."}], "tags": ["..."], "keywords": ["..."], "confidence": 0.0-1.0, "placement": "..." }] }',
         '```',
     ].join('\n');
 }

package/dist/server/infra/http/provider-model-fetcher-registry.js

@@ -45,6 +45,7 @@ export async function getModelFetcher(providerId) {
         case 'cerebras': // falls through
         case 'cohere': // falls through
         case 'deepinfra': // falls through
+        case 'deepseek': // falls through
         case 'groq': // falls through
         case 'mistral': // falls through
         case 'togetherai': // falls through
@@ -59,6 +60,10 @@ export async function getModelFetcher(providerId) {
             fetcher = new ChatBasedModelFetcher('https://api.z.ai/api/paas/v4', 'GLM (Z.AI)', ['glm-4.7', 'glm-4.6', 'glm-4.5', 'glm-4.5-flash']);
             break;
         }
+        case 'glm-coding-plan': {
+            fetcher = new ChatBasedModelFetcher('https://api.z.ai/api/coding/paas/v4', 'GLM Coding Plan (Z.AI)', ['glm-4.7', 'glm-4.7-flash', 'glm-4.7-flashx', 'glm-5-turbo', 'glm-4.5', 'glm-4.5-flash']);
+            break;
+        }
         case 'google': {
             fetcher = new GoogleModelFetcher();
             break;

package/dist/server/infra/http/provider-model-fetchers.js

@@ -429,36 +429,63 @@ export class ChatBasedModelFetcher {
         return this.knownModels;
     }
     async validateApiKey(apiKey) {
-        try {
-            await axios.post(`${this.baseUrl}/chat/completions`, {
-                max_tokens: 1,
-                messages: [{ content: 'hi', role: 'user' }],
-                model: this.knownModels[0]?.id ?? 'default',
-            }, {
-                headers: {
-                    Authorization: `Bearer ${apiKey}`,
-                    'Content-Type': 'application/json',
-                },
-                httpAgent: ProxyConfig.getProxyAgent(),
-                httpsAgent: ProxyConfig.getProxyAgent(),
-                proxy: false,
-                timeout: 15_000,
-            });
-            return { isValid: true };
-        }
-        catch (error) {
-            if (isAxiosError(error)) {
-                if (error.response?.status === 401) {
-                    return { error: 'Invalid API key', isValid: false };
-                }
-                if (error.response?.status === 403) {
-                    return { error: 'API key does not have required permissions', isValid: false };
-                }
-                // Other errors (429, 400, etc.) mean the key was accepted
+        // Iterate through known models so a single missing model on a tier (e.g.
+        // GLM Coding Plan doesn't yet serve the latest glm-4.7) doesn't
+        // misclassify a valid key as invalid. We accept the key as soon as ANY
+        // model responds successfully, OR returns a non-auth error like 429/5xx
+        // (which still proves the key passed auth).
+        const candidates = this.knownModels.length > 0 ? this.knownModels : [{ id: 'default' }];
+        let lastNonAuthError;
+        for (const candidate of candidates) {
+            try {
+                // eslint-disable-next-line no-await-in-loop
+                await axios.post(`${this.baseUrl}/chat/completions`, {
+                    max_tokens: 1,
+                    messages: [{ content: 'hi', role: 'user' }],
+                    model: candidate.id,
+                }, {
+                    headers: {
+                        Authorization: `Bearer ${apiKey}`,
+                        'Content-Type': 'application/json',
+                    },
+                    httpAgent: ProxyConfig.getProxyAgent(),
+                    httpsAgent: ProxyConfig.getProxyAgent(),
+                    proxy: false,
+                    timeout: 15_000,
+                });
                 return { isValid: true };
             }
-            return { error: error instanceof Error ? error.message : 'Unknown error', isValid: false };
+            catch (error) {
+                if (isAxiosError(error)) {
+                    if (error.response?.status === 401) {
+                        return { error: 'Invalid API key', isValid: false };
+                    }
+                    if (error.response?.status === 403) {
+                        return { error: 'API key does not have required permissions', isValid: false };
+                    }
+                    // 400/404 may mean "model not available on this tier" — try next.
+                    if (error.response?.status === 400 || error.response?.status === 404) {
+                        lastNonAuthError = error;
+                        continue;
+                    }
+                    // Axios errors that are not 401/403/400/404 (e.g. 429, 5xx, or
+                    // network-level errors with no response like ECONNREFUSED) are
+                    // treated as "key accepted" — either auth was passed (429/5xx) or
+                    // we can't determine otherwise (no response). Optimistic: prefer a
+                    // false-positive valid over a false-negative invalid.
+                    return { isValid: true };
+                }
+                lastNonAuthError = error;
+            }
         }
+        // Every candidate model returned 400/404 or a non-axios error and none
+        // gave us a positive auth signal. Treat the key as inconclusive — but
+        // since 401/403 was never observed, surface the last error so the user
+        // can see the real cause (often a model-availability issue, not auth).
+        return {
+            error: lastNonAuthError instanceof Error ? lastNonAuthError.message : 'Validation failed for all known models',
+            isValid: false,
+        };
     }
 }
 // ============================================================================

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

@@ -25,6 +25,12 @@ export declare class QueryLogHandler implements ITaskLifecycleHook {
     private readonly tasks;
     constructor(createStore?: ((projectPath: string) => IQueryLogStore) | undefined);
     cleanup(taskId: string): void;
+    /**
+     * Expose query metadata via the lifecycle-hook contract so TaskRouter can merge it into
+     * the task:completed payload sent to the originating client. Returning {} when no metadata
+     * is available keeps the merge a no-op and lets the daemon emit task:completed unchanged.
+     */
+    getTaskCompletionData(taskId: string): Record<string, unknown>;
     onTaskCancelled(taskId: string, _task: TaskInfo): Promise<void>;
     onTaskCompleted(taskId: string, result: string, _task: TaskInfo): Promise<void>;
     onTaskCreate(task: TaskInfo): Promise<void | {

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

@@ -39,6 +39,29 @@ export class QueryLogHandler {
             }
         }
     }
+    /**
+     * Expose query metadata via the lifecycle-hook contract so TaskRouter can merge it into
+     * the task:completed payload sent to the originating client. Returning {} when no metadata
+     * is available keeps the merge a no-op and lets the daemon emit task:completed unchanged.
+     */
+    getTaskCompletionData(taskId) {
+        const state = this.tasks.get(taskId);
+        if (!state?.queryResult)
+            return {};
+        // Flatten the QueryExecutorResult's nested shape onto the task:completed payload so
+        // it matches the public RecallResult contract (flat `durationMs` / `topScore`).
+        // `timing` is always populated by every QueryExecutor branch, so no guard.
+        // `searchMetadata` is omitted on cache hits (Tier 0/1), so guard before extracting.
+        const out = {
+            durationMs: state.queryResult.timing.durationMs,
+            matchedDocs: state.queryResult.matchedDocs,
+            tier: state.queryResult.tier,
+        };
+        if (state.queryResult.searchMetadata !== undefined) {
+            out.topScore = state.queryResult.searchMetadata.topScore;
+        }
+        return out;
+    }
     async onTaskCancelled(taskId, _task) {
         const state = this.tasks.get(taskId);
         if (!state)

package/dist/server/infra/process/task-history-entry-builder.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Build a `TaskHistoryEntry` from a live `TaskInfo`. Single source of truth
+ * for `task-router.ts:handleTaskGet` (in-memory synthesis) and
+ * `task-history-hook.ts:persist` (lifecycle persistence) — extracting it here
+ * eliminates the duplicate `baseFromTaskInfo` + `statusShapeFromTaskInfo`
+ * pair that previously lived in both modules and would silently drift.
+ *
+ * Two functions are exposed:
+ * - `buildTaskHistoryEntry(task)` — full Zod-parsed `TaskHistoryEntry`,
+ *   used by `task-router.handleTaskGet` to return the same shape as
+ *   `store.getById` for in-flight tasks. Returns `undefined` when the
+ *   `TaskInfo` is incomplete (e.g. missing `projectPath`) or when the
+ *   inferred shape fails Zod validation.
+ * - `buildTaskHistoryEntryCandidate({task, override})` — pre-Zod object
+ *   used by the lifecycle hook, which sometimes injects branch-specific
+ *   fields (terminal completedAt / error / result) before validation.
+ */
+import type { TaskInfo } from '../../core/domain/transport/task-info.js';
+import { type TaskHistoryEntry } from '../../core/domain/entities/task-history-entry.js';
+/**
+ * Build the pre-validation candidate object. The lifecycle hook calls this
+ * with an `override` to inject terminal-status fields before Zod-parsing.
+ */
+export declare function buildTaskHistoryEntryCandidate(args: {
+    override?: Record<string, unknown>;
+    task: TaskInfo;
+}): Record<string, unknown>;
+/**
+ * Build a fully-validated `TaskHistoryEntry` from in-memory `TaskInfo`.
+ * Returns `undefined` when `task.projectPath` is missing or when the
+ * candidate fails Zod validation.
+ *
+ * Used by `task-router.handleTaskGet` to return live in-flight tasks in the
+ * same shape `store.getById` would have returned for persisted ones.
+ */
+export declare function buildTaskHistoryEntry(task: TaskInfo): TaskHistoryEntry | undefined;

package/dist/server/infra/process/task-history-entry-builder.js

@@ -0,0 +1,101 @@
+/**
+ * Build a `TaskHistoryEntry` from a live `TaskInfo`. Single source of truth
+ * for `task-router.ts:handleTaskGet` (in-memory synthesis) and
+ * `task-history-hook.ts:persist` (lifecycle persistence) — extracting it here
+ * eliminates the duplicate `baseFromTaskInfo` + `statusShapeFromTaskInfo`
+ * pair that previously lived in both modules and would silently drift.
+ *
+ * Two functions are exposed:
+ * - `buildTaskHistoryEntry(task)` — full Zod-parsed `TaskHistoryEntry`,
+ *   used by `task-router.handleTaskGet` to return the same shape as
+ *   `store.getById` for in-flight tasks. Returns `undefined` when the
+ *   `TaskInfo` is incomplete (e.g. missing `projectPath`) or when the
+ *   inferred shape fails Zod validation.
+ * - `buildTaskHistoryEntryCandidate({task, override})` — pre-Zod object
+ *   used by the lifecycle hook, which sometimes injects branch-specific
+ *   fields (terminal completedAt / error / result) before validation.
+ */
+import { TASK_HISTORY_ID_PREFIX } from '../../constants.js';
+import { TASK_HISTORY_SCHEMA_VERSION, TaskHistoryEntrySchema, } from '../../core/domain/entities/task-history-entry.js';
+/** Build the base shape (fields shared by every status branch). */
+function baseFromTaskInfo(task) {
+    return {
+        content: task.content,
+        createdAt: task.createdAt,
+        id: `${TASK_HISTORY_ID_PREFIX}-${task.taskId}`,
+        projectPath: task.projectPath,
+        schemaVersion: TASK_HISTORY_SCHEMA_VERSION,
+        taskId: task.taskId,
+        type: task.type,
+        ...(task.clientCwd === undefined ? {} : { clientCwd: task.clientCwd }),
+        ...(task.files === undefined ? {} : { files: task.files }),
+        ...(task.folderPath === undefined ? {} : { folderPath: task.folderPath }),
+        ...(task.logId === undefined ? {} : { logId: task.logId }),
+        ...(task.model === undefined ? {} : { model: task.model }),
+        ...(task.provider === undefined ? {} : { provider: task.provider }),
+        ...(task.reasoningContents === undefined ? {} : { reasoningContents: task.reasoningContents }),
+        ...(task.responseContent === undefined ? {} : { responseContent: task.responseContent }),
+        ...(task.sessionId === undefined ? {} : { sessionId: task.sessionId }),
+        ...(task.toolCalls === undefined ? {} : { toolCalls: task.toolCalls }),
+        ...(task.worktreeRoot === undefined ? {} : { worktreeRoot: task.worktreeRoot }),
+    };
+}
+/**
+ * Build the per-branch shape inferred from `task.status`. Override-only
+ * paths (terminal hooks) supply their own status; this is the default for
+ * in-flight transitions.
+ */
+function statusShapeFromTaskInfo(task) {
+    switch (task.status) {
+        case 'cancelled':
+        case 'completed': {
+            return {
+                completedAt: task.completedAt ?? Date.now(),
+                status: task.status,
+                ...(task.startedAt === undefined ? {} : { startedAt: task.startedAt }),
+                ...(task.status === 'completed' && task.result !== undefined ? { result: task.result } : {}),
+            };
+        }
+        case 'error': {
+            return {
+                completedAt: task.completedAt ?? Date.now(),
+                error: task.error ?? { code: 'TASK_ERROR', message: 'unknown error', name: 'TaskError' },
+                status: 'error',
+                ...(task.startedAt === undefined ? {} : { startedAt: task.startedAt }),
+            };
+        }
+        case 'started': {
+            return { startedAt: task.startedAt ?? task.createdAt, status: 'started' };
+        }
+        // 'created' or undefined — minimal base, no extra branch fields.
+        default: {
+            return { status: 'created' };
+        }
+    }
+}
+/**
+ * Build the pre-validation candidate object. The lifecycle hook calls this
+ * with an `override` to inject terminal-status fields before Zod-parsing.
+ */
+export function buildTaskHistoryEntryCandidate(args) {
+    const { override, task } = args;
+    if (override !== undefined) {
+        return { ...baseFromTaskInfo(task), ...statusShapeFromTaskInfo(task), ...override };
+    }
+    return { ...baseFromTaskInfo(task), ...statusShapeFromTaskInfo(task) };
+}
+/**
+ * Build a fully-validated `TaskHistoryEntry` from in-memory `TaskInfo`.
+ * Returns `undefined` when `task.projectPath` is missing or when the
+ * candidate fails Zod validation.
+ *
+ * Used by `task-router.handleTaskGet` to return live in-flight tasks in the
+ * same shape `store.getById` would have returned for persisted ones.
+ */
+export function buildTaskHistoryEntry(task) {
+    if (task.projectPath === undefined)
+        return undefined;
+    const candidate = buildTaskHistoryEntryCandidate({ task });
+    const parsed = TaskHistoryEntrySchema.safeParse(candidate);
+    return parsed.success ? parsed.data : undefined;
+}

package/dist/server/infra/process/task-history-hook.d.ts

@@ -0,0 +1,37 @@
+/**
+ * TaskHistoryHook — persists `TaskInfo` to `ITaskHistoryStore` at every
+ * lifecycle transition (created / started-via-throttle / terminal).
+ *
+ * Wired into TaskRouter via `lifecycleHooks[]`. The 4 existing methods fire
+ * synchronously at create + terminal; the new `onTaskUpdate` fires on the
+ * throttled flush (~100ms) for in-flight mutations populated by the
+ * llmservice accumulator.
+ *
+ * Holds NO per-task state — every method reads from the live `TaskInfo`
+ * passed in. Errors are swallowed via `processLog`; tasks without
+ * `projectPath` are skipped silently.
+ */
+import type { TaskInfo } from '../../core/domain/transport/task-info.js';
+import type { ITaskLifecycleHook } from '../../core/interfaces/process/i-task-lifecycle-hook.js';
+import type { ITaskHistoryStore } from '../../core/interfaces/storage/i-task-history-store.js';
+type TaskHistoryHookOptions = {
+    /** Per-project store factory (DIP — never depends on FileTaskHistoryStore directly). */
+    getStore: (projectPath: string) => ITaskHistoryStore;
+};
+export declare class TaskHistoryHook implements ITaskLifecycleHook {
+    private readonly getStore;
+    constructor(opts: TaskHistoryHookOptions);
+    onTaskCancelled(_taskId: string, task: TaskInfo): Promise<void>;
+    onTaskCompleted(_taskId: string, result: string, task: TaskInfo): Promise<void>;
+    onTaskCreate(task: TaskInfo): Promise<void>;
+    onTaskError(_taskId: string, errorMessage: string, task: TaskInfo): Promise<void>;
+    onTaskUpdate(task: TaskInfo): Promise<void>;
+    /**
+     * Build + save a `TaskHistoryEntry` from the current `TaskInfo`. Optional
+     * `override` injects branch-specific fields (status / completedAt / error /
+     * result). When omitted, the branch shape is inferred from `task.status`
+     * by `buildTaskHistoryEntryCandidate`.
+     */
+    private persist;
+}
+export {};

package/dist/server/infra/process/task-history-hook.js

@@ -0,0 +1,70 @@
+/**
+ * TaskHistoryHook — persists `TaskInfo` to `ITaskHistoryStore` at every
+ * lifecycle transition (created / started-via-throttle / terminal).
+ *
+ * Wired into TaskRouter via `lifecycleHooks[]`. The 4 existing methods fire
+ * synchronously at create + terminal; the new `onTaskUpdate` fires on the
+ * throttled flush (~100ms) for in-flight mutations populated by the
+ * llmservice accumulator.
+ *
+ * Holds NO per-task state — every method reads from the live `TaskInfo`
+ * passed in. Errors are swallowed via `processLog`; tasks without
+ * `projectPath` are skipped silently.
+ */
+import { TaskHistoryEntrySchema } from '../../core/domain/entities/task-history-entry.js';
+import { processLog } from '../../utils/process-logger.js';
+import { buildTaskHistoryEntryCandidate } from './task-history-entry-builder.js';
+export class TaskHistoryHook {
+    getStore;
+    constructor(opts) {
+        this.getStore = opts.getStore;
+    }
+    async onTaskCancelled(_taskId, task) {
+        await this.persist(task, { completedAt: Date.now(), status: 'cancelled' });
+    }
+    async onTaskCompleted(_taskId, result, task) {
+        await this.persist(task, {
+            completedAt: Date.now(),
+            ...(result ? { result } : {}),
+            status: 'completed',
+        });
+    }
+    async onTaskCreate(task) {
+        await this.persist(task, { status: 'created' });
+    }
+    async onTaskError(_taskId, errorMessage, task) {
+        await this.persist(task, {
+            completedAt: Date.now(),
+            error: { code: 'TASK_ERROR', message: errorMessage, name: 'TaskError' },
+            status: 'error',
+        });
+    }
+    async onTaskUpdate(task) {
+        await this.persist(task);
+    }
+    /**
+     * Build + save a `TaskHistoryEntry` from the current `TaskInfo`. Optional
+     * `override` injects branch-specific fields (status / completedAt / error /
+     * result). When omitted, the branch shape is inferred from `task.status`
+     * by `buildTaskHistoryEntryCandidate`.
+     */
+    async persist(task, override) {
+        if (!task.projectPath)
+            return;
+        const candidate = buildTaskHistoryEntryCandidate({ override, task });
+        let entry;
+        try {
+            entry = TaskHistoryEntrySchema.parse(candidate);
+        }
+        catch (error) {
+            processLog(`TaskHistoryHook: failed to build entry for ${task.taskId}: ${error instanceof Error ? error.message : String(error)}`);
+            return;
+        }
+        try {
+            await this.getStore(task.projectPath).save(entry);
+        }
+        catch (error) {
+            processLog(`TaskHistoryHook: store.save failed for ${task.taskId}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}

package/dist/server/infra/process/task-history-store-cache.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Per-project FileTaskHistoryStore cache + lazy startup audit.
+ *
+ * Module-scoped so M2.09's wire handlers can reuse the same store instances
+ * the M2.06 lifecycle hook writes to. Audit fires once per project on first
+ * access, comparing `_index.jsonl` ↔ `data/` files to flag orphans without
+ * auto-fixing (M2.03 compaction owns the cleanup pass).
+ */
+import { FileTaskHistoryStore } from '../storage/file-task-history-store.js';
+/**
+ * Resolve (or lazily create) the per-project store. The first call for a
+ * given `projectPath` schedules a best-effort audit; subsequent calls reuse
+ * the cached store and skip re-auditing.
+ */
+export declare function getStore(projectPath: string): FileTaskHistoryStore;
+/**
+ * Compare `_index.jsonl` (live entries) against the `data/` directory and log
+ * orphans. Best-effort: never throws to caller. The `log` parameter defaults
+ * to `processLog` for production; tests inject a stub.
+ */
+export declare function auditTaskHistory(projectPath: string, store: FileTaskHistoryStore, log?: ((msg: string) => void) | undefined): Promise<void>;
+/** Test-only: clear module-scope state so each test sees a fresh cache. */
+export declare function resetTaskHistoryStoreCache(): void;
+/** Test-only: inject a logger into the audit path triggered by `getStore`. Pass no arg to clear. */
+export declare function _setTestLoggerForGetStore(log?: (msg: string) => void): void;

package/dist/server/infra/process/task-history-store-cache.js

@@ -0,0 +1,106 @@
+/**
+ * Per-project FileTaskHistoryStore cache + lazy startup audit.
+ *
+ * Module-scoped so M2.09's wire handlers can reuse the same store instances
+ * the M2.06 lifecycle hook writes to. Audit fires once per project on first
+ * access, comparing `_index.jsonl` ↔ `data/` files to flag orphans without
+ * auto-fixing (M2.03 compaction owns the cleanup pass).
+ */
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { TASK_HISTORY_DIR } from '../../constants.js';
+import { getProjectDataDir } from '../../utils/path-utils.js';
+import { processLog } from '../../utils/process-logger.js';
+import { FileTaskHistoryStore } from '../storage/file-task-history-store.js';
+const FILENAME_PATTERN = /^tsk-(.+)\.json$/;
+const MAX_LISTED_ORPHANS = 5;
+const stores = new Map();
+const auditedProjects = new Set();
+/**
+ * Daemon boot wall-clock timestamp. Captured at module load so EVERY per-project
+ * store shares the same boot reference. The C0 daemon-startup gate inside
+ * `FileTaskHistoryStore.isStaleAndRecoverable` uses this to skip stale-recovery
+ * for entries written post-boot — those belong to live in-memory tasks whose
+ * lifecycle hooks are still firing throttled saves and must not be tombstoned
+ * to `INTERRUPTED`.
+ *
+ * `resetTaskHistoryStoreCache()` re-captures it so tests see fresh boot
+ * semantics per `beforeEach`.
+ */
+let daemonStartedAt = Date.now();
+/** Optional logger override for tests — when set, audit triggered inside getStore uses this. */
+let testLoggerForGetStore;
+/**
+ * Resolve (or lazily create) the per-project store. The first call for a
+ * given `projectPath` schedules a best-effort audit; subsequent calls reuse
+ * the cached store and skip re-auditing.
+ */
+export function getStore(projectPath) {
+    let store = stores.get(projectPath);
+    if (!store) {
+        store = new FileTaskHistoryStore({ baseDir: getProjectDataDir(projectPath), daemonStartedAt });
+        stores.set(projectPath, store);
+    }
+    if (!auditedProjects.has(projectPath)) {
+        auditedProjects.add(projectPath);
+        auditTaskHistory(projectPath, store, testLoggerForGetStore).catch((error) => {
+            processLog(`[task-history] audit failed for ${projectPath}: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    }
+    return store;
+}
+/**
+ * Compare `_index.jsonl` (live entries) against the `data/` directory and log
+ * orphans. Best-effort: never throws to caller. The `log` parameter defaults
+ * to `processLog` for production; tests inject a stub.
+ */
+export async function auditTaskHistory(projectPath, store, log = undefined) {
+    const effectiveLog = log ?? processLog;
+    const liveEntries = await store.list();
+    const liveTaskIds = new Set(liveEntries.map((e) => e.taskId));
+    const dataDir = join(getProjectDataDir(projectPath), TASK_HISTORY_DIR, 'data');
+    let dataFiles;
+    try {
+        dataFiles = await readdir(dataDir);
+    }
+    catch {
+        dataFiles = [];
+    }
+    const dataTaskIds = new Set();
+    for (const filename of dataFiles) {
+        const match = FILENAME_PATTERN.exec(filename);
+        if (match)
+            dataTaskIds.add(match[1]);
+    }
+    const orphanIndex = [...liveTaskIds].filter((id) => !dataTaskIds.has(id));
+    const orphanData = [...dataTaskIds].filter((id) => !liveTaskIds.has(id));
+    const head = `[task-history] audit ${projectPath} — ${liveTaskIds.size} live entries, ${dataTaskIds.size} data files.`;
+    if (orphanIndex.length === 0 && orphanData.length === 0) {
+        effectiveLog(`${head} ok.`);
+        return;
+    }
+    const parts = [];
+    if (orphanIndex.length > 0)
+        parts.push(formatOrphans('orphan-index', orphanIndex));
+    if (orphanData.length > 0)
+        parts.push(formatOrphans('orphan-data', orphanData));
+    effectiveLog(`${head} WARN: ${parts.join('; ')}.`);
+}
+/** Test-only: clear module-scope state so each test sees a fresh cache. */
+export function resetTaskHistoryStoreCache() {
+    stores.clear();
+    auditedProjects.clear();
+    testLoggerForGetStore = undefined;
+    // Re-capture boot time so tests see fresh "this daemon just started" semantics
+    // for the C0 stale-recovery gate.
+    daemonStartedAt = Date.now();
+}
+/** Test-only: inject a logger into the audit path triggered by `getStore`. Pass no arg to clear. */
+export function _setTestLoggerForGetStore(log) {
+    testLoggerForGetStore = log;
+}
+function formatOrphans(label, ids) {
+    const listed = ids.slice(0, MAX_LISTED_ORPHANS).map((id) => `tsk-${id}`).join(', ');
+    const remainder = ids.length > MAX_LISTED_ORPHANS ? ` (+${ids.length - MAX_LISTED_ORPHANS} more)` : '';
+    return `${ids.length} ${label} ${listed}${remainder}`;
+}