byterover-cli 3.11.0 → 3.12.0

package/dist/server/infra/process/transport-handlers.d.ts

@@ -31,6 +31,7 @@ import type { IClientManager } from '../../core/interfaces/client/i-client-manag
 import type { ITaskLifecycleHook } from '../../core/interfaces/process/i-task-lifecycle-hook.js';
 import type { IProjectRegistry } from '../../core/interfaces/project/i-project-registry.js';
 import type { IProjectRouter } from '../../core/interfaces/routing/i-project-router.js';
+import type { ITaskHistoryStore } from '../../core/interfaces/storage/i-task-history-store.js';
 import type { ITransportServer } from '../../core/interfaces/transport/i-transport-server.js';
 import type { IsReviewDisabledResolver, PreDispatchCheck } from './task-router.js';
 export type { IsReviewDisabledResolver, PreDispatchCheck, PreDispatchCheckResult } from './task-router.js';
@@ -43,6 +44,8 @@ type TransportHandlersOptions = {
      * `client:register` ack so clients can render version-drift indicators.
      */
     daemonVersion?: string;
+    /** Per-project `ITaskHistoryStore` factory used by the M2.09 persistent-history handlers. */
+    getTaskHistoryStore?: (projectPath: string) => ITaskHistoryStore;
     /** Resolves project's review-disabled flag at task-create. Snapshotted once into TaskInfo + TaskExecute. */
     isReviewDisabled?: IsReviewDisabledResolver;
     /** Lifecycle hooks for task events (e.g. CurateLogHandler). */
@@ -51,6 +54,11 @@ type TransportHandlersOptions = {
     preDispatchCheck?: PreDispatchCheck;
     projectRegistry?: IProjectRegistry;
     projectRouter?: IProjectRouter;
+    /** Resolves the active provider/model snapshot stamped onto created tasks. */
+    resolveActiveProvider?: () => Promise<{
+        model?: string;
+        provider?: string;
+    }>;
     transport: ITransportServer;
 };
 /**

package/dist/server/infra/process/transport-handlers.js

@@ -41,11 +41,13 @@ export class TransportHandlers {
         this.taskRouter = new TaskRouter({
             agentPool: options.agentPool,
             getAgentForProject: (projectPath) => this.connectionCoordinator.getAgentForProject(projectPath),
+            getTaskHistoryStore: options.getTaskHistoryStore,
             isReviewDisabled: options.isReviewDisabled,
             lifecycleHooks: options.lifecycleHooks,
             preDispatchCheck: options.preDispatchCheck,
             projectRegistry: options.projectRegistry,
             projectRouter: options.projectRouter,
+            resolveActiveProvider: options.resolveActiveProvider,
             resolveClientProjectPath: (clientId) => options.clientManager?.getClient(clientId)?.projectPath,
             transport: options.transport,
         });

package/dist/server/infra/storage/file-task-history-store.d.ts

@@ -0,0 +1,294 @@
+/**
+ * File-based implementation of `ITaskHistoryStore`.
+ *
+ * Two-tier on-disk format:
+ * - `_index.jsonl` — append-only summary file. One JSON-line per save.
+ *   Cheap to scan for list views.
+ * - `data/tsk-${taskId}.json` — full Level 2 detail per task (response,
+ *   tool calls, reasoning) for the detail panel.
+ *
+ * Save ordering (data first, index second) bounds the failure mode to
+ * orphan data files (invisible to `list()`); compaction in M2.03 will
+ * sweep them. The reverse order would create dangling index entries
+ * pointing at non-existent data files.
+ *
+ * M2.02 scope: save / getById / list. Prune (M2.03), stale recovery
+ * (M2.04), and delete/clear (M2.05) land in subsequent tickets.
+ */
+import type { TaskListItem } from '../../../shared/transport/events/task-events.js';
+import type { TaskHistoryEntry } from '../../core/domain/entities/task-history-entry.js';
+import type { ITaskHistoryStore, TaskHistoryStatus } from '../../core/interfaces/storage/i-task-history-store.js';
+/**
+ * Group a list of pre-serialized index lines into batches whose total UTF-8
+ * byte length stays under `maxBytes`. A single line larger than `maxBytes` is
+ * emitted as its own batch (we never split a line — the caller relies on
+ * line-level atomicity).
+ *
+ * Exported for direct unit-testing of the chunk boundaries.
+ */
+export declare function chunkLinesByBytes(lines: readonly string[], maxBytes: number): readonly (readonly string[])[];
+type FileTaskHistoryStoreOptions = {
+    baseDir: string;
+    /**
+     * Wall-clock time at which this daemon process started. Used to gate
+     * stale-recovery: only entries whose `lastSavedAt < daemonStartedAt`
+     * are considered orphans of a previous daemon boot. Entries saved
+     * post-boot belong to an in-memory active task and must NEVER be
+     * recovered to `error: INTERRUPTED` (the read path would otherwise
+     * ping-pong with the live throttled saves at every `list()` call).
+     *
+     * Defaults to `Date.now()` at construction time, which is correct for
+     * production (one store per project, constructed at first use).
+     * Tests that wish to simulate "entries from a previous daemon" should
+     * pass a value FAR IN THE FUTURE so their saves register as pre-boot.
+     */
+    daemonStartedAt?: number;
+    /**
+     * Age-based prune threshold. Entries older than this many days are
+     * tombstoned + their data files unlinked. Default `TASK_HISTORY_DEFAULT_MAX_AGE_DAYS`
+     * (0 — disabled by default; count cap is the sole retention). Pass a
+     * positive integer to opt in to time-based eviction for a specific store.
+     */
+    maxAgeDays?: number;
+    /**
+     * Count-based prune cap. When live entry count exceeds this, oldest excess
+     * entries are tombstoned. Default `TASK_HISTORY_DEFAULT_MAX_ENTRIES` (1000).
+     * Pass `Number.POSITIVE_INFINITY` to disable.
+     */
+    maxEntries?: number;
+    /**
+     * Index-compaction trigger. When `total_lines / live_count` exceeds this
+     * ratio, `_index.jsonl` is rewritten with one line per live entry. Default
+     * `TASK_HISTORY_DEFAULT_MAX_INDEX_BLOAT_RATIO` (2). Pass
+     * `Number.POSITIVE_INFINITY` to disable compaction.
+     */
+    maxIndexBloatRatio?: number;
+    /**
+     * Staleness threshold for read-path recovery: entries with status `'created'`
+     * or `'started'` whose `createdAt` is older than this are rewritten to
+     * `status: 'error'` with `code: 'INTERRUPTED'`. Defaults to
+     * `TASK_HISTORY_STALE_THRESHOLD_MS` (10 minutes). Pass
+     * `Number.POSITIVE_INFINITY` to disable recovery.
+     */
+    staleThresholdMs?: number;
+};
+export declare class FileTaskHistoryStore implements ITaskHistoryStore {
+    private readonly daemonStartedAt;
+    private readonly dataDir;
+    /** Dedup-by-taskId result of the last index read. Invalidated on save/delete/recovery/prune. */
+    private indexCache;
+    /**
+     * In-flight `readIndexDedup` promise — concurrent callers (e.g. `getById`
+     * and a parallel `prune` timer) share the same pass so the embedded
+     * stale-recovery side effect cannot double-append index lines for the
+     * same taskId.
+     */
+    private indexDedupInFlight;
+    /**
+     * Monotonic counter bumped on every write to the index (save / tombstone /
+     * recovery / compaction). `doReadIndexDedup` samples it at start and at
+     * end of its pass; if the epoch advanced during the pass, the snapshot
+     * the pass built is stale relative to disk and MUST NOT replace the
+     * `indexCache`. Without this guard, a `firePrune` pass that began before
+     * a concurrent `save()` can finish AFTER that save's cache invalidation
+     * and overwrite the invalidation with a snapshot missing the just-saved
+     * row — visible to callers as "list() returns N-1 entries after N awaited
+     * saves" (the Category B race).
+     */
+    private indexEpoch;
+    private readonly indexPath;
+    private readonly maxAgeDays;
+    private readonly maxEntries;
+    private readonly maxIndexBloatRatio;
+    /**
+     * Promise-chain lock serializing operations that mutate the index file
+     * AND the data dir together — compaction (snapshot → rewrite → post-rewrite
+     * recovery → orphan sweep) and tombstoneAndUnlink (append + unlink). These
+     * two operations cannot interleave: a tombstone landing mid-rewrite would
+     * be wiped by `rename`, and `recoverPreRenameSaves` cannot recover the
+     * tombstone (the data file has been unlinked) — leaving a phantom row
+     * (B2). `save()` is intentionally NOT locked: its data file persists, so
+     * the C1 fix recovers from the data dir if the index line is wiped.
+     */
+    private operationLock;
+    /**
+     * Promise of the most recently scheduled prune+compaction pass. Each
+     * `firePrune()` call wraps its `setTimeout` in a promise and assigns it
+     * here; re-entrance via `pruneRequested` extends the chain through the
+     * tail-recursive `firePrune()` in the `.finally`. Tests await on this via
+     * `flushPendingOperations()` to drain pending work deterministically
+     * instead of polling.
+     */
+    private pruneChain;
+    /** Dedupes concurrent prune passes — only one runs at a time. */
+    private pruneInFlight;
+    /** Set when a save fires while a prune is in flight; triggers a re-run after current pass. */
+    private pruneRequested;
+    private readonly staleThresholdMs;
+    private readonly storeDir;
+    constructor(opts: FileTaskHistoryStoreOptions);
+    clear(options?: {
+        projectPath?: string;
+        statuses?: TaskHistoryStatus[];
+    }): Promise<{
+        deletedCount: number;
+        taskIds: string[];
+    }>;
+    delete(taskId: string): Promise<boolean>;
+    deleteMany(taskIds: string[]): Promise<string[]>;
+    /**
+     * Deterministically wait for all in-flight prune/compaction work to drain.
+     * Loops because each prune pass may schedule the next via `pruneRequested`,
+     * which `firePrune()` reschedules at the tail of `pruneChain`. Also drains
+     * `operationLock` so any compaction/tombstone serializer queued behind a
+     * prune has finished its writes before the caller proceeds.
+     *
+     * Test-only contract: production daemon never calls this — saves are
+     * fire-and-forget by design.
+     */
+    flushPendingOperations(): Promise<void>;
+    getById(taskId: string): Promise<TaskHistoryEntry | undefined>;
+    list(options?: {
+        createdAfter?: number;
+        createdBefore?: number;
+        model?: string[];
+        projectPath?: string;
+        provider?: string[];
+        status?: TaskHistoryStatus[];
+        type?: string[];
+    }): Promise<TaskListItem[]>;
+    save(entry: TaskHistoryEntry): Promise<void>;
+    /**
+     * Construct the recovered (status='error') variant of a stale entry.
+     * Uses Zod parse to narrow to the discriminated 'error' branch without an `as` cast.
+     */
+    private buildRecovered;
+    private dataPath;
+    private doReadIndexDedup;
+    /**
+     * Schedule an asynchronous prune+compaction pass without blocking the caller.
+     * Deduplicates concurrent calls — only one pass runs at a time. If a save
+     * fires while a pass is in-flight, `pruneRequested` is set so a follow-up
+     * pass runs once the current one finishes (catches saves that landed mid-pass).
+     *
+     * Uses `setTimeout(fn, 0)` to defer the pass to the next macrotask, ensuring
+     * all pending microtasks (e.g. a follow-up `getById` that triggers M2.04
+     * recovery on the same task) drain before prune runs. Without this, the
+     * prune's own `readIndexDedup` could trigger a parallel recovery race.
+     */
+    private firePrune;
+    /**
+     * Drop all cached/in-flight reads of the index AND bump `indexEpoch` so any
+     * concurrent `doReadIndexDedup` pass that sampled the old epoch will skip
+     * its setCache step. Called by every write path (save / tombstone /
+     * recovery / compaction). Both layers must clear together — leaving
+     * `indexDedupInFlight` set after a write would let a list() call hit the
+     * pre-write promise and silently return the stale snapshot.
+     */
+    private invalidateIndexCaches;
+    private isStale;
+    /**
+     * Daemon-startup gate (C0): only entries whose `lastSavedAt` predates this
+     * daemon's boot are eligible for stale recovery. An entry written by the
+     * CURRENT daemon (post-boot) belongs to an in-memory active task whose
+     * lifecycle hook is still firing throttled saves — recovering it would
+     * ping-pong the on-disk state against the next save.
+     *
+     * Legacy lines (no `lastSavedAt`) fall back to the age-only check so
+     * existing index files from before this field was introduced behave as
+     * they did pre-C0.
+     */
+    private isStaleAndRecoverable;
+    /**
+     * Rewrite `_index.jsonl` keeping one line per live entry when bloat exceeds
+     * the configured ratio. Sweeps orphan data files (taskId not in live map)
+     * after the rewrite so the data dir stays in sync.
+     *
+     * Locked against `tombstoneAndUnlink` via `operationLock` — see B2 comment
+     * on the field declaration.
+     */
+    private maybeCompact;
+    /**
+     * Best-effort: write the recovered shape to the data file FIRST, then
+     * append the recovery line to the index. Sequential ordering matches
+     * `save()` and bounds the failure mode: if the data-file write fails,
+     * we return BEFORE the index append so the index never gains an orphan
+     * recovery line pointing to an unmutated data file (which would split
+     * `list()` from `getById()` — N1). Each step swallows its own error
+     * and logs via `transportLog`; never throws to caller.
+     */
+    private persistRecovery;
+    /**
+     * Phase 1 (age) + Phase 2 (count) prune. Builds the dead-taskId set from
+     * the dedup'd live map and delegates to `tombstoneAndUnlink`.
+     */
+    private prune;
+    private pruneAndCompact;
+    private readIndexDedup;
+    /**
+     * Detect data files whose index line was overwritten by the compaction
+     * rename (race window: save's `appendFile` landed BEFORE compaction's
+     * `rename`). For each, parse the data file and either:
+     *   - C1 path (current-boot save): re-append as live with `lastSavedAt = now`.
+     *   - N2 path (prior-boot orphan): delegate to `recoverViaTaskId`, which
+     *     mutates the data file to `status: 'error'` and persists the recovery
+     *     line. Without this gate, an old `'started'` orphan would be re-stamped
+     *     `lastSavedAt = Date.now()` and the C0 daemon-startup check would then
+     *     forever protect it as a live current-boot task.
+     *
+     * Distinguishing C1 vs N2: synthesize a probe `IndexDataLine` from the data
+     * file with no `lastSavedAt` and feed it through `isStaleAndRecoverable`.
+     * Recent saves (createdAt within `staleThresholdMs`) fall through to the
+     * C1 branch; old `'created'`/`'started'` orphans take the N2 branch.
+     */
+    private recoverPreRenameSaves;
+    /**
+     * Read the data file for a stale candidate, mutate to error, persist.
+     * Returns the summary projection of the recovered entry. Returns undefined
+     * if the data file is missing/corrupt. If the data file already shows a
+     * terminal status (a prior partial-success recovery), returns its projection
+     * without re-recovering — defensive idempotency restoration.
+     */
+    private recoverViaTaskId;
+    /**
+     * Atomically replace `_index.jsonl` with a fresh file containing exactly
+     * one line per live entry. Preserves the previous main as `_index.jsonl.bak`
+     * for one cycle. Sequence (best-effort .bak; atomic main swap):
+     *   1. Write `_index.jsonl.tmp` with the new content
+     *   2. copyFile `_index.jsonl` → `_index.jsonl.bak` (best-effort)
+     *   3. rename `_index.jsonl.tmp` → `_index.jsonl` (single atomic syscall)
+     */
+    private rewriteIndex;
+    /**
+     * After compaction, unlink any `data/tsk-${taskId}.json` whose taskId is
+     * not in the live map. Best-effort per file — ENOENT etc. is swallowed.
+     */
+    private sweepOrphanData;
+    /**
+     * Tombstone the given taskIds, then unlink each data file in parallel. Order
+     * matters: tombstone first so list/getById skip the entry even if the unlink
+     * fails (orphan data files are swept by M2.03 compaction). Reverse order
+     * would leave the row visible to list while getById returns undefined.
+     *
+     * Tombstones are appended in size-bounded chunks (each <`MAX_APPEND_CHUNK_BYTES`).
+     * POSIX guarantees nothing about regular-file write atomicity beyond pipes
+     * (PIPE_BUF applies to FIFOs/sockets only). Linux ext4 / macOS APFS happen
+     * to serialize appends per inode, but other filesystems may interleave a
+     * concurrent unlocked `save()` into the middle of a large multi-line write,
+     * corrupting a tombstone JSON line. Keeping every individual `appendFile`
+     * call comfortably under 4 KB lets the kernel page-cache write path treat
+     * each call as a single sector-level write, which most filesystems handle
+     * atomically.
+     *
+     * Locked against `maybeCompact` via `operationLock` (B2): if our appendFile
+     * landed mid-rewrite the tombstone would be wiped by `rename`, and our
+     * subsequent unlink would orphan the index entry `recoverPreRenameSaves`
+     * cannot detect (data file gone). The lock spans the entire chunked append
+     * + unlink sequence so all tombstones and unlinks are durable before any
+     * compaction consumes the snapshot.
+     */
+    private tombstoneAndUnlink;
+    private withOperationLock;
+    private writeAtomic;
+}
+export {};