evolcore 0.0.20 → 0.0.22

package/dist/core/session/session-fs-store.js

@@ -155,11 +155,160 @@ export function atomicWriteText(filePath, content) {
     atomicWrite(filePath, content);
 }
 export function appendJsonl(filePath, record) {
-    const line = JSON.stringify(record) + '\n';
-    const fd = fs.openSync(filePath, 'a');
-    fs.writeSync(fd, line);
-    fs.fsyncSync(fd);
-    fs.closeSync(fd);
+    const line = Buffer.from(JSON.stringify(record) + '\n');
+    const fd = fs.openSync(filePath, 'a+');
+    try {
+        recoverJsonlTail(fd, filePath);
+        writeAllSync(fd, line);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** Durable append used by authoritative topic Session snapshots. */
+export function appendJsonlDurable(filePath, record) {
+    const line = Buffer.from(JSON.stringify(record) + '\n');
+    const fd = fs.openSync(filePath, 'a+');
+    try {
+        recoverJsonlTail(fd, filePath);
+        writeAllSync(fd, line);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function writeAllSync(fd, content) {
+    let offset = 0;
+    while (offset < content.length) {
+        const written = fs.writeSync(fd, content, offset, content.length - offset, null);
+        if (written <= 0)
+            throw new Error('JSONL write made no progress');
+        offset += written;
+    }
+}
+/**
+ * Remove only an unterminated final record.  Committed (newline-terminated)
+ * bytes are never rewritten here; the latest reader is responsible for
+ * rejecting a malformed committed record instead of hiding it.
+ */
+function recoverJsonlTail(fd, filePath) {
+    const stat = fs.fstatSync(fd);
+    if (stat.size === 0)
+        return;
+    const finalByte = Buffer.allocUnsafe(1);
+    const finalRead = fs.readSync(fd, finalByte, 0, 1, stat.size - 1);
+    if (finalRead !== 1)
+        throw new Error(`short JSONL tail read while recovering ${filePath}`);
+    if (finalByte[0] === 0x0a)
+        return;
+    const chunkSize = 64 * 1024;
+    let cursor = stat.size;
+    let lastNewline = -1;
+    while (cursor > 0 && lastNewline < 0) {
+        const start = Math.max(0, cursor - chunkSize);
+        const length = cursor - start;
+        const chunk = Buffer.allocUnsafe(length);
+        let offset = 0;
+        while (offset < length) {
+            const read = fs.readSync(fd, chunk, offset, length - offset, start + offset);
+            if (read <= 0)
+                throw new Error(`short JSONL read while recovering ${filePath}`);
+            offset += read;
+        }
+        const index = chunk.lastIndexOf(0x0a);
+        if (index >= 0)
+            lastNewline = start + index;
+        cursor = start;
+    }
+    const committedSize = lastNewline < 0 ? 0 : lastNewline + 1;
+    if (committedSize !== stat.size) {
+        fs.ftruncateSync(fd, committedSize);
+        fs.fsyncSync(fd);
+    }
+}
+function readExactAt(fd, length, position, filePath) {
+    const content = Buffer.allocUnsafe(length);
+    let offset = 0;
+    while (offset < length) {
+        const read = fs.readSync(fd, content, offset, length - offset, position + offset);
+        if (read <= 0)
+            throw new Error(`short JSONL read at ${filePath}:${position + offset}`);
+        offset += read;
+    }
+    return content;
+}
+function findLastNewline(fd, endExclusive, filePath) {
+    const chunkSize = 64 * 1024;
+    let cursor = endExclusive;
+    while (cursor > 0) {
+        const start = Math.max(0, cursor - chunkSize);
+        const chunk = readExactAt(fd, cursor - start, start, filePath);
+        const index = chunk.lastIndexOf(0x0a);
+        if (index >= 0)
+            return start + index;
+        cursor = start;
+    }
+    return -1;
+}
+function parseJsonlLineStrict(line, filePath, location) {
+    try {
+        return JSON.parse(line);
+    }
+    catch (cause) {
+        const error = new Error(`Invalid committed JSONL record at ${filePath}:${location}`, { cause });
+        error.code = 'JSONL_COMMITTED_RECORD_INVALID';
+        throw error;
+    }
+}
+/**
+ * Read only the latest newline-terminated JSONL record. An unterminated tail
+ * is uncommitted and ignored; a malformed latest committed record is fatal.
+ */
+export function readLastJsonlLineStrict(filePath) {
+    let fd;
+    try {
+        fd = fs.openSync(filePath, 'r');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    try {
+        const size = fs.fstatSync(fd).size;
+        if (size === 0)
+            return undefined;
+        const finalByte = readExactAt(fd, 1, size - 1, filePath)[0];
+        const finalNewline = finalByte === 0x0a ? size - 1 : findLastNewline(fd, size, filePath);
+        if (finalNewline < 0)
+            return undefined;
+        let lineEnd = finalNewline;
+        while (lineEnd >= 0) {
+            const previousNewline = findLastNewline(fd, lineEnd, filePath);
+            const lineStart = previousNewline + 1;
+            const line = readExactAt(fd, lineEnd - lineStart, lineStart, filePath).toString('utf8').trim();
+            if (line)
+                return parseJsonlLineStrict(line, filePath, lineStart);
+            if (previousNewline < 0)
+                return undefined;
+            lineEnd = previousNewline;
+        }
+        return undefined;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** Reconfirm durability after an append reported an indeterminate failure. */
+export function fsyncJsonlFile(filePath) {
+    const fd = fs.openSync(filePath, 'r+');
+    try {
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
 }
 export function readJsonFile(filePath) {
     try {

package/dist/core/session/session-manager.js

@@ -1,13 +1,25 @@
 import { ensureDir } from '../../utils/atomic-write.js';
 import { logger } from '../../utils/logger.js';
 import { encodePath } from '../../utils/cross-platform.js';
-import { chatDirPath, generateSessionId, formatTimestamp, atomicWriteJson, atomicWriteText, appendJsonl, readJsonFile, readLastJsonlLine, readAllJsonlLines, scanChatDirs, scanMetaFiles, ensureChatDir, readThreadIndex, writeThreadIndex, } from './session-fs-store.js';
+import { chatDirPath, generateSessionId, formatTimestamp, atomicWriteJson, atomicWriteText, appendJsonl, appendJsonlDurable, fsyncJsonlFile, readJsonFile, readLastJsonlLine, readLastJsonlLineStrict, readAllJsonlLines, scanChatDirs, scanMetaFiles, ensureChatDir, readThreadIndex, writeThreadIndex, } from './session-fs-store.js';
 import { sessionToFile, fileToSession, formatSessionKey, DEFAULT_THREAD_ID } from './session-mapper.js';
 import { tryParseChannelKey } from '../channel-loader.js';
 import { isSystemControlChannel } from '../system-channels.js';
 import path from 'path';
 import fs from 'fs';
 import os from 'os';
+/** Metadata keys owned by ordinary topic/session routing writers. */
+const TOPIC_METADATA_PROTECTED_KEYS = new Set(['turnState', 'resumeAt', 'agentSessions']);
+const TOPIC_BACKEND_SCOPED_KEYS = ['resumeAt', 'agentSessions'];
+function topicMetadataOwnershipError(key) {
+    const error = new Error(`topic metadata field is owned by a dedicated updater: ${key}`);
+    error.code = 'TOPIC_METADATA_OWNERSHIP';
+    return error;
+}
+export function normalizeBackendSessionId(value) {
+    const normalized = typeof value === 'string' ? value.trim() : '';
+    return normalized.length > 0 ? normalized : undefined;
+}
 function newSessionStableMetadata(chatType, ...sources) {
     const keys = chatType === 'group'
         ? ['channelKey', 'groupId', 'groupName', 'mentionMode']
@@ -280,7 +292,11 @@ export class SessionManager {
     }
     appendMeta(channel, channelId, session) {
         const file = sessionToFile(session);
-        appendJsonl(this.metaPathForSession(session), file);
+        const metaPath = this.metaPathForSession(session);
+        if (session.threadId)
+            appendJsonlDurable(metaPath, file);
+        else
+            appendJsonl(metaPath, file);
     }
     /**
      * Session 持久化的唯一事务原语。所有 session 写操作都应经此，业务层不直接调
@@ -301,8 +317,50 @@ export class SessionManager {
      * @returns 是否真的写入了 .jsonl（去重命中时返回 false）
      */
     persistSession(session, intent, opts) {
+        // Topic session snapshots can be written by synchronous legacy paths
+        // (mark/clear processing) after an async /renew has committed.  Preserve
+        // the newest backend fence unless this call is one of the two explicit
+        // boundary writers.  This is a last-line guard against a stale object
+        // replaying an old agentSessionId into the JSONL history.
+        if (session.threadId && !opts?.backendMutation) {
+            const latest = this.readMetaLatest(this.metaPathForSession(session));
+            const latestId = normalizeBackendSessionId(latest?.agentSessionId);
+            if (latest) {
+                // Generic writers may update turn/route metadata, but never the
+                // backend boundary itself. Always take the latest binding and owner.
+                session.agentSessionId = latestId;
+                session.baseagent = latest.baseagent;
+                // Merge metadata at field level as well.  A caller can hold a stale
+                // Session object across an await; preserving keys from the latest
+                // snapshot prevents unrelated turn/route updates from being erased.
+                // The backend boundary remains entirely owned by the latest snapshot.
+                const requestedMetadata = session.metadata ?? {};
+                const mergedMetadata = {
+                    ...(latest.metadata ?? {}),
+                    ...requestedMetadata,
+                    ...(!opts?.turnStateMutation
+                        ? (latest.metadata?.turnState
+                            ? { turnState: JSON.parse(JSON.stringify(latest.metadata.turnState)) }
+                            : { turnState: undefined })
+                        : {}),
+                };
+                for (const key of TOPIC_BACKEND_SCOPED_KEYS) {
+                    if (Object.prototype.hasOwnProperty.call(latest.metadata ?? {}, key)) {
+                        const value = latest.metadata[key];
+                        mergedMetadata[key] = value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+                    }
+                    else {
+                        delete mergedMetadata[key];
+                    }
+                }
+                session.metadata = mergedMetadata;
+            }
+        }
         if (!opts?.forceWrite) {
-            const lastMeta = readLastJsonlLine(this.metaPathForSession(session));
+            const metaPath = this.metaPathForSession(session);
+            const lastMeta = session.threadId
+                ? readLastJsonlLineStrict(metaPath)
+                : readLastJsonlLine(metaPath);
             if (lastMeta && this.sessionFilesEqual(lastMeta, sessionToFile(session))) {
                 // .jsonl 末行已与目标一致：仍可能需要把缓存对齐（'set' 语义）
                 if (intent === 'set') {
@@ -334,7 +392,10 @@ export class SessionManager {
         return JSON.stringify(stripVolatile(a)) === JSON.stringify(stripVolatile(b));
     }
     readMetaLatest(metaFilePath) {
-        const file = readLastJsonlLine(metaFilePath);
+        const isTopic = path.basename(path.dirname(metaFilePath)) === '_threads';
+        const file = isTopic
+            ? readLastJsonlLineStrict(metaFilePath)
+            : readLastJsonlLine(metaFilePath);
         if (!file)
             return undefined;
         return fileToSession(file);
@@ -342,13 +403,10 @@ export class SessionManager {
     /**
      * 为 by-sessionId 改方法加载"当前 session 状态"。
      *
-     * 设计契约（docs/refactor/01-db-to-fs.md）：
-     *   active.json 是热路径权威源。.jsonl 是历史档案。
-     *
      * 读取策略：
      *   1. 先按 sessionId 定位 .jsonl 文件（确认 session 存在 + 拿到 channel/channelId）
-     *   2. 优先读 active.json（如果 active.id === sessionId）—— 当前状态
-     *   3. 否则 fallback 到 .jsonl 末行 —— 非活跃 session 的更新（如多 session 并存时改非 active 那个）
+     *   2. topic session 始终读取 .jsonl 最新有效 snapshot；active.json 只是缓存
+     *   3. 主 session 保持既有 active.json 热路径兼容，找不到时回退 .jsonl 末行
      *
      * 返回 { current }：caller 修改后交给 persistSession 写回（去重由 persistSession 内建）。
      */
@@ -360,9 +418,9 @@ export class SessionManager {
         const fromJsonl = this.readMetaLatest(found.metaPath);
         if (!fromJsonl)
             return undefined;
-        // 优先用 active.json 的当前状态（如果它就是这个 sessionId）
+        // active.json 不能参与 topic backend boundary/CAS；它可能落后于线程 JSONL。
         const active = this.readActive(fromJsonl.channel, fromJsonl.channelId);
-        const base = (active && active.id === sessionId) ? active : fromJsonl;
+        const base = (!fromJsonl.threadId && active && active.id === sessionId) ? active : fromJsonl;
         const current = JSON.parse(JSON.stringify(base));
         return { current };
     }
@@ -441,6 +499,111 @@ export class SessionManager {
         }
         return threadIds;
     }
+    latestSessionForBoundary(sessionId) {
+        const found = this.findSessionFileById(sessionId);
+        if (!found)
+            return { found };
+        return { found, session: this.readMetaLatest(found.metaPath) };
+    }
+    /**
+     * The single short read-modify-append primitive for topic backend fields.
+     * The callback must remain synchronous: all filesystem operations in this
+     * critical section are synchronous, so no await can interleave a stale
+     * snapshot between validation and append in the single-process daemon.
+     */
+    mutateLatestTopicSession(sessionId, mutation) {
+        const state = this.latestSessionForBoundary(sessionId);
+        if (!state.found || !state.session) {
+            const error = new Error(`session not found: ${sessionId}`);
+            error.code = 'SESSION_NOT_FOUND';
+            throw error;
+        }
+        // Keep this callback synchronous. Node cannot interleave another
+        // read-modify-append while the strict latest read and append are running.
+        return mutation(state.session, state.found);
+    }
+    persistConfirmedTopicBoundary(current, found, next) {
+        try {
+            this.persistSession(next, 'none', { forceWrite: true, backendMutation: true });
+        }
+        catch (error) {
+            // A synchronous append can report a late failure after the complete
+            // target line is visible. Confirm only the exact latest boundary; the
+            // operation history is deliberately not part of this protocol.
+            const confirmed = this.readMetaLatest(found.metaPath);
+            if (confirmed && this.sessionFilesEqual(sessionToFile(confirmed), sessionToFile(next))) {
+                try {
+                    fsyncJsonlFile(found.metaPath);
+                }
+                catch (syncError) {
+                    const persistenceError = new Error('topic backend mutation durability is unknown', { cause: syncError });
+                    persistenceError.code = 'BACKEND_PERSISTENCE_UNKNOWN';
+                    throw persistenceError;
+                }
+                return;
+            }
+            throw error;
+        }
+    }
+    /** Clear a topic binding in one short latest-snapshot mutation. */
+    async rotateTopicBackend(input) {
+        if (!input.expectedThreadId.trim())
+            throw new Error('backend rotation requires a non-empty threadId');
+        return this.mutateLatestTopicSession(input.sessionId, (current, found) => {
+            if (!current.threadId || current.threadId !== input.expectedThreadId) {
+                const error = new Error('backend rotation threadId mismatch');
+                error.code = 'THREAD_MISMATCH';
+                throw error;
+            }
+            const wasBound = !!normalizeBackendSessionId(current.agentSessionId);
+            const next = JSON.parse(JSON.stringify(current));
+            next.agentSessionId = undefined;
+            const nextMetadata = { ...(next.metadata ?? {}) };
+            delete nextMetadata.resumeAt;
+            delete nextMetadata.agentSessions;
+            next.metadata = nextMetadata;
+            this.persistConfirmedTopicBoundary(current, found, next);
+            return { status: 'rotated', sessionId: input.sessionId, wasBound };
+        });
+    }
+    /**
+     * Bind a backend discovered by the currently active turn.
+     * A stale or retired discovery is a normal, non-throwing rejection so the
+     * runner can dispose only its local runtime.
+     */
+    async activateTopicBackend(input) {
+        const agentSessionId = normalizeBackendSessionId(input.agentSessionId);
+        if (!agentSessionId)
+            return 'stale';
+        if (input.lease.sessionId !== input.sessionId
+            || !Number.isSafeInteger(input.lease.generation) || input.lease.generation < 0
+            || !input.lease.taskId.trim() || !input.lease.turnId.trim() || !input.lease.inputId.trim()) {
+            const error = new Error('backend activation turn lease is invalid');
+            error.code = 'BACKEND_TURN_LEASE_INVALID';
+            throw error;
+        }
+        return this.mutateLatestTopicSession(input.sessionId, (current, found) => {
+            if (!current.threadId)
+                return 'stale';
+            const active = current.metadata?.turnState?.active;
+            if (!active
+                || active.taskId !== input.lease.taskId
+                || active.turnId !== input.lease.turnId
+                || active.generation !== input.lease.generation
+                || active.inputId !== input.lease.inputId
+                || current.metadata?.turnState?.generation !== input.lease.generation)
+                return 'stale';
+            const currentId = normalizeBackendSessionId(current.agentSessionId);
+            if (currentId === agentSessionId)
+                return 'already_active';
+            if (currentId && currentId !== agentSessionId)
+                return 'conflict';
+            const next = JSON.parse(JSON.stringify(current));
+            next.agentSessionId = agentSessionId;
+            this.persistConfirmedTopicBoundary(current, found, next);
+            return 'activated';
+        });
+    }
     markProcessing(sessionId, taskId) {
         const now = Date.now();
         const state = taskId ? `${now}:${taskId}` : String(now);
@@ -515,17 +678,31 @@ export class SessionManager {
         const result = [];
         const chatDirs = scanChatDirs(this.sessionsDir);
         for (const { dirPath } of chatDirs) {
-            for (const metaFile of scanMetaFiles(dirPath)) {
-                const session = this.readMetaLatest(path.join(dirPath, metaFile));
-                if (!session?.processingState)
-                    continue;
-                const colonIdx = session.processingState.indexOf(':');
-                const ts = parseInt(colonIdx > 0 ? session.processingState.slice(0, colonIdx) : session.processingState, 10);
-                if (!isNaN(ts) && (now - ts) < maxAgeMs) {
-                    result.push(session);
-                }
-                else {
-                    this.clearProcessing(session.id);
+            // Startup recovery covers both main and topic sessions. Topic metadata
+            // is read strictly; one corrupt committed record must not make the
+            // daemon abandon recovery for every other chat.
+            const metaDirs = [dirPath, path.join(dirPath, '_threads')];
+            for (const metaDir of metaDirs) {
+                for (const metaFile of scanMetaFiles(metaDir)) {
+                    const metaPath = path.join(metaDir, metaFile);
+                    let session;
+                    try {
+                        session = this.readMetaLatest(metaPath);
+                    }
+                    catch (error) {
+                        logger.error(`[SessionManager] Skipping corrupt session metadata during startup recovery: ${metaPath}: ${error instanceof Error ? error.message : String(error)}`);
+                        continue;
+                    }
+                    if (!session?.processingState)
+                        continue;
+                    const colonIdx = session.processingState.indexOf(':');
+                    const ts = parseInt(colonIdx > 0 ? session.processingState.slice(0, colonIdx) : session.processingState, 10);
+                    if (!isNaN(ts) && (now - ts) < maxAgeMs) {
+                        result.push(session);
+                    }
+                    else {
+                        this.clearProcessing(session.id);
+                    }
                 }
             }
         }
@@ -651,6 +828,7 @@ export class SessionManager {
         }
         // Create new session
         const sessionMetadata = { ...(metadata || {}) };
+        sessionMetadata.__sessionCreatedAt = Date.now();
         const newIdentity = identity ?? this.resolveIdentity(channel, userId, chatType, identityConversationId);
         const resolvedBaseagent = baseagent || 'claude';
         const session = {
@@ -684,22 +862,86 @@ export class SessionManager {
         return session;
     }
     async updateSession(sessionId, updates) {
+        // This operation only holds the short synchronous snapshot writer inside
+        // persistSession; it must not wait behind a long-running boundary action.
         const loaded = this.loadSessionForUpdate(sessionId);
         if (!loaded)
             return;
         const { current } = loaded;
+        if (current.threadId && updates.baseagent !== undefined) {
+            const error = new Error('topic baseagent is immutable while backend rotation is managed');
+            error.code = 'TOPIC_BASEAGENT_IMMUTABLE';
+            throw error;
+        }
+        if (current.threadId && Object.prototype.hasOwnProperty.call(updates, 'agentSessionId')) {
+            const error = new Error('topic backend binding requires rotation or turn-lease activation');
+            error.code = 'TOPIC_BACKEND_BINDING_PROTECTED';
+            throw error;
+        }
         if (updates.baseagent !== undefined)
             current.baseagent = updates.baseagent;
         if (updates.chatType !== undefined)
             current.chatType = updates.chatType;
         if (updates.name !== undefined)
             current.name = updates.name;
-        if (updates.metadata !== undefined)
-            current.metadata = updates.metadata;
-        if ('agentSessionId' in updates)
-            current.agentSessionId = updates.agentSessionId ?? undefined;
+        if (updates.metadata !== undefined) {
+            if (current.threadId) {
+                for (const key of Object.keys(updates.metadata)) {
+                    if (TOPIC_METADATA_PROTECTED_KEYS.has(key))
+                        throw topicMetadataOwnershipError(key);
+                }
+            }
+            current.metadata = {
+                ...(current.metadata ?? {}),
+                ...updates.metadata,
+            };
+        }
+        if ('agentSessionId' in updates) {
+            current.agentSessionId = normalizeBackendSessionId(updates.agentSessionId);
+        }
+        // The generic update API is not allowed to mutate a topic backend
+        // boundary. Explicit rotation/activation APIs are the only writers that
+        // may change the binding.
+        this.persistSession(current, 'sync');
+    }
+    /**
+     * Apply a route/display metadata patch without accepting backend or turn
+     * ownership. `undefined` removes a field from the next snapshot.
+     */
+    async patchSessionMetadata(sessionId, patch) {
+        const loaded = this.loadSessionForUpdate(sessionId);
+        if (!loaded)
+            return;
+        const { current } = loaded;
+        for (const key of Object.keys(patch)) {
+            if (current.threadId && TOPIC_METADATA_PROTECTED_KEYS.has(key)) {
+                throw topicMetadataOwnershipError(key);
+            }
+        }
+        const metadata = { ...(current.metadata ?? {}) };
+        for (const [key, value] of Object.entries(patch)) {
+            if (value === undefined)
+                delete metadata[key];
+            else
+                metadata[key] = value;
+        }
+        current.metadata = metadata;
         this.persistSession(current, 'sync');
     }
+    /** Persist only the turn coordinator-owned metadata field. */
+    async updateTurnState(sessionId, turnState) {
+        const loaded = this.loadSessionForUpdate(sessionId);
+        if (!loaded)
+            return;
+        const { current } = loaded;
+        const metadata = { ...(current.metadata ?? {}) };
+        if (turnState === undefined)
+            delete metadata.turnState;
+        else
+            metadata.turnState = JSON.parse(JSON.stringify(turnState));
+        current.metadata = metadata;
+        this.persistSession(current, 'sync', { turnStateMutation: true });
+    }
     getOrCreateThreadSession(channel, channelId, threadId, defaultProjectPath, metadata, name, baseagent, selfAID, channelType, peerType, chatType) {
         // 使用精确路径（channelType + selfAID）
         const chatDir = (channelType && selfAID)
@@ -711,7 +953,14 @@ export class SessionManager {
             const metaPath = path.join(chatDir, '_threads', `${existingEntry.sessionId}.jsonl`);
             const existing = this.readMetaLatest(metaPath);
             if (existing) {
-                const validSessionId = this.validateSessionFile(existing);
+                // Topic JSONL is the authoritative backend boundary.  A missing
+                // provider file must not be converted into an in-memory UNBOUND view
+                // by this generic lookup; doing so would let the next run create a
+                // backend without an explicit rotation.  Repair/rotation decides how
+                // to handle an unavailable bound backend.
+                const validSessionId = existing.threadId
+                    ? normalizeBackendSessionId(existing.agentSessionId)
+                    : this.validateSessionFile(existing);
                 let mutated = false;
                 if (metadata) {
                     const creatorPeerId = existing.metadata?.peerId;
@@ -831,19 +1080,64 @@ export class SessionManager {
         const active = this.readActive(channel, channelId);
         if (!active)
             return;
+        if (active.threadId) {
+            // Topic backend binding is owned exclusively by rotation or an active
+            // TurnLease activation. Keep this legacy channel-scoped API main-session
+            // only so stale callers cannot resurrect a renewed topic backend.
+            logger.warn(`[SessionManager] Ignoring topic agentSessionId update through legacy channel API: sessionId=${active.id}`);
+            return;
+        }
         active.agentSessionId = agentSessionId;
         this.persistSession(active, 'sync');
     }
-    async updateAgentSessionIdBySessionId(sessionId, agentSessionId) {
+    async updateAgentSessionIdBySessionId(sessionId, agentSessionId, turnLease) {
         const loaded = this.loadSessionForUpdate(sessionId);
         if (!loaded)
-            return;
+            return 'stale';
         const { current } = loaded;
+        if (current.threadId) {
+            if (turnLease && normalizeBackendSessionId(agentSessionId)) {
+                return this.activateTopicBackend({ sessionId, lease: turnLease, agentSessionId });
+            }
+            // Topic backend binding is never writable through the legacy API.  Empty
+            // callbacks may still clear runner-local state, but cannot clear the
+            // authoritative Session without a boundary-scoped operation.
+            logger.warn(`[SessionManager] Ignoring topic agentSessionId update without an active turn lease: sessionId=${sessionId}`);
+            return 'stale';
+        }
         current.agentSessionId = agentSessionId;
         const wrote = this.persistSession(current, 'sync');
         if (wrote) {
             logger.info(`[SessionManager] Updating agent_session_id: sessionId=${sessionId}, agentSessionId=${agentSessionId}`);
         }
+        return 'legacy_updated';
+    }
+    /**
+     * Clear a main-session backend only when the durable latest snapshot still
+     * points at the caller's expected ID. This is the recovery counterpart to
+     * provider-side "session not found" errors and must never rotate a topic.
+     */
+    async clearMainSessionBackendIfMatches(sessionId, expectedAgentSessionId, metadataKeys = []) {
+        const loaded = this.loadSessionForUpdate(sessionId);
+        if (!loaded)
+            return 'missing';
+        const { current } = loaded;
+        if (current.threadId)
+            return 'topic';
+        const currentId = normalizeBackendSessionId(current.agentSessionId);
+        if (!currentId)
+            return 'already_clear';
+        if (currentId !== normalizeBackendSessionId(expectedAgentSessionId))
+            return 'mismatch';
+        current.agentSessionId = undefined;
+        if (metadataKeys.length > 0 && current.metadata) {
+            const metadata = { ...current.metadata };
+            for (const key of metadataKeys)
+                delete metadata[key];
+            current.metadata = metadata;
+        }
+        this.persistSession(current, 'sync');
+        return 'cleared';
     }
     async switchAgent(channel, channelId, projectPath, newBaseagent) {
         const inheritedChatType = this.getActiveChatType(channel, channelId);
@@ -965,7 +1259,10 @@ export class SessionManager {
         const session = this.readMetaLatest(metaPath);
         if (!session)
             return undefined;
-        const validSessionId = this.validateSessionFile(session);
+        // Do not consult provider-file existence to derive topic binding state;
+        // the topic JSONL boundary is authoritative and may intentionally point
+        // at a backend that needs an explicit /renew or repair operation.
+        const validSessionId = normalizeBackendSessionId(session.agentSessionId);
         return { ...session, agentSessionId: validSessionId };
     }
     async listSessions(channel, channelId) {
@@ -1155,6 +1452,7 @@ export class SessionManager {
             throw new Error(`[SessionManager] createNewSession: baseagent is empty for channel=${channel} channelId=${channelId}`);
         }
         const metadata = newSessionStableMetadata(inheritedChatType, activeMetadata, identityMetadata);
+        metadata.__sessionCreatedAt = Date.now();
         if (identityMetadata?.sessionBoundaryOperationId) {
             metadata.sessionBoundaryOperationId = identityMetadata.sessionBoundaryOperationId;
         }
@@ -1317,6 +1615,7 @@ export class SessionManager {
         delete metadata.agentSessions;
         delete metadata.resumeAt;
         delete metadata.replyContext;
+        metadata.__sessionRenewedAt = Date.now();
         const session = {
             id: generateSessionId(),
             channel: sourceSession.channel,