@maudecode/talaria-web 1.17.2 → 1.19.0

package/dist/sessions/service.d.ts

@@ -3,7 +3,7 @@
  * detail payload, list and search, and every mutation with its guards.
  * Runtime concerns owned by other domains arrive through `SessionServiceDeps`.
  */
-import type { PendingSteer } from '@maudecode/talaria-web-contracts';
+import type { AgentStorage, ChatReadiness, PendingSteer, RecoveryAudit, RunStatus, SessionGoal, SessionNotice, RecoveryRepair, SidecarResult } from '@maudecode/talaria-web-contracts';
 import type { RunJournal } from './journal.js';
 import type { DraftStore } from './drafts.js';
 import type { SessionEventBus } from './events.js';
@@ -11,7 +11,7 @@ import { type ListParams, type ListResponse, type Row, type RuntimeOverlay } fro
 import { Session, titleFrom, type Message } from './session.js';
 import { type SessionStore } from './store.js';
 import { type ClaudeCodeSessionSource } from './claude-code.js';
-import { type StateDbRead } from './state-db.js';
+import { type StateDbRead, type StateDbSessionSource } from './state-db.js';
 import { type CompressionJob } from './compress.js';
 import { type SidecarLike } from '../sidecar/client.js';
 import { type ToolResultView } from './merge.js';
@@ -21,6 +21,7 @@ import { type ShareStore } from './shares.js';
 import { type MediaAccessDeps } from '../workspace/media.js';
 import { type MediaProjection } from '../workspace/media-refs.js';
 import type { ProjectStore } from '../projects.js';
+import type { GatewaySessions } from './gateway-sessions.js';
 export declare class HttpFailure extends Error {
     readonly status: number;
     readonly extra: Record<string, unknown>;
@@ -31,7 +32,15 @@ export declare class HttpFailure extends Error {
  * mutates anything. Any other failure of the check is not a verdict and lets the caller proceed.
  */
 export declare function ensureAgentRuntimeCurrent(sidecar: SidecarLike | null): Promise<void>;
+/**
+ * TAL-951: whether a chat turn would be admitted now. Ready and source-stale incompatible sidecars both run turn
+ * admission's live check: recovery state can change after the handshake. A check
+ * that cannot answer fails closed as `sidecar_unavailable`.
+ */
+export declare function currentChatReadiness(sidecar: SidecarLike | null): Promise<ChatReadiness>;
 export interface SessionServiceDeps {
+    /** TAL-259: epoch seconds of the state directory's `recovery_stamping_since` marker. */
+    recoveryStampingSince: () => Promise<number>;
     /** TAL-255: the Agent sidecar for manual compression (`chat.compress`); null while it is down. */
     sidecar?: () => SidecarLike | null;
     /** Detached sidecar work for a profile: deletion waits for the returned release, so the home outlives the work. */
@@ -39,7 +48,8 @@ export interface SessionServiceDeps {
     /** A profile whose deletion has started takes no new detached work. */
     profileDeleting?: (profile: string | null) => boolean;
     /** TAL-372: the session's background work receipts, for the delegation rows that started them. */
-    backgroundReceipts?: (sid: string) => Receipt[];
+    backgroundReceipts?: (sid: string) => Receipt[] | Promise<Receipt[]>;
+    backgroundPending?: (sid: string) => Promise<Set<string>>;
     store: SessionStore;
     drafts: DraftStore;
     events: SessionEventBus;
@@ -62,21 +72,34 @@ export interface SessionServiceDeps {
         journalDegraded: (streamId: string) => boolean;
         /** TAL-424: the live stream's pending steers, as clients show them. */
         pendingSteers?: (streamId: string) => PendingSteer[];
+        /** The live stream's server-selected presentation, else null. */
+        runStatus?: (streamId: string) => RunStatus | null;
+        /** TAL-1006: the live stream's open compression span start (epoch seconds), else null. */
+        compressionStartedAt?: (streamId: string) => number | null;
+        /** TAL-899: whether a Stop holds the session's automatic turns until the user's next turn. */
+        automaticTurnsHeld?: (sid: string) => Promise<boolean>;
+        sessionNotices?: (sid: string) => SessionNotice[];
+        sessionGoal?: (sid: string) => SessionGoal | null;
         /** Drop the session's cached agent; `endSession` (delete/clear) also ends its approval grants and parked approvals. */
-        evictAgent: (sid: string, endSession?: boolean) => void;
+        evictAgent: (sid: string, endSession?: boolean) => Promise<void>;
         closeTerminal: (sid: string) => void;
-        /** Python `delete_cli_session`: remove the session's rows from the profile's state.db; resolves false on failure. */
-        deleteCliSession: (profile: string | null, sid: string) => Promise<boolean>;
+        /**
+         * Python `delete_cli_session`: remove the session and its compression continuations from the profile's state.db in one
+         * transaction; `ok` is false on failure, with `refused` when another Agent process holds any of them (TAL-792).
+         */
+        deleteCliSession: (profile: string | null, sid: string) => Promise<SidecarResult<'state_db.delete_cli_session'>>;
     };
     attachmentDir: (sid: string) => string;
     /** A deleted session can never be viewed, so its finished runs are cleared from the relay. */
-    clearRelayCompletions?: (sid: string, profile: string | null) => void;
+    clearRelayCompletions?: (sid: string, profile: string | null) => Promise<void>;
     /** Run journals are removed with their session (Python `delete_run_journal`). */
     journal?: RunJournal;
     hermesHome: string;
     home: string;
-    /** Sync title-only metadata to state.db when `sync_to_insights` is on. */
-    syncTitle: (session: Session) => Promise<void>;
+    /** Sync title-only metadata to state.db when `sync_to_insights` is on; `manual` marks a user-requested title (rename or regenerate). */
+    syncTitle: (session: Session, manual?: boolean) => Promise<void>;
+    /** TAL-591: the background title job for a CLI session a mutation just claimed (Python `import_cli` queued one). */
+    titleClaimed?: (session: Session) => void;
     /** Context length lookup for a model (checkpoint 7 wires the catalog). */
     contextLengthFor: (model: string | null, provider: string | null) => number | null;
     /** TAL-301: the catalog entry id a stored `(model, provider)` pair selects (null when none or not yet known). */
@@ -99,15 +122,25 @@ export interface SessionServiceDeps {
     /** `truncated`: source kinds whose rows stopped at the per-kind window on this read (TAL-482). */
     cliSessions: (profile: string, opts: {
         sourceFilter: string | null;
-    }) => {
+        sessionIds?: readonly string[];
+    }) => Promise<{
         rows: Row[];
         truncated: ReadonlySet<string>;
-    };
+        storage: AgentStorage;
+    }>;
+    /** `cliSessions` read on this thread, for the synchronous single-session lookups. */
+    cliSessionsSync: (profile: string, opts: {
+        sourceFilter: string | null;
+        sessionIds?: readonly string[];
+    }) => Promise<{
+        rows: Row[];
+        truncated: ReadonlySet<string>;
+    }>;
     /** TAL-551: read-only Claude Code transcripts, listed with the CLI rows when both toggles are on. */
     claudeCode?: ClaudeCodeSessionSource;
     profileHome: (profile: string) => string;
     /** Python `commit_session_memory` (fire-and-forget): the cached Agent flushes memory for a session the user left. */
-    commitSessionMemory?: (sid: string) => void;
+    commitSessionMemory?: (sid: string) => Promise<void>;
     /** TAL-186: the `/api/media` allow-list the transcript media projection rewrites against; without it nothing local is rewritten. */
     media?: {
         access: MediaAccessDeps;
@@ -116,15 +149,25 @@ export interface SessionServiceDeps {
 }
 export declare class SessionService {
     readonly deps: SessionServiceDeps;
+    owner: GatewaySessions | null;
     /** TAL-255: one manual compression worker per session, shared by every compress route. */
     private readonly compressionJobs;
+    /** TAL-1005: the turns now waiting on their session's compression job before they read its history. */
+    private readonly compactionWaiters;
     constructor(deps: SessionServiceDeps);
     private get store();
+    /**
+     * User-turn admission shared by `chat.start` and automatic turns through `TurnRunner.startServerTurn`.
+     * A requested workspace must be trusted; the session's own one, when its directory is gone, falls back to the last one.
+     */
+    turnWorkspace(s: Session, requested?: unknown): Promise<string>;
+    /** A `@provider:` id is split; any other model an explicit pick did not just choose is checked against the catalog (TAL-542). */
+    turnModel(s: Session, body?: Record<string, unknown>): [string | null, string | null, boolean];
     /**
      * TAL-186: rewrites a session's media references to their URLs. A local path is rewritten only when `/api/media`
      * serves it for this session, under the same resolution, so every rewritten reference loads.
      */
-    mediaProjector(s: Session): (text: string) => MediaProjection | null;
+    mediaProjector(s: Session): Promise<(text: string) => MediaProjection | null>;
     publish(reason: string, profile?: string | null, sessionId?: string | null): void;
     visibleToActiveProfile(profile: string | null | undefined): boolean;
     /**
@@ -132,22 +175,50 @@ export declare class SessionService {
      * not slip past the profile check into a handler that trims and trusts it. A non-empty id that is still unsafe after
      * trimming can name no session and is refused here instead of falling through.
      */
-    sessionIdVisible(raw: unknown): boolean;
+    sessionIdVisible(raw: unknown): Promise<boolean>;
+    private localTargets;
+    /** One receipt-backed physical target for every operation on a local conversation alias. */
+    resolveSessionId(sid: string): string;
     /** Python `_lookup_cli_session_metadata(...).get('read_only')` plus the persisted sidecar flag and a not-claimable foreign owner. */
     private isReadOnlyImport;
     /** Python `_session_is_subagent_view_only`: a delegated child by any signal — the persisted sidecar or the state.db row. */
-    isSubagentViewOnly(sid: string): boolean;
+    isSubagentViewOnly(sid: string): Promise<boolean>;
     /** TAL-358: batched `sessions.source` owners from the active profile's state.db. */
-    readonly stateDbSources: (ids: string[]) => Map<string, string> | null;
+    readonly stateDbSources: (ids: string[], profile?: string) => Map<string, StateDbSessionSource> | null;
+    /**
+     * TAL-590 (Python #3238): the read-only CLI or API-server imports among `rows` whose active-profile state.db row is
+     * gone, so their source was deleted outside Web and no Web action could remove them. An unreadable state.db proves
+     * nothing (`agentSessionRowsExisting`); another profile's session or one with a run the runtime still holds is never
+     * an orphan, while a stream id a crash left behind does not count as one.
+     */
+    private orphanedImports;
+    private orphanCandidates;
+    private isOrphanedImport;
+    /**
+     * The list's owner locks and orphan prune (an orphan's sidecar goes, as nothing else ever removes it), with their
+     * state.db reads made on the listing worker up front so the synchronous build never opens state.db (TAL-920).
+     */
+    private listStateDbLookups;
     /** The persisted flag folded with the state.db owner lock (TAL-358): the one read-only rule for mutation gates and the wire. */
-    isReadOnly(s: Session): boolean;
+    readOnlyReason(s: Session | string, profile?: string): Promise<string | null>;
+    private loadedReadOnlyReason;
+    /** A loaded session's final owner check stays synchronous with the protected sidecar dispatch. */
+    assertWritable(session: Session, profile?: string): void;
+    assertWritable(session: string, profile?: string): Promise<void>;
+    /** Controls can exist without a local session file; use the same id the sidecar will address. */
+    idForMutation(sid: string): Promise<string>;
+    isReadOnly(s: Session): Promise<boolean>;
+    /** Recheck after the mutex wait; legacy local metadata/handoff actions keep their existing read-only allowance. */
+    private withMutationLock;
     /** Full session for mutation, refusing read-only imports (Python `_get_or_materialize_session`). */
-    getForMutation(sid: string): Session;
+    getForMutation(sid: string): Promise<Session>;
     private get404;
     /** The Agent's state.db rows for this session (empty for subagent views, which never merge). */
     stateDbRows(s: Session): Message[];
     /** `stateDbRows` and whether the read succeeded on a state.db whose messages carry ids (TAL-493). */
     stateDbRead(s: Session): StateDbRead;
+    /** Preserve existing transcript provenance before a turn adds Agent rows from its starting database read. */
+    beginStateDbTurn(s: Session): StateDbRead;
     private stateDbPath;
     /**
      * Python `_merged_session_messages_for_display`: the sidecar transcript merged append-only with the Agent's state.db
@@ -176,7 +247,23 @@ export declare class SessionService {
         previousContext: Message[];
         agentRows?: Message[] | null;
         startId?: number | null;
+        startGeneration?: string | null;
+        read?: StateDbRead;
     }): void;
+    /**
+     * TAL-921: the model context a turn leaves when it ends without its settled result (an error, a Stop, a dead run), as a
+     * Stop's: the Agent's rows when they hold the turn's prompt, else its own rows among `stateRows` (the state.db rows
+     * committed after it started), then the prose that streamed past them. Null when it captured nothing the model can use.
+     */
+    unsettledTurnContext(turn: {
+        previousContext: Message[];
+        prompt: string | Record<string, unknown>[];
+        msgText: string;
+        streamedText: string;
+        historyLength: number;
+        agentRows?: Message[] | null;
+        stateRows: Message[];
+    }): Message[] | null;
     /**
      * Python `reconciled_state_db_messages_for_session(prefer_context=True)`: the model history is the owner context
      * extended append-only with the Agent's state.db rows (a CLI continuation of this session reaches the model), except
@@ -188,6 +275,8 @@ export declare class SessionService {
      * deferred save keeps out of `messages` and `context_messages` until settlement.
      */
     sideQuestionContext(s: Session): Message[];
+    /** Python `_is_messaging_session_id`: from the WebUI metadata or the Agent's row. */
+    private isMessagingSession;
     /** Python `_lookup_cli_session_metadata`: the sidebar row for a state.db session in the active profile. */
     private lookupCliMeta;
     private claudeCodeRows;
@@ -198,43 +287,59 @@ export declare class SessionService {
      * a WebUI sidecar. `materialized` sessions are writeable (the caller persists the sidecar), `not_claimable` ones are
      * read-only stubs, `was_webui`/`no_foreign_state`/`invalid_sid` answer 404.
      */
-    claimOrSynthesizeCliSession(sid: string, metaIn?: Row | null): {
+    claimOrSynthesizeCliSession(sid: string, metaIn?: Row | null): Promise<{
         session: Session | null;
         reason: 'materialized' | 'not_claimable' | 'was_webui' | 'no_foreign_state' | 'invalid_sid';
-    };
+    }>;
     private mutationTarget;
     /**
      * TAL-551: a Claude Code import is a live view of a transcript Claude Code keeps writing. Web never stores a copy,
      * which would freeze its messages and pin it to one profile.
      */
     private rejectClaudeCode;
-    private rejectSubagent;
+    private rejectViewOnly;
+    /** All transcript transports use the same live-run and durable-pending evidence. */
+    backgroundUpdates<T>(s: Session, messages: T[], reviewRows?: (turnId: string) => Message[]): Promise<T[]>;
     /** TAL-372: each delegation row of a turn's scene carries the status of the work it started. */
-    backgroundLinked(s: Session, messages: unknown[]): unknown[];
+    backgroundLinked(s: Session, messages: unknown[]): Promise<unknown[]>;
     /** `compact()` plus messages, redacted for the wire (Python `_public_session_projection`). */
-    publicSession(s: Session, withMessages?: boolean): Record<string, unknown>;
+    publicSession(s: Session, withMessages?: boolean, messages?: Message[]): Promise<Record<string, unknown>>;
     /** `compact()` with the wire streaming/read-only flags (TAL-312), for replies that return the session row. */
-    wireRow(s: Session): Record<string, unknown>;
+    wireRow(s: Session): Promise<Record<string, unknown>>;
     /**
      * TAL-303: the label for a session's workspace, from its own profile's registry (a profileless row is the root's).
      * One resolver serves one response, so each profile's registry is read once however many rows it names.
      */
-    workspaceNames(): (row: {
+    workspaceNames(rows: readonly {
         profile?: unknown;
         workspace?: unknown;
-    }) => string | null;
+    }[]): Promise<(row: {
+        profile?: unknown;
+        workspace?: unknown;
+    }) => string | null>;
     /** The agent's display name for a session's profile (`assistant_name`). */
     assistantName(s: Session): string;
     /** Python `public_session_projection(s.__dict__)`: every persisted field, redacted (session export). */
     publicSessionDocument(s: Session): Record<string, unknown>;
     private loadRevision;
+    private readonly pageTails;
+    private readonly pageContexts;
+    private prefixIndex;
+    /** Existing projections, once per complete turn range, in absolute transcript coordinates. */
+    private deriveRange;
+    private limitedDetail;
     /** Python `_handle_session_get` on the WebUI sidecar (state.db merge pending). */
     detail(sid: string, query: {
         messages?: string | null | undefined;
         msg_limit?: string | null | undefined;
         msg_before?: string | null | undefined;
         resolve_model?: string | null | undefined;
-    }): Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * TAL-454: the chat `/branch` copied, while it still loads (archived included). A compression continuation is also a
+     * fork of its parent but not a branch, so it links nowhere.
+     */
+    private branchedFrom;
     /**
      * TAL-316: the active run whose journal can replay its output from the start. The detail then leaves that output to the
      * replay; with no active run, no identifiable prompt, or no complete journal, it returns the persisted transcript unchanged.
@@ -245,18 +350,21 @@ export declare class SessionService {
     /** A session without a sidecar, synthesized from state.db for this profile; 404/409 like the detail. */
     private foreignSession;
     /** Python `_handle_session_get` without a sidecar: the state.db transcript as a (read-only or claimable) foreign stub. */
+    foreignMessages(messages: Message[], session: object): Message[];
     private foreignSessionDetail;
     /** Clear persisted streaming flags when no live stream backs them (Python `_clear_stale_stream_state`). */
-    clearStaleStreamState(session: Session): boolean;
-    list(params: Omit<ListParams, 'activeProfile' | 'isolatedProfileMode' | 'profilesMatch' | 'cliRows' | 'gatewayIdentity' | 'stateDbSources' | 'truncatedSources'>): {
+    clearStaleStreamState(session: Session): Promise<boolean>;
+    /** Expand saved aliases in one worker query independently of the bounded native sidebar window. */
+    private persistedAliasMetadata;
+    list(params: Omit<ListParams, 'activeProfile' | 'isolatedProfileMode' | 'profilesMatch' | 'cliRows' | 'gatewayIdentity' | 'stateDbSources' | 'truncatedSources' | 'agentStorage' | 'pruneOrphanedImports' | 'webuiRows'>): Promise<{
         body: ListResponse;
         etag: string;
-    };
+    }>;
     search(q: string, opts: {
         content: boolean;
         depth: number;
         allProfiles: boolean;
-    }): Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
     /**
      * TAL-308: the sidebar search. The candidates are exactly the `/api/sessions` rows for `params` (visibility, source,
      * archived, projection and order), narrowed to `projectId` (`none`: rows without a project), then matched on the
@@ -266,12 +374,12 @@ export declare class SessionService {
         content: boolean;
         depth: number;
         projectId: string | null;
-    }): Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
     /** The first of a stored session's first `depth` messages (0: all) containing every term, with its redacted excerpt. */
     private contentMatch;
-    status(sid: string): Record<string, unknown>;
-    usage(sid: string): Record<string, unknown>;
-    resolveNewSessionWorkspace(body: Record<string, unknown>, visiblePrevSessionId: string | null, profile: string | null): string | null;
+    status(sid: string): Promise<Record<string, unknown>>;
+    usage(sid: string): Promise<Record<string, unknown>>;
+    resolveNewSessionWorkspace(body: Record<string, unknown>, visiblePrevSessionId: string | null, profile: string | null): Promise<string | null>;
     /** The server owns the names' normalization (TAL-631): trimmed, blanks dropped, and nothing left is the profile's defaults. */
     validateToolsetsShape(toolsets: unknown): string[] | null;
     create(body: Record<string, unknown>, opts?: {
@@ -281,7 +389,7 @@ export declare class SessionService {
             repo_root: string;
             created_at: number;
         } | null;
-    }): Session;
+    }): Promise<Session>;
     /** Python `_persist_generated_session_title`: title + generated/manual flags under the session lock, then insights sync. */
     persistGeneratedTitle(sid: string, nextTitle: string, eventReason: string): Promise<Session>;
     rename(sid: string, rawTitle: unknown): Promise<Record<string, unknown>>;
@@ -290,58 +398,155 @@ export declare class SessionService {
     private pinUnserialized;
     archive(sid: string, archived: boolean): Promise<Record<string, unknown>>;
     move(sid: string, targetProjectId: string | null): Promise<Record<string, unknown>>;
+    private readonly modelConfirmationKey;
+    private confirmModelSwitch;
     update(sid: string, body: Record<string, unknown>): Promise<Record<string, unknown>>;
     setToolsets(sid: string, toolsets: unknown): Promise<Record<string, unknown>>;
     /** Python `/api/personality/set` persistence: the name only; the prompt is resolved by the caller. */
     setPersonality(sid: string, name: string | null): Promise<string | null>;
-    truncate(sid: string, keepRaw: unknown): Promise<Record<string, unknown>>;
+    /**
+     * TAL-929: under a `hold`, a cut that discards more than one user turn changes nothing and answers with its counts,
+     * unless `confirmToken` is the token of the rows it would remove now: a transcript that changed since asks again.
+     * Without one (a released App, which asked on the device) the cut proceeds as before.
+     */
+    truncate(sid: string, keepRaw: unknown, hold?: {
+        confirmToken: string | null;
+    } | null): Promise<Record<string, unknown>>;
+    /**
+     * TAL-929: the confirmation a cut at `keep` needs, or null for one that removes at most one user turn. Counted on the rows
+     * the detail shows, state.db continuation included, since `keep` indexes them: the user turns the cut removes, and the
+     * messages after the row it starts at.
+     */
+    private heldCut;
     /**
      * Python `_handle_session_compress_start`: validate, then join the session's running job or start a fresh one (a
      * finished job is replaced). The stale-runtime refusal comes before a job exists; a running job is joined without it.
      */
-    startCompression(sid: string, focusRaw: unknown): Promise<CompressionJob>;
+    startCompression(sid: string, focusRaw: unknown, opts?: {
+        automatic?: boolean;
+    }): Promise<CompressionJob>;
+    /**
+     * TAL-1005: compact the session in its joinable compression job before the next turn reads its history. A running job
+     * is always joined; a new one starts when the session is `due` (`compactionDue`, read from the store when omitted).
+     * `turn` is the waiting turn's stream: the job leaves its rows alone. `onWait` runs once a job is being waited on; an abort of `signal` (the turn's Stop) ends the wait but not the
+     * job. True when the job installed a compressed context. Never throws: a failed job leaves the Agent's own preflight.
+     */
+    ensureCompacted(sid: string, opts?: {
+        turn?: string;
+        signal?: AbortSignal;
+        onWait?: () => void | Promise<void>;
+        due?: boolean;
+    }): Promise<boolean>;
+    /**
+     * TAL-1005: measure the model context again when it holds a post-compression estimate the rows after it may have
+     * outgrown (a waiting turn's prompt, a stopped or failed turn's work). Skipped while a turn owns the session, which
+     * settles its own figures, or once the estimate changed meanwhile. True when it stored a new estimate.
+     */
+    remeasureContext(sid: string): Promise<boolean>;
+    private storedCompactionDue;
+    /** Whether the session's context (the post-compression estimate, else the last prompt) reached the next turn's threshold. */
+    compactionDue(s: Session): boolean;
     /** The session a compression may run on now, and the model history it compresses: the context a turn would send, so a
-     * repeat compression builds on the previous summary instead of re-reading the whole display transcript. */
+     * repeat compression builds on the previous summary instead of re-reading the whole display transcript. `context` is
+     * that history unsanitized and `stateRows` the state.db read it came from. */
     private compressionTarget;
+    /**
+     * The loaded session's own compression guards: no running turn and enough model history. TAL-1005: a turn waiting on
+     * the compression has not read its history yet, so it does not block; the context leaves out its rows, as it does.
+     */
+    private compressionContext;
+    /** TAL-614: whether a manual compression would start now: `compressionTarget`'s gates, with `readOnly` the wire flag. */
+    private canCompress;
+    /** TAL-258: the session's WebUI record (absent for a CLI or gateway session) and the profile whose state.db holds its rows. */
+    private handoffTarget;
+    /** Python `_handle_conversation_rounds` (TAL-258): the session's rounds and whether the handoff dock is due. */
+    conversationRounds(sid: string, since: number | null): Promise<{
+        ok: true;
+        rounds: number;
+        threshold: number;
+        should_show: boolean;
+    }>;
+    /**
+     * Python `_handle_handoff_summary` (TAL-258): the session's main model summarizes its last 50 state.db messages after
+     * `since`, and the summary is appended as a display-only `handoff_summary` tool row. A failed or cut-off answer falls
+     * back to a deterministic local summary rather than an error.
+     */
+    handoffSummary(sid: string, since: number | null): Promise<{
+        ok: true;
+        summary: string;
+        message_count: number;
+        rounds: number;
+        fallback: boolean;
+        warning?: string;
+    }>;
+    /** The main model's summary at 700 tokens, once more at 1400 when it was cut off, else the local fallback. */
+    private generateHandoffSummary;
+    /**
+     * Python `_persist_handoff_summary`: a messaging session gets the marker in state.db and its WebUI record; any other
+     * session in its WebUI record, or in state.db when it has none. Each store skips a marker its tail already holds, and
+     * the session lock keeps two summaries from both passing that check. A card neither store saved answers 503.
+     */
+    private persistHandoffMarker;
+    /** The same live presentation for session detail and journal snapshot recovery. */
+    currentRunStatus(sid: string, streamId: string | null): RunStatus | null;
     /** The session's compression job; a deleted session's finished result is dropped rather than served. */
-    compressionJob(sid: string): CompressionJob | undefined;
+    compressionJob(sid: string): Promise<CompressionJob | undefined>;
     /**
      * Python `_handle_session_compress`: compress the sanitized transcript in the sidecar outside the lock, then under the
-     * session lock refuse a result the session moved past (stream state or transcript changed) and install it as the
+     * session lock refuse a result the session moved past (another stream, or a transcript changed) and install it as the
      * model context with the manual anchor and the #4836 boundary that keeps state.db from replaying compressed rows.
-     * The guards run again first: a stream may have started while the caller awaited the runtime check.
+     * The guards run again first: a stream may have started while the caller awaited the runtime check. TAL-1005: rows
+     * the job's waiting turns added meanwhile (a prompt, a Stop) stay after the compressed context.
      */
     private compressSession;
+    /** Clear and delete share the profile-scoped, best-effort Agent session boundary. */
+    private finalizeSession;
     clear(sid: string): Promise<Record<string, unknown>>;
     retry(sid: string): Promise<Record<string, unknown>>;
     undo(sid: string): Promise<Record<string, unknown>>;
-    duplicate(sid: string): Record<string, unknown>;
-    branch(sid: string, body: Record<string, unknown>): Record<string, unknown>;
+    duplicate(sid: string): Promise<Record<string, unknown>>;
+    branch(sid: string, body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Python `read_session_lineage_report` on the active profile's state.db. */
+    lineageReport(sid: string): Record<string, unknown>;
+    /** TAL-259: recovery reads the active profile's state.db, and a recovered sidecar joins that profile. */
+    private recoveryDeps;
+    recoveryAudit(): Promise<RecoveryAudit>;
+    recoveryRepairSafe(): Promise<RecoveryRepair>;
+    /**
+     * Python `_handle_session_compression_recovery_start`: open a compression-exhausted session's focused continuation, an
+     * empty fork keeping its workspace, model, profile, toolsets and worktree. A retry opens the oldest continuation
+     * already started from it in the same profile; the source's lock makes concurrent starts converge on one child.
+     */
+    compressionRecoveryStart(sid: string): Promise<Record<string, unknown>>;
+    /** Python `find_compression_recovery_session`: the oldest same-profile continuation started from `sid`, cached or persisted. */
+    private compressionRecoveryChild;
     /** The run that keeps `delete` answering 409, if any; stream status reports it so a draining client can wait on it (TAL-622). */
-    activeRunBlocking(sid: string): string | null;
+    activeRunBlocking(sid: string): Promise<string | null>;
     delete(sid: string): Promise<Record<string, unknown>>;
-    cleanup(zeroOnly: boolean): Record<string, unknown>;
-    import(body: Record<string, unknown>): Record<string, unknown>;
-    readDraft(sid: string): Record<string, unknown>;
+    /** The committed Agent deletion targets and cleanup outcome; throws 409 `refused` while an Agent process holds a row. */
+    private deleteStateDbRows;
+    cleanup(zeroOnly: boolean): Promise<Record<string, unknown>>;
+    import(body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    readDraft(sid: string): Promise<Record<string, unknown>>;
     writeDraft(body: Record<string, unknown>): Promise<Record<string, unknown>>;
     saveAnchorScene(body: Record<string, unknown>): Promise<Record<string, unknown>>;
     /** The session and the full transcript its detail is built from; a state.db-only session gives its synthesized one. */
     private fullTranscript;
-    readAnchorScene(query: Record<string, string | null | undefined>): Record<string, unknown>;
+    readAnchorScene(query: Record<string, string | null | undefined>): Promise<Record<string, unknown>>;
     /** TAL-331: one tool call's whole result, which a limited response clipped (`result_truncated`), redacted like the detail. */
     readToolResult(query: {
         session_id: string;
         tool_call_id: string;
-    }): {
+    }): Promise<{
         tool_call_id: string;
         result: string;
         result_view: ToolResultView;
-    };
-    createShare(sid: string): Record<string, unknown>;
-    revokeShare(sid: string): Record<string, unknown>;
-    loadShare(token: string): Record<string, unknown>;
+    }>;
+    createShare(sid: string): Promise<Record<string, unknown>>;
+    revokeShare(sid: string): Promise<Record<string, unknown>>;
+    loadShare(token: string): Promise<Record<string, unknown>>;
     yolo(sid: string): Record<string, unknown>;
-    setYolo(sid: string, enabled: boolean): Record<string, unknown>;
+    setYolo(sid: string, enabled: boolean): Promise<Record<string, unknown>>;
 }
 export declare const AUTO_TITLE_LABELS: Set<string>;
 /** Python `apply_session_title_rename`. */