@threadbase-sh/streamer 1.40.0 → 1.41.0

package/dist/index.d.cts

@@ -182,6 +182,16 @@ interface ManagedSession {
     statusUpdatedAt?: Date;
     filePath?: string;
     resumedFromConversationId?: string;
+    /**
+     * This session was seeded from the durable registry at boot, not spawned by
+     * this run — there is no PTY behind it and never was one in this process.
+     *
+     * INTERNAL. It never reaches the wire: `managedToResponse` translates it into
+     * the already-defined `ownership: "historical"` + `lifecycle: "resumable"`
+     * pair, so no client needs to learn a new field to render a recovered session.
+     * Cleared implicitly when a resume overwrites the stub with a real session.
+     */
+    rehydrated?: boolean;
     /**
      * Set once a live session's underlying persisted conversation file is
      * discovered after the fact (currently: fresh Codex sessions, whose
@@ -501,6 +511,7 @@ interface ServerConfig {
     skipStartupWarmup?: boolean;
     ptyGracePeriodMs?: number;
     cacheDir?: string;
+    runtimeDbPath?: string;
     tailSize?: number;
     directoryScanDebounceMs?: number;
     defaultSystemPrompt?: string;
@@ -1251,6 +1262,41 @@ declare class SessionsRepository {
     listManagedSessions(): ManagedSession[];
 }
 
+/**
+ * `~/.threadbase/runtime.db` — the authoritative, non-derived half of the
+ * streamer's SQLite state.
+ *
+ * Deliberately a separate file from `cache/cache.db`, and deliberately not
+ * under `cache/`. The conversation cache is rebuildable from the provider
+ * JSONLs at any time, which is why "delete the cache and restart" is reasonable
+ * support advice and why the integrity monitor offers a reset-and-rescan
+ * action. The managed-session registry is not rebuildable from anything on
+ * disk, so it must not sit one plausible instruction away from deletion — nor
+ * share a handle whose failure (a better-sqlite3 ABI mismatch, most commonly)
+ * would silently disable session persistence along with the cache.
+ *
+ * Runs its own migrations from `src/db/runtime-migrations/`, tracked in this
+ * file's own `schema_migrations` table.
+ */
+declare class RuntimeStore {
+    private readonly db;
+    private constructor();
+    static open(dbPath: string, migrationsDir?: string): RuntimeStore;
+    getDatabase(): Database.Database;
+    /**
+     * One-time move of `managed_sessions` rows out of a pre-split `cache.db`.
+     *
+     * Non-destructive by design: the source table is left in place so an older
+     * streamer rolled back onto the same machine still finds its registry. Runs
+     * only when this file's table is empty, so a second boot is a no-op rather
+     * than a re-copy that would resurrect rows deleted since.
+     *
+     * Returns the number of rows copied.
+     */
+    importLegacyManagedSessions(source: Database.Database): number;
+    close(): void;
+}
+
 declare class LiveSessionManager {
     private runners;
     constructor(options?: PTYManagerOptions);
@@ -1413,6 +1459,8 @@ type ApiDeps = {
     conversationsRepo: () => ConversationsRepository | null;
     sessionsRepo: () => SessionsRepository | null;
     cacheMetadataRepo: () => CacheMetadataRepository | null;
+    /** Authoritative session registry (~/.threadbase/runtime.db). Null when it failed to open. */
+    runtimeStore: () => RuntimeStore | null;
     ptyAttachedIds: () => Set<string>;
     handleListSessions: (url: URL, res: ServerResponse) => Promise<void>;
     handleSessionsCount: (res: ServerResponse) => void;
@@ -1632,6 +1680,7 @@ declare class StreamerServer {
     private conversationsRepo;
     private sessionsRepo;
     private managedSessionsRepo;
+    private runtimeStore;
     private readonly streamerInstanceId;
     private cacheMetadataRepo;
     private pushRepo;
@@ -1641,6 +1690,7 @@ declare class StreamerServer {
     private liveActivityRenewal;
     private discoveryCache;
     private cacheDir;
+    private runtimeDbPath;
     private tailSize;
     private directoryDebounceMs;
     private markScannerStaleDebounced;
@@ -1702,6 +1752,22 @@ declare class StreamerServer {
      * signals anything. `orphaned` is a report, not a cleanup trigger.
      */
     private reconcilePreviousSessions;
+    /**
+     * Seed the session list with what previous runs left behind (persistence plan
+     * Phase 1, gaps G1/G2/G8).
+     *
+     * Reconciliation classifies rows and stops there; a verdict is overlaid onto a
+     * SessionResponse that already exists, and after a clean restart none does —
+     * `SessionStore` starts empty. So the user's session did not become
+     * `resumable`, it became *absent*. This is the half that puts it back.
+     *
+     * The seeded stubs hold no PTY and are never handed to `LiveSessionManager`,
+     * so `reapIdleSessions` and `startGraceTimer` — both of which iterate
+     * `ptyManager.listSessions()` — cannot observe them. A later resume calls
+     * `sessionStore.addManaged` with the real session, which overwrites the stub
+     * by id rather than duplicating it.
+     */
+    private rehydratePreviousSessions;
     /**
      * Pick a token guaranteed to appear in the spawned process's argv, for the
      * reconciler's pid-reuse guard.

package/dist/index.d.ts

@@ -182,6 +182,16 @@ interface ManagedSession {
     statusUpdatedAt?: Date;
     filePath?: string;
     resumedFromConversationId?: string;
+    /**
+     * This session was seeded from the durable registry at boot, not spawned by
+     * this run — there is no PTY behind it and never was one in this process.
+     *
+     * INTERNAL. It never reaches the wire: `managedToResponse` translates it into
+     * the already-defined `ownership: "historical"` + `lifecycle: "resumable"`
+     * pair, so no client needs to learn a new field to render a recovered session.
+     * Cleared implicitly when a resume overwrites the stub with a real session.
+     */
+    rehydrated?: boolean;
     /**
      * Set once a live session's underlying persisted conversation file is
      * discovered after the fact (currently: fresh Codex sessions, whose
@@ -501,6 +511,7 @@ interface ServerConfig {
     skipStartupWarmup?: boolean;
     ptyGracePeriodMs?: number;
     cacheDir?: string;
+    runtimeDbPath?: string;
     tailSize?: number;
     directoryScanDebounceMs?: number;
     defaultSystemPrompt?: string;
@@ -1251,6 +1262,41 @@ declare class SessionsRepository {
     listManagedSessions(): ManagedSession[];
 }
 
+/**
+ * `~/.threadbase/runtime.db` — the authoritative, non-derived half of the
+ * streamer's SQLite state.
+ *
+ * Deliberately a separate file from `cache/cache.db`, and deliberately not
+ * under `cache/`. The conversation cache is rebuildable from the provider
+ * JSONLs at any time, which is why "delete the cache and restart" is reasonable
+ * support advice and why the integrity monitor offers a reset-and-rescan
+ * action. The managed-session registry is not rebuildable from anything on
+ * disk, so it must not sit one plausible instruction away from deletion — nor
+ * share a handle whose failure (a better-sqlite3 ABI mismatch, most commonly)
+ * would silently disable session persistence along with the cache.
+ *
+ * Runs its own migrations from `src/db/runtime-migrations/`, tracked in this
+ * file's own `schema_migrations` table.
+ */
+declare class RuntimeStore {
+    private readonly db;
+    private constructor();
+    static open(dbPath: string, migrationsDir?: string): RuntimeStore;
+    getDatabase(): Database.Database;
+    /**
+     * One-time move of `managed_sessions` rows out of a pre-split `cache.db`.
+     *
+     * Non-destructive by design: the source table is left in place so an older
+     * streamer rolled back onto the same machine still finds its registry. Runs
+     * only when this file's table is empty, so a second boot is a no-op rather
+     * than a re-copy that would resurrect rows deleted since.
+     *
+     * Returns the number of rows copied.
+     */
+    importLegacyManagedSessions(source: Database.Database): number;
+    close(): void;
+}
+
 declare class LiveSessionManager {
     private runners;
     constructor(options?: PTYManagerOptions);
@@ -1413,6 +1459,8 @@ type ApiDeps = {
     conversationsRepo: () => ConversationsRepository | null;
     sessionsRepo: () => SessionsRepository | null;
     cacheMetadataRepo: () => CacheMetadataRepository | null;
+    /** Authoritative session registry (~/.threadbase/runtime.db). Null when it failed to open. */
+    runtimeStore: () => RuntimeStore | null;
     ptyAttachedIds: () => Set<string>;
     handleListSessions: (url: URL, res: ServerResponse) => Promise<void>;
     handleSessionsCount: (res: ServerResponse) => void;
@@ -1632,6 +1680,7 @@ declare class StreamerServer {
     private conversationsRepo;
     private sessionsRepo;
     private managedSessionsRepo;
+    private runtimeStore;
     private readonly streamerInstanceId;
     private cacheMetadataRepo;
     private pushRepo;
@@ -1641,6 +1690,7 @@ declare class StreamerServer {
     private liveActivityRenewal;
     private discoveryCache;
     private cacheDir;
+    private runtimeDbPath;
     private tailSize;
     private directoryDebounceMs;
     private markScannerStaleDebounced;
@@ -1702,6 +1752,22 @@ declare class StreamerServer {
      * signals anything. `orphaned` is a report, not a cleanup trigger.
      */
     private reconcilePreviousSessions;
+    /**
+     * Seed the session list with what previous runs left behind (persistence plan
+     * Phase 1, gaps G1/G2/G8).
+     *
+     * Reconciliation classifies rows and stops there; a verdict is overlaid onto a
+     * SessionResponse that already exists, and after a clean restart none does —
+     * `SessionStore` starts empty. So the user's session did not become
+     * `resumable`, it became *absent*. This is the half that puts it back.
+     *
+     * The seeded stubs hold no PTY and are never handed to `LiveSessionManager`,
+     * so `reapIdleSessions` and `startGraceTimer` — both of which iterate
+     * `ptyManager.listSessions()` — cannot observe them. A later resume calls
+     * `sessionStore.addManaged` with the real session, which overwrites the stub
+     * by id rather than duplicating it.
+     */
+    private rehydratePreviousSessions;
     /**
      * Pick a token guaranteed to appear in the spawned process's argv, for the
      * reconciler's pid-reuse guard.