@threadbase-sh/streamer 1.41.1 → 1.42.0

package/dist/index.d.cts

@@ -137,7 +137,7 @@ type SessionLifecycle = "attached" | "detached" | "orphaned" | "resumable" | "co
  * line and discarded, so a status reached by a timer expiring was indistinguishable
  * on the wire from one reached by observing a prompt marker.
  */
-type StatusSource = "spawn" | "prompt-marker" | "screen-marker" | "user-input" | "process-exit" | "timeout-fallback" | "quiet-fallback" | "shutdown";
+type StatusSource$1 = "spawn" | "prompt-marker" | "screen-marker" | "user-input" | "process-exit" | "timeout-fallback" | "quiet-fallback" | "shutdown";
 /**
  * How much to trust the status.
  *
@@ -150,7 +150,7 @@ type StatusSource = "spawn" | "prompt-marker" | "screen-marker" | "user-input" |
  */
 type StatusConfidence = "observed" | "inferred";
 /** Confidence implied by each source. Inference is exactly the timer-driven paths. */
-declare function confidenceForSource(source: StatusSource): StatusConfidence;
+declare function confidenceForSource(source: StatusSource$1): StatusConfidence;
 interface ManagedSession {
     id: string;
     provider?: ProviderName;
@@ -178,7 +178,7 @@ interface ManagedSession {
      * How `status` was derived, and when (C3). Confidence is derived from the
      * source via confidenceForSource — storing both would let them disagree.
      */
-    statusSource?: StatusSource;
+    statusSource?: StatusSource$1;
     statusUpdatedAt?: Date;
     filePath?: string;
     resumedFromConversationId?: string;
@@ -192,6 +192,13 @@ interface ManagedSession {
      * Cleared implicitly when a resume overwrites the stub with a real session.
      */
     rehydrated?: boolean;
+    /**
+     * What this session was doing when the streamer stopped it, for a stub whose
+     * `status` had to flatten to `idle`. Only ever set from a registry row whose
+     * `status_source` is `shutdown` — the one source that means "we ended this",
+     * as opposed to the agent finishing or a crash freezing the row mid-turn.
+     */
+    interruptedStatus?: "running" | "waiting_input";
     /**
      * Set once a live session's underlying persisted conversation file is
      * discovered after the fact (currently: fresh Codex sessions, whose
@@ -399,13 +406,22 @@ interface SessionResponse {
      * An `inferred` confidence means a timer expired and we assumed — not that
      * anything in the stream confirmed the state.
      */
-    statusSource?: StatusSource;
+    statusSource?: StatusSource$1;
     statusConfidence?: StatusConfidence;
     statusUpdatedAt?: string;
     lifecycle?: SessionLifecycle;
     /** How `lifecycle` was determined, so stale values are visible not implied. */
     lifecycleSource?: "spawn" | "exit" | "probe" | "reconcile";
     lifecycleUpdatedAt?: string;
+    /**
+     * ADDITIVE (plan Phase 5). What a recovered session was doing when the
+     * streamer stopped it, so a client can say "interrupted mid-response" instead
+     * of the `idle` its `status` is forced to report — a stub holds no PTY, and a
+     * novel SessionStatus value would be dropped by `?status=` filtering on
+     * already-shipped clients. Present only on rows whose `status_source` was
+     * `shutdown`; older clients ignore it.
+     */
+    interruptedStatus?: "running" | "waiting_input";
     failureReason?: string;
     pid?: number;
     sessionName?: string;
@@ -510,6 +526,15 @@ interface ServerConfig {
     scannerPersistent?: boolean;
     skipStartupWarmup?: boolean;
     ptyGracePeriodMs?: number;
+    /**
+     * Re-start interrupted sessions at boot instead of listing them for the user
+     * to tap (plan Phase 7). A boolean here rather than the tri-state the loader
+     * returns: by the time a ServerConfig is built the "never asked" case has
+     * already resolved to false. Precedence: explicit here → `auto_resume_on_boot`
+     * in server.yaml → false. Never enabled implicitly — it is the one setting
+     * that starts an agent nobody asked for in that moment.
+     */
+    autoResumeOnBoot?: boolean;
     cacheDir?: string;
     runtimeDbPath?: string;
     tailSize?: number;
@@ -542,6 +567,15 @@ interface StartSessionOptions {
     projectPath: string;
     projectName?: string;
     branch?: string;
+    /**
+     * Provider-side id to resume from, when it differs from `sessionId`. Codex
+     * keys a fresh session by a local placeholder UUID and only learns its real
+     * rollout id once it writes the file, so resuming needs the rollout id in
+     * argv while the session keeps the placeholder the client navigated to.
+     * Absent means "resume by the session id", which is what every Claude session
+     * does — PTYManager ignores this field entirely.
+     */
+    resumeId?: string;
     permissionMode?: PermissionMode;
     model?: string;
     effort?: EffortLevel;
@@ -1031,6 +1065,125 @@ declare class DevicesRepository {
     touch(deviceId: string, now?: number): void;
 }
 
+/**
+ * Durable registry of managed sessions (C1 Phase 2).
+ * See docs/architecture/2026-07-24-durable-session-runtime.md.
+ *
+ * Distinct from SessionsRepository, which wraps the in-memory SessionStore for
+ * the live request path. This one exists so session identity and provenance
+ * outlive the streamer process: without it, a restart loses startedAt,
+ * promptCount, sessionName, the Codex rollout binding, and failureReason, and
+ * the boot reconciler has nothing to reconcile against.
+ *
+ * Deliberately not stored here: the PTY output ring buffer and xterm screen.
+ * Their authoritative copy is the provider's JSONL, and writing 64KiB of ANSI
+ * on every chunk to duplicate it would be a write storm for no gain.
+ */
+/** How a persisted status was obtained — never inferred, always recorded. */
+type StatusSource = "spawn" | "transition" | "exit" | "shutdown" | "probe" | "reconcile";
+
+interface ManagedSessionRow {
+    session_id: string;
+    provider: string;
+    pid: number | null;
+    cmdline: string | null;
+    project_path: string;
+    project_name: string;
+    branch: string;
+    status: string;
+    status_source: string;
+    status_updated_at: number;
+    started_at: number;
+    completed_at: number | null;
+    last_activity_at: number | null;
+    prompt_count: number;
+    session_name: string | null;
+    project_id: string | null;
+    bound_conversation_id: string | null;
+    resumed_from_conversation_id: string | null;
+    failure_reason: string | null;
+    streamer_instance_id: string;
+    /**
+     * Which machine boot `pid` was recorded during (migration 002). Optional
+     * because rows written before it exists read back as null/absent, which the
+     * reconciler treats exactly like a mismatch — never like a match.
+     */
+    boot_token?: string | null;
+}
+interface RecordSpawnInput {
+    session: ManagedSession;
+    pid: number | null;
+    cmdline: string | null;
+    streamerInstanceId: string;
+}
+declare class ManagedSessionsRepository {
+    private upsertStmt;
+    private updateStatusStmt;
+    private bindStmt;
+    private getStmt;
+    private listNonTerminalStmt;
+    private listAllStmt;
+    private pruneTerminalStmt;
+    private listRecoverableStmt;
+    private deleteStmt;
+    constructor(db: Database.Database);
+    /** Record a session at spawn, or refresh every field of an existing row. */
+    recordSpawn({ session, pid, cmdline, streamerInstanceId }: RecordSpawnInput): void;
+    /**
+     * Persist a status transition. `source` is required rather than defaulted:
+     * a status whose provenance is unknown is the thing this table exists to
+     * prevent, and the reconciler reads it to decide how much to trust the value.
+     */
+    recordStatus(sessionId: string, status: SessionStatus, source: StatusSource, fields?: {
+        completedAt?: Date | null;
+        lastActivityAt?: Date | null;
+        promptCount?: number;
+        failureReason?: string | null;
+        /** Null/omitted keeps whatever is stored — it never clears a known name. */
+        sessionName?: string | null;
+    }): void;
+    /**
+     * Persist the Codex rollout id discovered after spawn.
+     *
+     * Its own statement rather than a `recordSpawn` re-run: the binding arrives
+     * while the session is live, and re-upserting would also rewrite `cmdline`
+     * with an id that is *not* in a fresh Codex process's argv, turning the
+     * reconciler's identity check into a false `orphaned`. Without this write the
+     * binding lives only in memory and dies with the streamer — which is the
+     * whole reason a restarted Codex session could not be resumed (G6).
+     */
+    recordBinding(sessionId: string, boundConversationId: string): void;
+    get(sessionId: string): ManagedSessionRow | null;
+    /**
+     * Rows with no recorded completion — the reconciler's probe set.
+     *
+     * Capped. Callers must compare the result length against the limit and say so
+     * when it clips: a silently truncated probe set reads as "we checked
+     * everything" when it did not.
+     */
+    listNonTerminal(limit?: number): ManagedSessionRow[];
+    /** Every row, most recently touched first, for the diagnostics surface. */
+    listAll(limit?: number): ManagedSessionRow[];
+    /**
+     * Delete terminal rows older than `olderThanMs`, returning how many went.
+     *
+     * Only rows carrying a `completed_at` are eligible, so nothing the reconciler
+     * or rehydrator might still want is reachable from here — a row without one
+     * is by definition unfinished business, however old it looks.
+     */
+    pruneTerminal(olderThanMs?: number): number;
+    /**
+     * Rows a restart could bring back: still open, or closed by our own shutdown,
+     * and touched no longer ago than `sinceMs`. Newest first, capped — the caller
+     * decides which of these actually deserve rehydrating (`shouldRehydrate`).
+     */
+    listRecoverable({ sinceMs, limit }: {
+        sinceMs: number;
+        limit: number;
+    }): ManagedSessionRow[];
+    delete(sessionId: string): void;
+}
+
 /**
  * Persisted Project row. Mirrors the projects SQLite table.
  */
@@ -1420,6 +1573,14 @@ declare class CacheIntegrityMonitor {
     resolve(fingerprint: string, action: ResolveAction, ids?: string[]): Promise<ResolveResult>;
 }
 
+/** Result for a single registry row. Pure data — nothing here acts. */
+interface ReconcileVerdict {
+    sessionId: string;
+    lifecycle: SessionLifecycle;
+    /** Why this verdict was reached, for logs and the diagnostics surface. */
+    reason: string;
+}
+
 type ApiDeps = {
     apiKey: string;
     localNoAuth: boolean;
@@ -1461,6 +1622,10 @@ type ApiDeps = {
     cacheMetadataRepo: () => CacheMetadataRepository | null;
     /** Authoritative session registry (~/.threadbase/runtime.db). Null when it failed to open. */
     runtimeStore: () => RuntimeStore | null;
+    /** Rows of that registry. Null when it failed to open. */
+    managedSessionsRepo: () => ManagedSessionsRepository | null;
+    /** This boot's reconcile verdicts, by session id. Empty before it has run. */
+    sessionVerdicts: () => Map<string, ReconcileVerdict>;
     ptyAttachedIds: () => Set<string>;
     handleListSessions: (url: URL, res: ServerResponse) => Promise<void>;
     handleSessionsCount: (res: ServerResponse) => void;
@@ -1673,7 +1838,7 @@ declare class StreamerServer {
     private lastAgentChunkAt;
     private terminalSeq;
     private idempotency;
-    private sessionLifecycles;
+    private sessionVerdicts;
     private idleReaperTimer;
     private clientIdToWs;
     private wsToClientId;
@@ -1755,6 +1920,14 @@ declare class StreamerServer {
      * signals anything. `orphaned` is a report, not a cleanup trigger.
      */
     private reconcilePreviousSessions;
+    /**
+     * Drop finished sessions the registry has held long enough (plan Phase 4).
+     *
+     * The registry is authoritative and never rebuilt from the cache, so nothing
+     * else would ever remove a row: without this it grows for the life of the
+     * install, and every boot pays for rows about sessions from months ago.
+     */
+    private pruneTerminalSessions;
     /**
      * Seed the session list with what previous runs left behind (persistence plan
      * Phase 1, gaps G1/G2/G8).
@@ -1980,6 +2153,19 @@ declare class StreamerServer {
     private handleListSessions;
     private handleGetSession;
     private handleResume;
+    /**
+     * Resume a session, from an HTTP request or from the boot path.
+     *
+     * Extracted from `handleResume` so both callers hit the **same collision
+     * probe** (plan Phase 7c). The probe is what stops this streamer attaching to
+     * a conversation an external terminal already owns; a second, hand-adapted
+     * copy of this sequence in the boot path is how two agents end up appending
+     * to one JSONL at 4am with nobody watching.
+     *
+     * Returns a typed reason rather than writing a response, so the HTTP caller
+     * maps it to a status code and the boot caller logs it.
+     */
+    private resumeSession;
     private enrichResumedSessionAsync;
     private handleSendInput;
     private processJsonlQuestions;
@@ -2096,4 +2282,4 @@ declare class ConversationWatcher {
     private readNewLines;
 }
 
-export { type AgentClient, type AgentClientOpts, type AgentConfig, type AppendArgs, type AskOption, type AskQuestion, CLAUDE_CODE_PROVIDER, CODEX_CLI_PROVIDER, type CacheAlertResolveAction, type ConversationListResponse, ConversationWatcher, type ConversationWriter, type DbConfig, type DiscoveredProcess, LiveSessionManager, type ManagedSession, PTYManager, type PTYManagerOptions, type PermissionOption, type ProcessLiveness, type ProgressDedupeLRU, type ProviderName, type ServerConfig, type ServerWarmingUpResponse, type ServerWarmupState, type SessionActivity, type SessionCursor, type SessionLifecycle, type SessionListPage, type SessionListQuery, type SessionOwnership, type SessionResponse, type SessionRunner, type SessionSortKey, type SessionStatus, SessionStore, type SortOrder, type StartFreshSessionOptions, type StartSessionOptions, type StatusConfidence, type StatusSource, StreamerServer, type UserMessage, WSHub, type WSMessage, confidenceForSource, createAgentClient, createConversationWriter, createPool, createProgressDedupeLRU, createProgressRoutes, discoverClaudeProcesses, generateApiKey, getDbConfig, isDbEnabled, isProviderName, isProviderResumable, loadOrCreateApiKey, maskConnectionString, readAgentConfig, validateApiKey };
+export { type AgentClient, type AgentClientOpts, type AgentConfig, type AppendArgs, type AskOption, type AskQuestion, CLAUDE_CODE_PROVIDER, CODEX_CLI_PROVIDER, type CacheAlertResolveAction, type ConversationListResponse, ConversationWatcher, type ConversationWriter, type DbConfig, type DiscoveredProcess, LiveSessionManager, type ManagedSession, PTYManager, type PTYManagerOptions, type PermissionOption, type ProcessLiveness, type ProgressDedupeLRU, type ProviderName, type ServerConfig, type ServerWarmingUpResponse, type ServerWarmupState, type SessionActivity, type SessionCursor, type SessionLifecycle, type SessionListPage, type SessionListQuery, type SessionOwnership, type SessionResponse, type SessionRunner, type SessionSortKey, type SessionStatus, SessionStore, type SortOrder, type StartFreshSessionOptions, type StartSessionOptions, type StatusConfidence, type StatusSource$1 as StatusSource, StreamerServer, type UserMessage, WSHub, type WSMessage, confidenceForSource, createAgentClient, createConversationWriter, createPool, createProgressDedupeLRU, createProgressRoutes, discoverClaudeProcesses, generateApiKey, getDbConfig, isDbEnabled, isProviderName, isProviderResumable, loadOrCreateApiKey, maskConnectionString, readAgentConfig, validateApiKey };

package/dist/index.d.ts

@@ -137,7 +137,7 @@ type SessionLifecycle = "attached" | "detached" | "orphaned" | "resumable" | "co
  * line and discarded, so a status reached by a timer expiring was indistinguishable
  * on the wire from one reached by observing a prompt marker.
  */
-type StatusSource = "spawn" | "prompt-marker" | "screen-marker" | "user-input" | "process-exit" | "timeout-fallback" | "quiet-fallback" | "shutdown";
+type StatusSource$1 = "spawn" | "prompt-marker" | "screen-marker" | "user-input" | "process-exit" | "timeout-fallback" | "quiet-fallback" | "shutdown";
 /**
  * How much to trust the status.
  *
@@ -150,7 +150,7 @@ type StatusSource = "spawn" | "prompt-marker" | "screen-marker" | "user-input" |
  */
 type StatusConfidence = "observed" | "inferred";
 /** Confidence implied by each source. Inference is exactly the timer-driven paths. */
-declare function confidenceForSource(source: StatusSource): StatusConfidence;
+declare function confidenceForSource(source: StatusSource$1): StatusConfidence;
 interface ManagedSession {
     id: string;
     provider?: ProviderName;
@@ -178,7 +178,7 @@ interface ManagedSession {
      * How `status` was derived, and when (C3). Confidence is derived from the
      * source via confidenceForSource — storing both would let them disagree.
      */
-    statusSource?: StatusSource;
+    statusSource?: StatusSource$1;
     statusUpdatedAt?: Date;
     filePath?: string;
     resumedFromConversationId?: string;
@@ -192,6 +192,13 @@ interface ManagedSession {
      * Cleared implicitly when a resume overwrites the stub with a real session.
      */
     rehydrated?: boolean;
+    /**
+     * What this session was doing when the streamer stopped it, for a stub whose
+     * `status` had to flatten to `idle`. Only ever set from a registry row whose
+     * `status_source` is `shutdown` — the one source that means "we ended this",
+     * as opposed to the agent finishing or a crash freezing the row mid-turn.
+     */
+    interruptedStatus?: "running" | "waiting_input";
     /**
      * Set once a live session's underlying persisted conversation file is
      * discovered after the fact (currently: fresh Codex sessions, whose
@@ -399,13 +406,22 @@ interface SessionResponse {
      * An `inferred` confidence means a timer expired and we assumed — not that
      * anything in the stream confirmed the state.
      */
-    statusSource?: StatusSource;
+    statusSource?: StatusSource$1;
     statusConfidence?: StatusConfidence;
     statusUpdatedAt?: string;
     lifecycle?: SessionLifecycle;
     /** How `lifecycle` was determined, so stale values are visible not implied. */
     lifecycleSource?: "spawn" | "exit" | "probe" | "reconcile";
     lifecycleUpdatedAt?: string;
+    /**
+     * ADDITIVE (plan Phase 5). What a recovered session was doing when the
+     * streamer stopped it, so a client can say "interrupted mid-response" instead
+     * of the `idle` its `status` is forced to report — a stub holds no PTY, and a
+     * novel SessionStatus value would be dropped by `?status=` filtering on
+     * already-shipped clients. Present only on rows whose `status_source` was
+     * `shutdown`; older clients ignore it.
+     */
+    interruptedStatus?: "running" | "waiting_input";
     failureReason?: string;
     pid?: number;
     sessionName?: string;
@@ -510,6 +526,15 @@ interface ServerConfig {
     scannerPersistent?: boolean;
     skipStartupWarmup?: boolean;
     ptyGracePeriodMs?: number;
+    /**
+     * Re-start interrupted sessions at boot instead of listing them for the user
+     * to tap (plan Phase 7). A boolean here rather than the tri-state the loader
+     * returns: by the time a ServerConfig is built the "never asked" case has
+     * already resolved to false. Precedence: explicit here → `auto_resume_on_boot`
+     * in server.yaml → false. Never enabled implicitly — it is the one setting
+     * that starts an agent nobody asked for in that moment.
+     */
+    autoResumeOnBoot?: boolean;
     cacheDir?: string;
     runtimeDbPath?: string;
     tailSize?: number;
@@ -542,6 +567,15 @@ interface StartSessionOptions {
     projectPath: string;
     projectName?: string;
     branch?: string;
+    /**
+     * Provider-side id to resume from, when it differs from `sessionId`. Codex
+     * keys a fresh session by a local placeholder UUID and only learns its real
+     * rollout id once it writes the file, so resuming needs the rollout id in
+     * argv while the session keeps the placeholder the client navigated to.
+     * Absent means "resume by the session id", which is what every Claude session
+     * does — PTYManager ignores this field entirely.
+     */
+    resumeId?: string;
     permissionMode?: PermissionMode;
     model?: string;
     effort?: EffortLevel;
@@ -1031,6 +1065,125 @@ declare class DevicesRepository {
     touch(deviceId: string, now?: number): void;
 }
 
+/**
+ * Durable registry of managed sessions (C1 Phase 2).
+ * See docs/architecture/2026-07-24-durable-session-runtime.md.
+ *
+ * Distinct from SessionsRepository, which wraps the in-memory SessionStore for
+ * the live request path. This one exists so session identity and provenance
+ * outlive the streamer process: without it, a restart loses startedAt,
+ * promptCount, sessionName, the Codex rollout binding, and failureReason, and
+ * the boot reconciler has nothing to reconcile against.
+ *
+ * Deliberately not stored here: the PTY output ring buffer and xterm screen.
+ * Their authoritative copy is the provider's JSONL, and writing 64KiB of ANSI
+ * on every chunk to duplicate it would be a write storm for no gain.
+ */
+/** How a persisted status was obtained — never inferred, always recorded. */
+type StatusSource = "spawn" | "transition" | "exit" | "shutdown" | "probe" | "reconcile";
+
+interface ManagedSessionRow {
+    session_id: string;
+    provider: string;
+    pid: number | null;
+    cmdline: string | null;
+    project_path: string;
+    project_name: string;
+    branch: string;
+    status: string;
+    status_source: string;
+    status_updated_at: number;
+    started_at: number;
+    completed_at: number | null;
+    last_activity_at: number | null;
+    prompt_count: number;
+    session_name: string | null;
+    project_id: string | null;
+    bound_conversation_id: string | null;
+    resumed_from_conversation_id: string | null;
+    failure_reason: string | null;
+    streamer_instance_id: string;
+    /**
+     * Which machine boot `pid` was recorded during (migration 002). Optional
+     * because rows written before it exists read back as null/absent, which the
+     * reconciler treats exactly like a mismatch — never like a match.
+     */
+    boot_token?: string | null;
+}
+interface RecordSpawnInput {
+    session: ManagedSession;
+    pid: number | null;
+    cmdline: string | null;
+    streamerInstanceId: string;
+}
+declare class ManagedSessionsRepository {
+    private upsertStmt;
+    private updateStatusStmt;
+    private bindStmt;
+    private getStmt;
+    private listNonTerminalStmt;
+    private listAllStmt;
+    private pruneTerminalStmt;
+    private listRecoverableStmt;
+    private deleteStmt;
+    constructor(db: Database.Database);
+    /** Record a session at spawn, or refresh every field of an existing row. */
+    recordSpawn({ session, pid, cmdline, streamerInstanceId }: RecordSpawnInput): void;
+    /**
+     * Persist a status transition. `source` is required rather than defaulted:
+     * a status whose provenance is unknown is the thing this table exists to
+     * prevent, and the reconciler reads it to decide how much to trust the value.
+     */
+    recordStatus(sessionId: string, status: SessionStatus, source: StatusSource, fields?: {
+        completedAt?: Date | null;
+        lastActivityAt?: Date | null;
+        promptCount?: number;
+        failureReason?: string | null;
+        /** Null/omitted keeps whatever is stored — it never clears a known name. */
+        sessionName?: string | null;
+    }): void;
+    /**
+     * Persist the Codex rollout id discovered after spawn.
+     *
+     * Its own statement rather than a `recordSpawn` re-run: the binding arrives
+     * while the session is live, and re-upserting would also rewrite `cmdline`
+     * with an id that is *not* in a fresh Codex process's argv, turning the
+     * reconciler's identity check into a false `orphaned`. Without this write the
+     * binding lives only in memory and dies with the streamer — which is the
+     * whole reason a restarted Codex session could not be resumed (G6).
+     */
+    recordBinding(sessionId: string, boundConversationId: string): void;
+    get(sessionId: string): ManagedSessionRow | null;
+    /**
+     * Rows with no recorded completion — the reconciler's probe set.
+     *
+     * Capped. Callers must compare the result length against the limit and say so
+     * when it clips: a silently truncated probe set reads as "we checked
+     * everything" when it did not.
+     */
+    listNonTerminal(limit?: number): ManagedSessionRow[];
+    /** Every row, most recently touched first, for the diagnostics surface. */
+    listAll(limit?: number): ManagedSessionRow[];
+    /**
+     * Delete terminal rows older than `olderThanMs`, returning how many went.
+     *
+     * Only rows carrying a `completed_at` are eligible, so nothing the reconciler
+     * or rehydrator might still want is reachable from here — a row without one
+     * is by definition unfinished business, however old it looks.
+     */
+    pruneTerminal(olderThanMs?: number): number;
+    /**
+     * Rows a restart could bring back: still open, or closed by our own shutdown,
+     * and touched no longer ago than `sinceMs`. Newest first, capped — the caller
+     * decides which of these actually deserve rehydrating (`shouldRehydrate`).
+     */
+    listRecoverable({ sinceMs, limit }: {
+        sinceMs: number;
+        limit: number;
+    }): ManagedSessionRow[];
+    delete(sessionId: string): void;
+}
+
 /**
  * Persisted Project row. Mirrors the projects SQLite table.
  */
@@ -1420,6 +1573,14 @@ declare class CacheIntegrityMonitor {
     resolve(fingerprint: string, action: ResolveAction, ids?: string[]): Promise<ResolveResult>;
 }
 
+/** Result for a single registry row. Pure data — nothing here acts. */
+interface ReconcileVerdict {
+    sessionId: string;
+    lifecycle: SessionLifecycle;
+    /** Why this verdict was reached, for logs and the diagnostics surface. */
+    reason: string;
+}
+
 type ApiDeps = {
     apiKey: string;
     localNoAuth: boolean;
@@ -1461,6 +1622,10 @@ type ApiDeps = {
     cacheMetadataRepo: () => CacheMetadataRepository | null;
     /** Authoritative session registry (~/.threadbase/runtime.db). Null when it failed to open. */
     runtimeStore: () => RuntimeStore | null;
+    /** Rows of that registry. Null when it failed to open. */
+    managedSessionsRepo: () => ManagedSessionsRepository | null;
+    /** This boot's reconcile verdicts, by session id. Empty before it has run. */
+    sessionVerdicts: () => Map<string, ReconcileVerdict>;
     ptyAttachedIds: () => Set<string>;
     handleListSessions: (url: URL, res: ServerResponse) => Promise<void>;
     handleSessionsCount: (res: ServerResponse) => void;
@@ -1673,7 +1838,7 @@ declare class StreamerServer {
     private lastAgentChunkAt;
     private terminalSeq;
     private idempotency;
-    private sessionLifecycles;
+    private sessionVerdicts;
     private idleReaperTimer;
     private clientIdToWs;
     private wsToClientId;
@@ -1755,6 +1920,14 @@ declare class StreamerServer {
      * signals anything. `orphaned` is a report, not a cleanup trigger.
      */
     private reconcilePreviousSessions;
+    /**
+     * Drop finished sessions the registry has held long enough (plan Phase 4).
+     *
+     * The registry is authoritative and never rebuilt from the cache, so nothing
+     * else would ever remove a row: without this it grows for the life of the
+     * install, and every boot pays for rows about sessions from months ago.
+     */
+    private pruneTerminalSessions;
     /**
      * Seed the session list with what previous runs left behind (persistence plan
      * Phase 1, gaps G1/G2/G8).
@@ -1980,6 +2153,19 @@ declare class StreamerServer {
     private handleListSessions;
     private handleGetSession;
     private handleResume;
+    /**
+     * Resume a session, from an HTTP request or from the boot path.
+     *
+     * Extracted from `handleResume` so both callers hit the **same collision
+     * probe** (plan Phase 7c). The probe is what stops this streamer attaching to
+     * a conversation an external terminal already owns; a second, hand-adapted
+     * copy of this sequence in the boot path is how two agents end up appending
+     * to one JSONL at 4am with nobody watching.
+     *
+     * Returns a typed reason rather than writing a response, so the HTTP caller
+     * maps it to a status code and the boot caller logs it.
+     */
+    private resumeSession;
     private enrichResumedSessionAsync;
     private handleSendInput;
     private processJsonlQuestions;
@@ -2096,4 +2282,4 @@ declare class ConversationWatcher {
     private readNewLines;
 }
 
-export { type AgentClient, type AgentClientOpts, type AgentConfig, type AppendArgs, type AskOption, type AskQuestion, CLAUDE_CODE_PROVIDER, CODEX_CLI_PROVIDER, type CacheAlertResolveAction, type ConversationListResponse, ConversationWatcher, type ConversationWriter, type DbConfig, type DiscoveredProcess, LiveSessionManager, type ManagedSession, PTYManager, type PTYManagerOptions, type PermissionOption, type ProcessLiveness, type ProgressDedupeLRU, type ProviderName, type ServerConfig, type ServerWarmingUpResponse, type ServerWarmupState, type SessionActivity, type SessionCursor, type SessionLifecycle, type SessionListPage, type SessionListQuery, type SessionOwnership, type SessionResponse, type SessionRunner, type SessionSortKey, type SessionStatus, SessionStore, type SortOrder, type StartFreshSessionOptions, type StartSessionOptions, type StatusConfidence, type StatusSource, StreamerServer, type UserMessage, WSHub, type WSMessage, confidenceForSource, createAgentClient, createConversationWriter, createPool, createProgressDedupeLRU, createProgressRoutes, discoverClaudeProcesses, generateApiKey, getDbConfig, isDbEnabled, isProviderName, isProviderResumable, loadOrCreateApiKey, maskConnectionString, readAgentConfig, validateApiKey };
+export { type AgentClient, type AgentClientOpts, type AgentConfig, type AppendArgs, type AskOption, type AskQuestion, CLAUDE_CODE_PROVIDER, CODEX_CLI_PROVIDER, type CacheAlertResolveAction, type ConversationListResponse, ConversationWatcher, type ConversationWriter, type DbConfig, type DiscoveredProcess, LiveSessionManager, type ManagedSession, PTYManager, type PTYManagerOptions, type PermissionOption, type ProcessLiveness, type ProgressDedupeLRU, type ProviderName, type ServerConfig, type ServerWarmingUpResponse, type ServerWarmupState, type SessionActivity, type SessionCursor, type SessionLifecycle, type SessionListPage, type SessionListQuery, type SessionOwnership, type SessionResponse, type SessionRunner, type SessionSortKey, type SessionStatus, SessionStore, type SortOrder, type StartFreshSessionOptions, type StartSessionOptions, type StatusConfidence, type StatusSource$1 as StatusSource, StreamerServer, type UserMessage, WSHub, type WSMessage, confidenceForSource, createAgentClient, createConversationWriter, createPool, createProgressDedupeLRU, createProgressRoutes, discoverClaudeProcesses, generateApiKey, getDbConfig, isDbEnabled, isProviderName, isProviderResumable, loadOrCreateApiKey, maskConnectionString, readAgentConfig, validateApiKey };