@maudecode/talaria-web 1.17.2 → 1.18.0

package/dist/sessions/service.js

@@ -3,17 +3,20 @@ import { randomUUID } from 'node:crypto';
 import { rmSync } from 'node:fs';
 import { buildActiveTurnToken, copyJson, redactSessionData, redactValue, stripPublicInternalFields, withSceneToolDisplay } from '../redact.js';
 import { DraftVersionConflict, normalizeDraftVersion } from './drafts.js';
-import { allSessions, buildSessionListPayload, CLI_IDENTITY_FIELDS, isClaimableCliSource, isMessagingSessionRecord, withOwnerLocks, withSessionWireFlags, lineageRootId, mergeCliSidebarMetadata, sessionListResponse, sessionSearchMatches, sessionSearchMessageText, sessionSearchPreview, sessionSearchTerms } from './list.js';
+import { allSessions, buildSessionListPayload, CLI_IDENTITY_FIELDS, isClaimableCliSource, isMessagingSessionRecord, ownerLockCandidates, withOwnerLocks, withSessionWireFlags, lineageRootId, mergeCliSidebarMetadata, sessionListResponse, sessionSearchMatches, sessionSearchMessageText, sessionSearchPreview, sessionSearchTerms } from './list.js';
 import { anchorSceneIntOrNull, fullToolResult, hydrateAnchorActivityScenes, normalizeAnchorSceneMessageRef, readAnchorSceneRows, storeAnchorScene, withTurnIds } from './anchor.js';
-import { isSafeSessionId, lastMessageTimestamp, Session, sharePath, stripAttachedFilesMarker, titleFrom } from './session.js';
+import { COMPRESSION_RECOVERY_ACTION_START_FOCUSED, compressionRecoveryPayload, isSafeSessionId, lastMessageTimestamp, Session, sharePath, stripAttachedFilesMarker, titleFrom } from './session.js';
 import { SessionBusy, SessionNotFound, statSignature } from './store.js';
 import { UNSETTLED_TODO_KEY, attachTodoState } from './todo.js';
 import { isClaudeCodeSessionId } from './claude-code.js';
-import { stateDbCompressionLineage, stateDbSessionMessages, stateDbSessionRead, stateDbSessionRow, stateDbSessionSources } from './state-db.js';
+import { auditSessionRecovery, repairSafeSessionRecovery } from './recovery.js';
+import { agentSessionRowsExisting, agentSessionRowsExistingAsync, CONVERSATION_ROUND_THRESHOLD, countConversationRounds, stateDbCompressionLineage, stateDbTailToolContent, stateDbLineageReport, stateDbSessionMessages, stateDbSessionRead, stateDbSessionRow, stateDbSessionSources, stateDbSessionSourcesAsync, stateDbTimestampSeconds } from './state-db.js';
+import { completionIncomplete, fallbackHandoffSummary, HANDOFF_SYSTEM_PROMPT, handoffMarker, handoffPayload, handoffTranscript, messageHandoffPayload, sameHandoff } from './handoff.js';
 import { anchorMessageKey, anchorSummary, CompressionJobs, compressionReference, visibleMessagesForAnchor } from './compress.js';
 import { SidecarError } from '../sidecar/client.js';
-import { agentSteerText, attachedFilesPrompt, attachmentObjects, dedupeContext, isContextCompressionMarker, journalOutputRows, looksLikeCurrentUserTurn, stoppedTurnContext, workspaceContextPrefix, mergeSessionMessagesAppendOnly, messageIdentity, pendingUserRow, reasoningFieldsText, sanitizeMessagesForApi, stateDbSeenId, stripWorkspacePrefix, withAttachmentObjects, withBodyExcerpts, withDisplayMedia, withMarkerKinds, withSceneRowMedia, withPendingUserTurn, withToolCallOutcomes, withoutRunningTurnOutput } from './merge.js';
+import { agentSteerText, attachedFilesPrompt, attachmentObjects, checkpointTurnStart, dedupeContext, isContextCompressionMarker, journalOutputRows, looksLikeCurrentUserTurn, stoppedTurnContext, mergeSessionMessagesAppendOnly, messageIdentity, pendingUserRow, reasoningFieldsText, sanitizeMessagesForApi, stateDbSeenId, stripWorkspacePrefix, withAttachmentObjects, withBodyExcerpts, withDisplayMedia, withMarkerKinds, withSceneRowMedia, withPendingUserTurn, withToolCallOutcomes, withoutRunningTurnOutput } from './merge.js';
 import { withBackgroundUpdates } from './background-updates.js';
+import { sourceKind } from './source-kind.js';
 import { withBackgroundLinks } from './background-tasks.js';
 import { messagesForLimitedPayload, messageWindowForDisplay, MAX_MSG_LIMIT, parseMsgLimit, toolCallsForMessageWindow } from './window.js';
 import { redactText } from '../redact.js';
@@ -64,6 +67,40 @@ export class SessionService {
         this.compressionJobs = new CompressionJobs();
     }
     get store() { return this.deps.store; }
+    /**
+     * TAL-577: user-turn admission shared by `chat.start` and server-side wakeups, after `ensureAgentRuntimeCurrent`.
+     * A requested workspace must be trusted; the session's own one, when its directory is gone, falls back to the last one.
+     */
+    turnWorkspace(s, requested) {
+        const ws = this.deps.workspaces;
+        if (requested !== undefined && requested !== null && requested !== '') {
+            try {
+                return ws.resolveTrusted(str(requested), s.profile);
+            }
+            catch (error) {
+                throw new HttpFailure(400, error.message);
+            }
+        }
+        try {
+            const [workspace, recovered] = ws.resolveImplicitWithRecovery(s.workspace, (p) => ws.lastWorkspace(p), s.profile);
+            if (recovered)
+                s.workspace = workspace;
+            return workspace;
+        }
+        catch (error) {
+            throw new HttpFailure(400, error.message);
+        }
+    }
+    /** A `@provider:` id is split; any other model an explicit pick did not just choose is checked against the catalog (TAL-542). */
+    turnModel(s, body = {}) {
+        const requestedModel = str(body.model) || s.model;
+        const requestedProvider = 'model_provider' in body ? body.model_provider : s.model_provider;
+        const [model, provider] = this.deps.modelStateFromRequest(requestedModel, requestedProvider, s.model_provider);
+        if (model !== requestedModel || !model || body.explicit_model_pick === true)
+            return [model, provider, model !== requestedModel];
+        const repaired = this.deps.repairSessionModel?.(s.profile ?? null, model, provider);
+        return repaired ? [repaired[0], repaired[1], true] : [model, provider, false];
+    }
     /**
      * 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.
@@ -150,6 +187,52 @@ export class SessionService {
     }
     /** TAL-358: batched `sessions.source` owners from the active profile's state.db. */
     stateDbSources = (ids) => stateDbSessionSources(join(this.deps.profileHome(this.deps.activeProfile()), 'state.db'), ids);
+    /**
+     * 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.
+     */
+    orphanedImports(rows) {
+        const candidates = this.orphanCandidates(rows);
+        if (!candidates.length)
+            return new Set();
+        const existing = agentSessionRowsExisting(this.stateDbPath(null), candidates);
+        return new Set(candidates.filter((sid) => !existing.has(sid)));
+    }
+    orphanCandidates(rows) {
+        return rows.filter((r) => r.read_only && ['cli', 'api'].includes(sourceKind(r)) && this.visibleToActiveProfile(str(r.profile) || null) && !this.activeRunBlocking(str(r.session_id)))
+            .map((r) => str(r.session_id));
+    }
+    isOrphanedImport(sid) {
+        try {
+            return this.orphanedImports([this.store.get(sid, { metadataOnly: true }).compact()]).size > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 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).
+     */
+    async listStateDbLookups(rows) {
+        const dbPath = this.stateDbPath(null);
+        const ownerIds = ownerLockCandidates(rows);
+        const owners = ownerIds.length ? await stateDbSessionSourcesAsync(dbPath, ownerIds) : new Map();
+        const checked = new Set(this.orphanCandidates(rows));
+        const existing = checked.size ? await agentSessionRowsExistingAsync(dbPath, checked) : new Set();
+        return {
+            stateDbSources: () => owners,
+            pruneOrphanedImports: (current) => {
+                // Only an id the worker checked can be an orphan; a row that became a candidate meanwhile waits for the next list.
+                const orphans = new Set(this.orphanCandidates(current).filter((sid) => checked.has(sid) && !existing.has(sid)));
+                for (const sid of orphans)
+                    this.store.deleteFiles(sid);
+                return orphans;
+            },
+        };
+    }
     /** 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) {
         if (s.read_only)
@@ -178,6 +261,7 @@ export class SessionService {
                 const synth = this.claimOrSynthesizeCliSession(sid);
                 if (synth.session && synth.reason === 'materialized') {
                     this.store.save(synth.session);
+                    this.deps.titleClaimed?.(synth.session);
                     return synth.session;
                 }
                 if (synth.session)
@@ -242,7 +326,7 @@ export class SessionService {
      * turn started from but the transcript lacks (a CLI continuation read into its context) are kept before the turn.
      */
     settleStateDb(s, turn) {
-        const read = this.stateDbRead(s);
+        const read = turn.read ?? this.stateDbRead(s);
         const startedWith = new Set(turn.previousContext.flatMap((m) => (typeof m._state_db_row_id === 'number' ? [m._state_db_row_id] : [])));
         const earlier = mergeSessionMessagesAppendOnly(s.messages, read.rows.filter((m) => typeof m._state_db_row_id === 'number' && startedWith.has(m._state_db_row_id)), { stateDbSeenId: -1 }).slice(s.messages.length);
         const added = new Map();
@@ -296,6 +380,30 @@ export class SessionService {
             this.markStateDbSeen(s);
         }
     }
+    /**
+     * 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) {
+        const reported = turn.agentRows && checkpointTurnStart(turn.agentRows, turn.msgText, turn.historyLength) !== null ? turn.agentRows : null;
+        const own = reported ? null : runStateDbRows(turn.stateRows, turn.msgText);
+        const checkpoint = reported ?? (own && [...turn.previousContext, ...own]);
+        const context = stoppedTurnContext(turn.previousContext, checkpoint, turn.prompt, turn.msgText, turn.streamedText, turn.historyLength);
+        if (!context)
+            return null;
+        if (!own || !checkpoint || checkpointTurnStart(checkpoint, turn.msgText, turn.historyLength) === null)
+            return dedupeContext(context);
+        // The context holds the turn's own state.db rows from its prompt on. The Agent persisted the prompt's text only, so the
+        // prompt row carries what the turn sent (attached files, images). This turn's settlement covers the rows: without
+        // their ids, the next one never reads them as a CLI continuation the transcript lacks.
+        const at = turn.previousContext.length;
+        return dedupeContext(context.map((m, i) => {
+            if (i === at)
+                return { role: 'user', content: turn.prompt, ...(m.timestamp != null ? { timestamp: m.timestamp } : {}) };
+            return i > at && i < at + own.length ? Object.fromEntries(Object.entries(m).filter(([k]) => k !== '_state_db_row_id' && k !== '_state_db_generation')) : m;
+        }));
+    }
     /**
      * 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
@@ -314,12 +422,22 @@ export class SessionService {
         const pending = this.pendingTurn(s);
         return pending ? withPendingUserTurn(context, pending) : context;
     }
+    /** Python `_is_messaging_session_id`: from the WebUI metadata or the Agent's row. */
+    isMessagingSession(sid) {
+        try {
+            if (isMessagingSessionRecord(this.store.get(sid, { metadataOnly: true }).compact()))
+                return true;
+        }
+        catch { /* absent */ }
+        const meta = this.lookupCliMeta(sid);
+        return meta !== null && isMessagingSessionRecord(meta);
+    }
     /** Python `_lookup_cli_session_metadata`: the sidebar row for a state.db session in the active profile. */
     lookupCliMeta(sid) {
         try {
             if (isClaudeCodeSessionId(sid))
                 return this.claudeCodeRows().find((r) => str(r.session_id) === sid) ?? null;
-            return this.deps.cliSessions(this.deps.activeProfile(), { sourceFilter: null }).rows.find((r) => str(r.session_id) === sid) ?? null;
+            return this.deps.cliSessionsSync(this.deps.activeProfile(), { sourceFilter: null }).rows.find((r) => str(r.session_id) === sid) ?? null;
         }
         catch {
             return null;
@@ -498,7 +616,8 @@ export class SessionService {
         }
         this.clearStaleStreamState(s);
         const journaled = loadMessages ? this.journaledActiveTurn(s) : null;
-        let transcript = loadMessages ? this.mergedTranscript(s) : [];
+        const stateRows = loadMessages ? this.stateDbRows(s) : [];
+        let transcript = loadMessages ? this.mergedTranscript(s, s.messages, stateRows) : [];
         const pending = loadMessages ? this.pendingTurn(s) : null;
         if (pending)
             transcript = withPendingUserTurn(transcript, pending);
@@ -572,10 +691,42 @@ export class SessionService {
         raw.read_only = this.isReadOnly(s);
         raw.assistant_name = this.assistantName(s);
         raw.workspace_name = this.workspaceNames()(s);
+        raw.branched_from = this.branchedFrom(s);
         withSessionWireFlags(raw, activeStreamIds);
+        // A metadata-only read lacks the history the gate counts, so it carries no flag.
+        if (loadMessages)
+            raw.can_compress = this.canCompress(s, raw.read_only === true, stateRows);
         raw.pending_steers = raw.active_stream_id ? (this.deps.runtime.pendingSteers?.(str(raw.active_stream_id)) ?? []) : [];
         return redactSessionData(raw, this.deps.redactEnabled());
     }
+    /**
+     * 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.
+     */
+    branchedFrom(s) {
+        const parentId = s.parent_session_id;
+        if (!parentId || str(s.session_source).trim().toLowerCase() !== 'fork' || s.compression_recovery_source_session_id)
+            return null;
+        let title;
+        try {
+            const parent = this.store.get(parentId, { metadataOnly: true, promote: false, cacheOnMiss: false });
+            if (!this.visibleToActiveProfile(parent.profile))
+                return null;
+            title = parent.title;
+        }
+        catch {
+            // A read-only foreign parent (a cron run) has no sidecar and opens from the active profile's state.db while it
+            // has transcript rows and is not a deleted chat (`claimOrSynthesizeCliSession`'s `was_webui` and `no_foreign_state`).
+            const dbPath = this.stateDbPath(null);
+            const row = stateDbSessionRow(dbPath, parentId);
+            if (!row || this.store.wasDeleted(parentId) || this.indexMarksWasWebui(parentId))
+                return null;
+            if (!stateDbSessionMessages(dbPath, parentId, { stitch: true }).length)
+                return null;
+            title = row.title;
+        }
+        return { session_id: parentId, title: str(redactText(str(title) || 'Untitled', this.deps.redactEnabled())) };
+    }
     /**
      * 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.
@@ -674,7 +825,8 @@ export class SessionService {
         const read = this.stateDbRead(target);
         const runStart = target.pending_started_at || events[0]?.created_at || this.deps.now();
         const before = read.rows.filter((m) => Number(m.timestamp) < runStart);
-        const ownRows = target.hasPendingPrompt ? runStateDbRows(read.rows.filter((m) => Number(m.timestamp) >= runStart), pendingText) : null;
+        const runRows = read.rows.filter((m) => Number(m.timestamp) >= runStart);
+        const ownRows = target.hasPendingPrompt ? runStateDbRows(runRows, pendingText) : null;
         // Without this turn's rows: an eager save already put its prompt in the transcript a fresh context falls back to.
         const previousContext = this.modelContext(target, before).filter((m) => m._turn_id !== turnId);
         if (target.hasPendingPrompt) {
@@ -684,16 +836,16 @@ export class SessionService {
                 target.messages.push({ role: 'user', content: pendingText, timestamp: Math.trunc(startedAt), ...(attachments.length ? { attachments } : {}), _recovered: true, _source: target.pending_user_source ?? 'webui', _turn_id: turnId });
             // The model context settles as a Stop's does: the Agent's own rows when it committed the prompt, else the prompt it
             // was sent; then the prose that streamed past them.
-            const prompt = attachedFilesPrompt((str(target.workspace) ? workspaceContextPrefix(str(target.workspace)) : '') + pendingText, attachments);
+            const prompt = attachedFilesPrompt(pendingText, attachments);
             const streamed = output.map((m) => str(m.content)).filter(Boolean).join('\n\n');
-            target.context_messages = dedupeContext(stoppedTurnContext(previousContext, ownRows ? [...previousContext, ...ownRows] : null, prompt, pendingText, streamed, previousContext.length) ?? [...structuredClone(previousContext), { role: 'user', content: prompt }]);
+            target.context_messages = this.unsettledTurnContext({ previousContext, prompt, msgText: pendingText, streamedText: streamed, historyLength: previousContext.length, stateRows: runRows }) ?? dedupeContext([...structuredClone(previousContext), { role: 'user', content: prompt }]);
         }
         if (target.hasPendingPrompt || output.length) {
             target.messages.push(...output);
             if (!answered)
                 target.messages.push({ role: 'assistant', content: '**Interrupted:** The reply was interrupted before it could be saved.', timestamp: Math.trunc(this.deps.now()), _error: true, _turn_id: turnId });
             // Settled like a turn: the Agent's own rows are covered by the recovered turn; without them, every row past the run's start is.
-            this.settleStateDb(target, { turnId, previousContext, agentRows: ownRows, startId: stateDbSeenId(before) ?? (read.idCapable ? 0 : null) });
+            this.settleStateDb(target, { turnId, previousContext, agentRows: ownRows, startId: stateDbSeenId(before) ?? (read.idCapable ? 0 : null), read });
         }
         target.active_stream_id = null;
         target.pending_user_message = null;
@@ -717,16 +869,18 @@ export class SessionService {
         return true;
     }
     // ── list / search ────────────────────────────────────────────────────────
-    list(params) {
+    async list(params) {
         const activeProfile = this.deps.activeProfile();
         const wantState = params.showCliSessions || params.showCronSessions || params.showWebhookSessions || params.showKanbanSessions;
         // Python reads every profile's state.db under all_profiles; this port projects the active profile only.
-        const cliRead = wantState ? this.deps.cliSessions(activeProfile, { sourceFilter: params.sourceFilter ?? null }) : undefined;
+        const cliRead = wantState ? await this.deps.cliSessions(activeProfile, { sourceFilter: params.sourceFilter ?? null }) : undefined;
         const claudeCodeRows = params.showCliSessions && params.showClaudeCodeSessions ? this.claudeCodeRows() : [];
         const cliRows = cliRead ? [...cliRead.rows, ...claudeCodeRows] : undefined;
         const gatewayIdentity = loadGatewaySessionIdentityMap(join(this.deps.profileHome(activeProfile), 'sessions', 'sessions.json'));
         const truncatedSources = cliRead?.truncated;
-        const payload = buildSessionListPayload(this.store, { ...params, ...(cliRows ? { cliRows } : {}), ...(truncatedSources ? { truncatedSources } : {}), gatewayIdentity, stateDbSources: this.stateDbSources, activeProfile, isolatedProfileMode: this.deps.isolatedProfileMode(), profilesMatch: this.deps.profilesMatch });
+        const webuiRows = allSessions(this.store, { sidebarMetadataOnly: true });
+        const lookups = await this.listStateDbLookups(webuiRows);
+        const payload = buildSessionListPayload(this.store, { ...params, ...(cliRows ? { cliRows } : {}), ...(truncatedSources ? { truncatedSources } : {}), gatewayIdentity, ...lookups, webuiRows, activeProfile, isolatedProfileMode: this.deps.isolatedProfileMode(), profilesMatch: this.deps.profilesMatch });
         return sessionListResponse(payload, this.deps.runtime, this.deps.redactEnabled(), this.deps.now(), this.workspaceNames());
     }
     search(q, opts) {
@@ -770,8 +924,8 @@ export class SessionService {
      * archived, projection and order), narrowed to `projectId` (`none`: rows without a project), then matched on the
      * title, then the metadata the row shows (workspace path and name, model, provider, profile, source label), then message content.
      */
-    sidebarSearch(q, params, opts) {
-        let rows = this.list(params).body.sessions;
+    async sidebarSearch(q, params, opts) {
+        let rows = (await this.list(params)).body.sessions;
         if (opts.projectId === 'none')
             rows = rows.filter((r) => !r.project_id);
         else if (opts.projectId)
@@ -916,7 +1070,8 @@ export class SessionService {
             markSessionTitleGenerated(current);
             this.store.save(current, { touchUpdatedAt: false });
         });
-        await this.deps.syncTitle(current);
+        // An explicit regenerate is user-requested, so state.db takes it over a manual name.
+        await this.deps.syncTitle(current, true);
         this.publish(eventReason, current.profile, current.session_id);
         return current;
     }
@@ -926,7 +1081,7 @@ export class SessionService {
             applySessionTitleRename(s, rawTitle);
             this.store.save(s);
         });
-        await this.deps.syncTitle(s);
+        await this.deps.syncTitle(s, true);
         this.publish('session_rename', s.profile, s.session_id);
         return { session: this.wireRow(s) };
     }
@@ -1113,12 +1268,146 @@ export class SessionService {
     compressionTarget(sid) {
         this.rejectSubagent(sid, 'compressed');
         const s = this.mutationTarget(sid, 'compressed');
+        return { s, history: this.compressionHistory(s) };
+    }
+    /** The loaded session's own compression guards: no running turn and enough model history. */
+    compressionHistory(s, stateRows) {
         if (s.active_stream_id)
             throw new HttpFailure(409, 'Session is still streaming; wait for the current turn to finish.');
-        const history = sanitizeMessagesForApi(this.modelContext(s));
+        const history = sanitizeMessagesForApi(this.modelContext(s, stateRows));
         if (history.length < 4)
             throw new HttpFailure(400, 'Not enough conversation to compress (need at least 4 messages).');
-        return { s, history };
+        return history;
+    }
+    /** TAL-614: whether a manual compression would start now: `compressionTarget`'s gates, with `readOnly` the wire flag. */
+    canCompress(s, readOnly, stateRows) {
+        if (readOnly || isClaudeCodeSessionId(s.session_id))
+            return false;
+        try {
+            this.compressionHistory(s, stateRows);
+            return true;
+        }
+        catch (error) {
+            if (error instanceof HttpFailure)
+                return false;
+            throw error;
+        }
+    }
+    /** TAL-258: the session's WebUI record (absent for a CLI or gateway session) and the profile whose state.db holds its rows. */
+    handoffTarget(sid) {
+        let local = null;
+        try {
+            local = this.store.get(sid);
+        }
+        catch { /* a foreign session without a WebUI record */ }
+        const profile = local?.profile ?? this.deps.activeProfile();
+        return { local, profile, dbPath: this.stateDbPath(profile) };
+    }
+    /** Python `_handle_conversation_rounds` (TAL-258): the session's rounds and whether the handoff dock is due. */
+    conversationRounds(sid, since) {
+        const rounds = countConversationRounds(this.handoffTarget(sid).dbPath, sid, since);
+        return { ok: true, rounds, threshold: CONVERSATION_ROUND_THRESHOLD, should_show: rounds >= CONVERSATION_ROUND_THRESHOLD };
+    }
+    /**
+     * 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.
+     */
+    async handoffSummary(sid, since) {
+        this.rejectSubagent(sid, 'summarized');
+        const { local, profile, dbPath } = this.handoffTarget(sid);
+        const rounds = countConversationRounds(dbPath, sid, since);
+        if (rounds < CONVERSATION_ROUND_THRESHOLD)
+            throw new HttpFailure(400, 'Not enough conversation rounds to generate a summary.');
+        // A running turn settles the transcript it started from, which would drop a card appended meanwhile.
+        if (local?.active_stream_id)
+            throw new HttpFailure(409, 'Session is still streaming; wait for the current turn to finish.');
+        const all = stateDbSessionMessages(dbPath, sid, { stitch: true });
+        const messages = (since === null ? all : all.filter((m) => { const ts = stateDbTimestampSeconds(m.timestamp); return ts !== null && ts > since; })).slice(-50);
+        if (messages.length < 2)
+            throw new HttpFailure(400, 'Not enough messages to summarize.');
+        const sidecar = this.deps.sidecar?.() ?? null;
+        await ensureAgentRuntimeCurrent(sidecar);
+        const meta = local ? null : this.lookupCliMeta(sid);
+        const generated = await this.generateHandoffSummary(sidecar, profile, local, meta, messages);
+        const pick = (row, ...keys) => { for (const key of keys) {
+            const v = str(row?.[key]).trim();
+            if (v)
+                return v;
+        } return ''; };
+        // Python `get_cli_sessions` never listed WebUI's own state.db rows, so they name no channel.
+        const cliRow = meta ?? this.lookupCliMeta(sid);
+        const channel = pick(local, 'source_label', 'raw_source', 'source_tag', 'session_source') || (str(cliRow?.raw_source || cliRow?.source).trim().toLowerCase() === 'webui' ? '' : pick(cliRow, 'source_label', 'raw_source', 'source_tag', 'source')) || null;
+        await this.persistHandoffMarker(sid, profile, handoffMarker(sid, generated.summary, channel, rounds, generated.fallback, this.deps.now()));
+        return { ok: true, summary: generated.summary, message_count: messages.length, rounds, fallback: generated.fallback, ...(generated.warning ? { warning: generated.warning } : {}) };
+    }
+    /** The main model's summary at 700 tokens, once more at 1400 when it was cut off, else the local fallback. */
+    async generateHandoffSummary(sidecar, profile, local, meta, messages) {
+        const fallback = (warning) => ({ summary: fallbackHandoffSummary(messages), fallback: true, ...(warning ? { warning: `Summary generation used local fallback: ${warning}` } : {}) });
+        if (!sidecar)
+            return fallback('the Agent sidecar is not running');
+        const [model, provider] = local ? this.deps.modelStateFromRequest(local.model, local.model_provider, local.model_provider) : [str(meta?.model).trim() || null, null];
+        const prompt = [{ role: 'system', content: HANDOFF_SYSTEM_PROMPT }, { role: 'user', content: `Conversation transcript:\n${handoffTranscript(messages)}` }];
+        const ask = (maxTokens) => sidecar.call('aux.complete', { profile_home: this.deps.profileHome(profile), task: 'handoff_summary', messages: prompt, model: model ?? '', provider, max_tokens: maxTokens, temperature: 0.2 }, { timeoutMs: 60_000 });
+        try {
+            let result = await ask(700);
+            if (completionIncomplete(result))
+                result = await ask(1400);
+            return completionIncomplete(result) ? fallback() : { summary: result.text, fallback: false };
+        }
+        catch (error) {
+            if (error instanceof SidecarError && error.condition === 'agent_runtime_stale')
+                throw staleRuntimeFailure(error);
+            // No credential is not a failure: the predecessor answered with the local summary and no warning.
+            if (error instanceof SidecarError && error.condition === 'credential_missing')
+                return fallback();
+            return fallback(sanitizePaths(error));
+        }
+    }
+    /**
+     * 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.
+     */
+    async persistHandoffMarker(sid, profile, marker) {
+        const card = messageHandoffPayload(marker);
+        const toStateDb = async () => {
+            if (sameHandoff(handoffPayload(stateDbTailToolContent(this.stateDbPath(profile), sid)), card))
+                return true;
+            const sidecar = this.deps.sidecar?.();
+            if (!sidecar)
+                return false;
+            try {
+                return (await sidecar.call('state_db.append_message', { profile_home: this.deps.profileHome(profile), session_id: sid, role: 'tool', content: str(marker.content), tool_name: 'handoff_summary', timestamp: Number(marker.timestamp) })).ok;
+            }
+            catch {
+                return false;
+            }
+        };
+        await this.store.withLock(sid, async () => {
+            let live = null;
+            try {
+                live = this.store.get(sid);
+            }
+            catch { /* no WebUI record */ }
+            // A turn that started while the summary was generated would drop the card when it settles.
+            if (live?.active_stream_id)
+                throw new HttpFailure(409, 'Session is still streaming; wait for the current turn to finish.');
+            const toLocal = () => {
+                if (!live)
+                    return false;
+                if (sameHandoff(messageHandoffPayload(live.messages.at(-1)), card))
+                    return true;
+                live.messages.push(marker);
+                this.store.save(live);
+                return true;
+            };
+            const messaging = this.isMessagingSession(sid);
+            const saved = messaging ? [await toStateDb(), toLocal()].some(Boolean) : toLocal() || await toStateDb();
+            // The caller may switch away on success, so a card saved nowhere is an error, not a summary.
+            if (!saved)
+                throw new HttpFailure(503, 'The handoff summary could not be saved; please retry.');
+        });
     }
     /** The session's compression job; a deleted session's finished result is dropped rather than served. */
     compressionJob(sid) {
@@ -1397,6 +1686,87 @@ export class SessionService {
         }
         return { session_id: branch.session_id, title, parent_session_id: source.session_id };
     }
+    /** Python `read_session_lineage_report` on the active profile's state.db. */
+    lineageReport(sid) {
+        return stateDbLineageReport(this.stateDbPath(null), sid);
+    }
+    /** TAL-259: recovery reads the active profile's state.db, and a recovered sidecar joins that profile. */
+    recoveryDeps() {
+        return { store: this.store, stateDbPath: this.stateDbPath(null), profile: this.deps.activeProfile(), stampingSince: this.deps.recoveryStampingSince(), log: this.deps.log };
+    }
+    recoveryAudit() {
+        return auditSessionRecovery(this.recoveryDeps());
+    }
+    recoveryRepairSafe() {
+        return repairSafeSessionRecovery(this.recoveryDeps());
+    }
+    /**
+     * 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.
+     */
+    async compressionRecoveryStart(sid) {
+        if (this.isSubagentViewOnly(sid))
+            throw new HttpFailure(400, 'Subagent sessions are view-only and cannot start compression recovery from WebUI');
+        const action = COMPRESSION_RECOVERY_ACTION_START_FOCUSED;
+        let created = false;
+        const child = await this.store.withLock(sid, () => {
+            // Validated under the lock: a delete that won it leaves no source to fork.
+            const source = this.store.get(sid);
+            if (!this.visibleToActiveProfile(source.profile))
+                throw new HttpFailure(404, 'Session not found');
+            if (!compressionRecoveryPayload(source))
+                throw new HttpFailure(409, 'Session does not have a compression recovery action.');
+            const existing = this.compressionRecoveryChild(sid, action, source.profile);
+            if (existing)
+                return existing;
+            const base = (source.title || 'Untitled').trim() || 'Untitled';
+            const fresh = new Session({
+                title: base.endsWith(' (focused continuation)') ? base : `${base} (focused continuation)`, workspace: source.workspace, model: source.model, model_provider: source.model_provider,
+                project_id: source.project_id, profile: source.profile, session_source: 'fork', personality: source.personality, enabled_toolsets: copyJson(source.enabled_toolsets),
+                context_length: source.context_length, threshold_tokens: source.threshold_tokens, gateway_routing: copyJson(source.gateway_routing), gateway_routing_history: copyJson(source.gateway_routing_history),
+                parent_session_id: source.session_id, worktree_path: source.worktree_path, worktree_branch: source.worktree_branch, worktree_repo_root: source.worktree_repo_root, worktree_created_at: source.worktree_created_at,
+                compression_recovery_source_session_id: sid, compression_recovery_action: action,
+                // An empty model-facing transcript: the focused follow-up must not replay the exhausted context.
+                messages: [], context_messages: [], composer_draft: { text: '', files: [] },
+            }, { workspace: source.workspace, model: source.model });
+            try {
+                this.store.save(fresh);
+            }
+            catch (error) {
+                throw new HttpFailure(500, `Failed to start compression recovery: ${sanitizePaths(error)}`);
+            }
+            this.store.touch(fresh);
+            created = true;
+            return fresh;
+        });
+        if (created)
+            this.publish('session_compression_recovery', child.profile, child.session_id);
+        return {
+            ok: true, session: this.publicSession(child), source_session_id: sid, recommended_recovery_action: action,
+            message: created ? 'Started a focused continuation. Describe the next narrow task to continue.' : 'Opened the existing focused continuation for this exhausted session.',
+        };
+    }
+    /** Python `find_compression_recovery_session`: the oldest same-profile continuation started from `sid`, cached or persisted. */
+    compressionRecoveryChild(sid, action, profile) {
+        const matches = (s) => s.compression_recovery_source_session_id === sid && s.compression_recovery_action === action && this.deps.profilesMatch(s.profile, profile);
+        const found = new Map();
+        for (const s of this.store.sessions.values())
+            if (matches(s))
+                found.set(s.session_id, s);
+        for (const id of this.store.persistedIds()) {
+            if (found.has(id) || this.store.sessions.has(id))
+                continue;
+            try {
+                const meta = this.store.get(id, { metadataOnly: true, promote: false, cacheOnMiss: false });
+                if (matches(meta))
+                    found.set(id, meta);
+            }
+            catch { /* unreadable: not a match */ }
+        }
+        const [oldest] = [...found.values()].sort((a, b) => (a.created_at || 0) - (b.created_at || 0) || (a.updated_at || 0) - (b.updated_at || 0) || (a.session_id < b.session_id ? -1 : 1));
+        return oldest ? this.store.get(oldest.session_id) : null;
+    }
     /** 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) {
         const live = this.deps.runtime.activeRunStream(sid);
@@ -1416,8 +1786,9 @@ export class SessionService {
         if (!isSafeSessionId(sid))
             throw new HttpFailure(400, 'Invalid session_id');
         // Python: a read-only import (persisted sidecar flag, sidebar metadata, or a foreign state.db owner such as a
-        // Claude Code session) is never deleted — that would erase the owner's authoritative transcript.
-        if (this.isReadOnlyImport(sid))
+        // Claude Code session) is never deleted — that would erase the owner's authoritative transcript. An orphan has none.
+        const orphaned = this.isOrphanedImport(sid);
+        if (!orphaned && this.isReadOnlyImport(sid))
             throw new HttpFailure(400, 'Read-only imported sessions cannot be deleted from WebUI');
         if (this.isSubagentViewOnly(sid))
             throw new HttpFailure(400, 'Subagent sessions are view-only and cannot be deleted from WebUI');
@@ -1437,11 +1808,7 @@ export class SessionService {
             hadSidecar = false;
         }
         // Python `_is_messaging_session_id`: decided before the JSON is gone, from WebUI metadata or the Agent's row.
-        const isMessaging = (() => { try {
-            if (isMessagingSessionRecord(this.store.get(sid, { metadataOnly: true }).compact()))
-                return true;
-        }
-        catch { /* absent */ } const meta = this.lookupCliMeta(sid); return meta !== null && isMessagingSessionRecord(meta); })();
+        const isMessaging = this.isMessagingSession(sid);
         if (this.activeRunBlocking(sid))
             throw new HttpFailure(409, 'Session has an active run; stop it before deleting');
         try {
@@ -1479,9 +1846,16 @@ export class SessionService {
         // Python: the Agent/CLI transcript in state.db goes too (else a claimable CLI row resurfaces in the sidebar), but a
         // messaging channel's memory is never erased from the WebUI; the actual outcome is reported.
         let stateDbCleanupFailed = false;
-        if (!isMessaging) {
+        if (!isMessaging && !orphaned) {
             // TAL-529: the compression continuations go too, tip first; the Agent's delete keeps and detaches them otherwise.
-            for (const id of stateDbCompressionLineage(this.stateDbPath(eventProfile), sid).reverse()) {
+            let lineage = [];
+            try {
+                lineage = stateDbCompressionLineage(this.stateDbPath(eventProfile), sid);
+            }
+            catch {
+                stateDbCleanupFailed = true;
+            }
+            for (const id of lineage.reverse()) {
                 try {
                     if (!(await this.deps.runtime.deleteCliSession(eventProfile, id)))
                         stateDbCleanupFailed = true;