@myagentroam/node 0.1.0 → 0.1.1

package/dist/connector.js

@@ -8,8 +8,8 @@ import { createEnvelope, nodeCapabilitiesSchema, nodeEnvelopeSchema, runnerDefau
 import { loadNodeConfig, nodeDatabasePath, saveNodeConfig } from './config.js';
 import { NodeMetrics, nodeLog } from './operational.js';
 import { assertLocalSqlitePath } from './storage.js';
-import { detectCapabilities } from './capabilities.js';
-import { inspectWorkspace, listWorkspaceDirectories, listWorkspaceFiles, preflightWorkspaceUpload, readCurrentChangeDiff, readCurrentChangesSummary, readGitSummary, readRestrictedDiff, readAllowedTextFile, readWorkspaceTextFile, restoreCurrentChange, searchWorkspaceFiles, workspaceUploadTemporaryName } from './workspace.js';
+import { detectCapabilitiesAsync, unavailableCapabilities } from './capabilities.js';
+import { inspectWorkspace, listWorkspaceDirectories, listWorkspaceFiles, preflightWorkspaceUpload, readCurrentChangeDiff, readCurrentChangesSummary, readGitSummary, readRestrictedDiff, readAllowedTextFile, readWorkspaceTextFile, restoreCurrentChange, WorkspaceFileIndex, workspaceUploadTemporaryName } from './workspace.js';
 import { ReliableWorkbenchEventBuffer } from './event-buffer.js';
 import { CodexAppServerClient, codexSessionControl } from './codex-app-server.js';
 import { ClaudeAgentSdkAdapter, denyPermission } from './claude-agent-sdk.js';
@@ -22,9 +22,16 @@ import { NodeRuntimeState } from './runtime-state.js';
 import { CommandStateStore, parseCommandInvocation } from './runner-command-engine.js';
 import { RunnerUsageReader } from './runner-usage.js';
 const HEARTBEAT_MS = 15_000;
+const WORKSPACE_FILE_INDEX_CACHE_LIMIT = 8;
+const WORKSPACE_WATCH_TTL_MS = 45_000;
+const WORKSPACE_SESSION_WATCH_INTERVAL_MS = 30_000;
+const WORKSPACE_SESSION_CACHE_TTL_MS = 15_000;
+const WORKSPACE_CHANGES_CACHE_TTL_MS = 5_000;
+const CAPABILITY_REFRESH_MS = 60_000;
 const SESSION_WATCH_INTERVAL_MS = 2_000;
 const SESSION_WATCH_TTL_MS = 45_000;
 const SESSION_WATCH_MAX_FAILURES = 3;
+const SESSION_WATCH_INITIAL_TURN_LIMIT = 30;
 const RETRY_MIN_MS = 500;
 const RETRY_MAX_MS = 30_000;
 const CLAUDE_APPROVAL_TIMEOUT_MS = 10 * 60_000;
@@ -87,12 +94,16 @@ export class NodeConnector {
     socket;
     terminalSocket;
     heartbeat;
+    capabilityRefreshTimer;
+    capabilityRefreshInFlight = false;
     reconnectTimer;
     terminalReconnectTimer;
     attempts = 0;
     stopped = false;
     config;
+    capabilitiesProvided;
     capabilities;
+    capabilityDetector;
     configPath;
     reconnect;
     claudeApprovalTimeoutMs;
@@ -158,6 +169,18 @@ export class NodeConnector {
     composerAttachments = new Map();
     /** Identical refreshes share one Git scan; separate Workspaces use bounded parallelism. */
     workspaceChangesReads = new Map();
+    workspaceChangesCache = new Map();
+    workspaceChangesVersions = new Map();
+    workspaceFileIndexes = new Map();
+    /** Tab-scoped Workspace observation leases; no state survives a Node restart. */
+    workspaceWatches = new Map();
+    workspaceWatchRevisions = new Map();
+    workspaceSessionWatchTimers = new Map();
+    workspaceSessionWatchSignatures = new Map();
+    workspaceSessionWatchReads = new Map();
+    /** Runner-native session discovery is expensive; cache only its short-lived baseline. */
+    workspaceSessionCache = new Map();
+    workspaceSessionCacheReads = new Map();
     workspaceChangesLimiter = new AsyncLimiter(3);
     database;
     /** Runtime/session state is intentionally not persisted to Node SQLite. */
@@ -166,7 +189,9 @@ export class NodeConnector {
     constructor(options = {}) {
         this.config = options.config;
         this.configPath = options.configPath;
-        this.capabilities = options.capabilities ?? detectCapabilities();
+        this.capabilitiesProvided = options.capabilities !== undefined;
+        this.capabilities = options.capabilities ?? unavailableCapabilities();
+        this.capabilityDetector = options.capabilityDetector ?? detectCapabilitiesAsync;
         this.reconnect = options.reconnect ?? true;
         this.fakeRunner = options.fakeRunner;
         this.fakeScript = options.fakeScript;
@@ -179,7 +204,7 @@ export class NodeConnector {
         this.terminalManager =
             options.terminalManager ??
                 new TerminalManager({
-                    platform: this.capabilities.platform
+                    platform: this.capabilities.platform === 'windows' ? 'win32' : 'linux'
                 });
         this.terminalManager.onSummary((summary) => this.persistTerminalSession(summary));
         this.terminalManager.onFrame((frame) => this.publishTerminalFrame(frame));
@@ -191,12 +216,15 @@ export class NodeConnector {
         this.database ??= new NodeDatabase(nodeDatabasePath(this.config, this.configPath), () => this.config?.nodeId ?? 'unregistered');
         this.database.closeRunningTerminalSessions();
         this.reconcilePersistedRuns();
+        this.startCapabilityRefresh();
         this.connect();
     }
     stop() {
         this.stopped = true;
         if (this.heartbeat !== undefined)
             clearInterval(this.heartbeat);
+        if (this.capabilityRefreshTimer !== undefined)
+            clearInterval(this.capabilityRefreshTimer);
         if (this.reconnectTimer !== undefined)
             clearTimeout(this.reconnectTimer);
         if (this.terminalReconnectTimer !== undefined)
@@ -233,6 +261,22 @@ export class NodeConnector {
         for (const upload of this.workspaceUploads.values())
             void this.removeWorkspaceUpload(upload);
         this.workspaceUploads.clear();
+        for (const index of this.workspaceFileIndexes.values())
+            index.dispose();
+        this.workspaceFileIndexes.clear();
+        for (const watches of this.workspaceWatches.values())
+            for (const watch of watches.values())
+                clearTimeout(watch.timer);
+        this.workspaceWatches.clear();
+        for (const timer of this.workspaceSessionWatchTimers.values())
+            clearInterval(timer);
+        this.workspaceSessionWatchTimers.clear();
+        this.workspaceSessionWatchSignatures.clear();
+        this.workspaceSessionWatchReads.clear();
+        this.workspaceSessionCache.clear();
+        this.workspaceSessionCacheReads.clear();
+        this.workspaceChangesCache.clear();
+        this.workspaceChangesVersions.clear();
         for (const attachment of this.composerAttachments.values())
             void rm(dirname(attachment.targetPath), { recursive: true, force: true });
         this.composerAttachments.clear();
@@ -245,6 +289,39 @@ export class NodeConnector {
         this.database?.close();
         this.database = undefined;
     }
+    startCapabilityRefresh() {
+        if (this.capabilityRefreshTimer !== undefined)
+            clearInterval(this.capabilityRefreshTimer);
+        if (!this.capabilitiesProvided)
+            void this.refreshCapabilities();
+        this.capabilityRefreshTimer = setInterval(() => void this.refreshCapabilities(), CAPABILITY_REFRESH_MS);
+    }
+    async refreshCapabilities() {
+        if (this.stopped || this.capabilityRefreshInFlight)
+            return;
+        this.capabilityRefreshInFlight = true;
+        let next;
+        try {
+            next = await this.capabilityDetector();
+        }
+        catch {
+            // A failed local probe keeps Node metadata but safely disables both Runner capabilities.
+            next = {
+                ...this.capabilities,
+                codex: { available: false },
+                claudeCode: { available: false }
+            };
+        }
+        try {
+            if (this.stopped || JSON.stringify(next) === JSON.stringify(this.capabilities))
+                return;
+            this.capabilities = next;
+            this.send('capabilities', next);
+        }
+        finally {
+            this.capabilityRefreshInFlight = false;
+        }
+    }
     connect() {
         const config = this.config;
         if (config === undefined)
@@ -570,7 +647,7 @@ export class NodeConnector {
                 // available. Do not leave the local lease in CANCELLING indefinitely:
                 // an already-created, but not yet controllable, Codex run is checked
                 // again immediately after turn/start resolves.
-                if (envelope.type === 'run.cancel' && codexRun === undefined && claudeRun === undefined) {
+                if (codexRun?.turnId === undefined && claudeRun === undefined) {
                     const run = this.runtime.getRun(runId);
                     if (run?.status === 'CANCELLING')
                         this.completeCancelledRun(runId, undefined);
@@ -612,7 +689,14 @@ export class NodeConnector {
             return;
         }
         try {
-            const result = await this.executeNodeOperation(payload.operation, payload.data);
+            const data = payload.data !== null && typeof payload.data === 'object'
+                ? {
+                    ...payload.data,
+                    __workspaceWatchSessionHash: payload.userAuthorization
+                        .sessionHash
+                }
+                : payload.data;
+            const result = await this.executeNodeOperation(payload.operation, data);
             this.send('node.response', { result }, envelope.id);
         }
         catch (error) {
@@ -661,6 +745,12 @@ export class NodeConnector {
                 throw new Error('WORKSPACE_BUSY');
             const workspace = database.removeWorkspace(input.workspaceId);
             this.runtime.removeWorkspace(input.workspaceId);
+            this.workspaceFileIndexes.get(workspace.id)?.dispose();
+            this.workspaceFileIndexes.delete(workspace.id);
+            this.invalidateWorkspaceChanges(workspace.id);
+            this.workspaceSessionCache.delete(workspace.id);
+            this.workspaceSessionCacheReads.delete(workspace.id);
+            this.clearWorkspaceWatches(workspace.id);
             return { workspace };
         }
         if (operation === 'workspace.list')
@@ -737,6 +827,10 @@ export class NodeConnector {
                     typeof input.customTitle !== 'string') ||
                 (input.pinned !== undefined && typeof input.pinned !== 'boolean'))
                 throw new Error('SESSION_INVALID');
+            if (input.customTitle === null || input.customTitle?.trim().length === 0)
+                throw new Error('SESSION_TITLE_REQUIRED');
+            if (input.customTitle !== undefined && input.customTitle.trim().length > 160)
+                throw new Error('SESSION_TITLE_INVALID');
             const current = this.runtime.getAgentSession(input.sessionId) ??
                 (await this.createMetadataProjection(input.sessionId));
             if (current === undefined)
@@ -760,6 +854,13 @@ export class NodeConnector {
                     : updated)
             };
         }
+        if (operation === 'session.pin.move') {
+            if (typeof input.sessionId !== 'string' ||
+                (input.direction !== 'up' && input.direction !== 'down'))
+                throw new Error('SESSION_PIN_MOVE_INVALID');
+            database.movePinnedSession(input.sessionId, input.direction);
+            return { moved: true };
+        }
         if (operation === 'session.remove') {
             if (typeof input.sessionId !== 'string')
                 throw new Error('SESSION_INVALID');
@@ -777,8 +878,16 @@ export class NodeConnector {
                     throw new Error('SESSION_ACTIVE');
             }
             const nativeSessionIds = this.nativeSessionIdsForProjection(session);
-            for (const externalSessionId of nativeSessionIds)
-                await removeNativeSession(session.runner, session.cwd, externalSessionId);
+            for (const externalSessionId of nativeSessionIds) {
+                try {
+                    await removeNativeSession(session.runner, session.cwd, externalSessionId);
+                }
+                catch (error) {
+                    if (!(error instanceof Error) || error.message !== 'NATIVE_TRANSCRIPT_UNAVAILABLE')
+                        throw error;
+                }
+            }
+            database.deleteSessionRecord(session.id);
             this.forgetNativeSessionProjection(session, nativeSessionIds);
             return { deleted: true };
         }
@@ -882,6 +991,50 @@ export class NodeConnector {
                 ...(typeof input.limit === 'number' ? { limit: input.limit } : {})
             });
         }
+        if (operation === 'workspace.watch') {
+            if (typeof input.workspaceId !== 'string' ||
+                typeof input.watchId !== 'string' ||
+                !/^[A-Za-z0-9_-]{8,128}$/.test(input.watchId) ||
+                (input.mode !== 'initial' && input.mode !== 'renew'))
+                throw new Error('WORKSPACE_WATCH_INVALID');
+            const workspace = this.requireWorkspace(input.workspaceId);
+            if (input.mode === 'renew') {
+                const watch = this.renewWorkspaceWatch(workspace.id, this.workspaceWatchKey(input));
+                if (watch === undefined)
+                    throw new Error('WORKSPACE_WATCH_NOT_FOUND');
+                return { renewed: true };
+            }
+            const topics = this.parseWorkspaceWatchTopics(input);
+            const snapshot = {};
+            if (topics.sessions)
+                snapshot.sessions = await this.executeNodeOperation('session.list', {
+                    workspaceId: workspace.id,
+                    limit: 20
+                });
+            if (topics.files !== undefined)
+                snapshot.files = {
+                    files: await this.listFilesForWorkspace(workspace, topics.files)
+                };
+            if (topics.changes)
+                snapshot.changes =
+                    workspace.kind === 'GIT_WORKSPACE'
+                        ? await this.currentChangesForWorkspace(workspace)
+                        : null;
+            // An initial snapshot is the observation baseline. Do not retain a
+            // background lease when producing that baseline has failed.
+            if (topics.files !== undefined || topics.changes)
+                await this.workspaceFileIndex(workspace).observe();
+            const watch = this.createWorkspaceWatch(workspace.id, input.watchId, this.workspaceWatchSessionHash(input), topics);
+            return { watch: { expiresAt: watch.expiresAt }, snapshot };
+        }
+        if (operation === 'workspace.unwatch') {
+            if (typeof input.workspaceId !== 'string' ||
+                typeof input.watchId !== 'string' ||
+                !/^[A-Za-z0-9_-]{8,128}$/.test(input.watchId))
+                throw new Error('WORKSPACE_WATCH_INVALID');
+            this.removeWorkspaceWatch(input.workspaceId, this.workspaceWatchKey(input));
+            return { stopped: true };
+        }
         if (operation === 'workspace.files.list') {
             const workspace = this.requireWorkspace(input.workspaceId);
             return { files: await this.listFilesForWorkspace(workspace, input) };
@@ -943,7 +1096,7 @@ export class NodeConnector {
                 throw new Error('WORKSPACE_BUSY');
             await restoreCurrentChange(workspace.path, input.path, input.state, this.fileAccessOptions());
             // A read started before the write must not satisfy the explicit post-write refresh.
-            this.workspaceChangesReads.delete(workspace.id);
+            this.invalidateWorkspaceWatchTopics(workspace.id);
             return { restored: true };
         }
         if (operation === 'workspace.diff') {
@@ -999,16 +1152,6 @@ export class NodeConnector {
             if (input.bootstrapOnly === true)
                 this.bootstrapSessionIds.add(session.id);
             database.saveRunnerDefaults(configuration);
-            if (session.externalSessionId !== null) {
-                database.saveNativeSessionMetadata({
-                    runner: session.runner,
-                    externalSessionId: session.externalSessionId,
-                    workspaceId: session.workspaceId,
-                    model: configuration.model,
-                    effort: configuration.effort,
-                    access: configuration.access
-                });
-            }
             if (input.bootstrapOnly !== true)
                 this.emitWorkbenchEvent('session', { session: this.presentSession(session) });
             return {
@@ -1144,11 +1287,14 @@ export class NodeConnector {
             };
         }
         if (operation === 'session.list') {
-            // Native discovery is deliberately deferred until a Workspace is
-            // selected.  A node selection must not block on every user's historical
-            // transcript directory; selected-workspace discovery populates this
-            // process-local cache before a direct session can be opened.
-            const native = [...this.directNativeSessions.values()].map((session) => this.presentSession(session));
+            const workspaceId = typeof input.workspaceId === 'string' ? input.workspaceId : undefined;
+            // Pagination is only correct after persisted records and the current
+            // Runner discovery have been merged. A selected Workspace therefore
+            // performs discovery inside this authoritative list operation.
+            const nativeSessions = workspaceId === undefined
+                ? [...this.directNativeSessions.values()]
+                : await this.cachedWorkspaceSessions(workspaceId);
+            const native = nativeSessions.map((session) => this.presentSession({ ...session, externalDiscovered: true }));
             const projected = this.runtime
                 .listAgentSessions()
                 .filter((session) => session.nativeControl === 'MAR_MANAGED' ||
@@ -1160,17 +1306,51 @@ export class NodeConnector {
                     : {
                         ...session,
                         runnerTitle: source.runnerTitle,
+                        pinnedAt: source.pinnedAt,
+                        pinOrder: source.pinOrder ?? null,
+                        externalDiscovered: true,
                         titleSource: session.customTitle === null ? source.titleSource : session.titleSource,
                         lastActivityAt: source.lastActivityAt
                     });
             });
-            const allSessions = [
+            const merged = new Map([
                 ...projected,
                 ...native.filter((native) => native.externalSessionId === null ||
                     this.sessionProjectionForNativeRecord(native) === undefined)
-            ];
-            return sessionPage(typeof input.workspaceId === 'string'
-                ? allSessions.filter((session) => session.workspaceId === input.workspaceId)
+            ].map((session) => [session.id, session]));
+            if (workspaceId !== undefined) {
+                const workspace = database.getWorkspace(workspaceId);
+                if (workspace === undefined)
+                    throw new Error('WORKSPACE_NOT_FOUND');
+                for (const record of database.listSessionRecords(workspaceId)) {
+                    if (merged.has(record.id))
+                        continue;
+                    merged.set(record.id, this.presentSession({
+                        id: record.id,
+                        nodeId: this.config?.nodeId ?? 'recorded-session',
+                        workspaceId,
+                        runner: record.runner,
+                        externalSessionId: record.id,
+                        nativeControl: 'EXTERNAL',
+                        channelToken: null,
+                        cwd: workspace.path,
+                        model: record.metadata.model,
+                        effort: record.metadata.effort,
+                        access: record.metadata.access,
+                        customTitle: record.metadata.customTitle,
+                        runnerTitle: record.metadata.runnerTitle,
+                        pinnedAt: record.pinOrder === null ? null : 1,
+                        pinOrder: record.pinOrder,
+                        externalDiscovered: false,
+                        titleSource: record.metadata.customTitle === null ? 'RUNNER' : 'CUSTOM',
+                        lastActivityAt: 0,
+                        createdAt: 0
+                    }));
+                }
+            }
+            const allSessions = [...merged.values()];
+            return sessionPage(workspaceId !== undefined
+                ? allSessions.filter((session) => session.workspaceId === workspaceId)
                 : allSessions, input);
         }
         if (operation === 'session.discover') {
@@ -1220,18 +1400,26 @@ export class NodeConnector {
                 (await this.resolveDirectNativeSession(input.sessionId));
             if (value === undefined)
                 throw new Error('SESSION_NOT_FOUND');
-            await this.refreshCodexExternalActivity(value);
             return { session: this.presentSession(value) };
         }
         if (operation === 'session.watch') {
-            if (typeof input.sessionId !== 'string')
+            if (typeof input.sessionId !== 'string' ||
+                (input.mode !== 'initial' && input.mode !== 'renew'))
                 throw new Error('SESSION_INVALID');
             const session = this.runtime.getAgentSession(input.sessionId) ??
                 (await this.resolveDirectNativeSession(input.sessionId));
             if (session === undefined || session.externalSessionId === null)
                 throw new Error('SESSION_NOT_FOUND');
+            if (input.mode === 'renew') {
+                const watch = this.renewNativeSessionWatch(session);
+                if (watch === undefined)
+                    throw new Error('SESSION_WATCH_NOT_FOUND');
+                return { renewed: true };
+            }
             const watch = this.watchNativeSession(session);
-            const snapshot = watch === undefined ? undefined : await this.refreshWatchedSession(session.id);
+            const snapshot = watch !== undefined
+                ? await this.refreshWatchedSession(session.id, SESSION_WATCH_INITIAL_TURN_LIMIT)
+                : undefined;
             if (watch !== undefined && snapshot === undefined)
                 throw new Error('NATIVE_TRANSCRIPT_UNAVAILABLE');
             return {
@@ -1650,6 +1838,174 @@ export class NodeConnector {
             throw new Error('WORKSPACE_NOT_FOUND');
         return workspace;
     }
+    parseWorkspaceWatchTopics(input) {
+        if (!isPlainRecord(input.topics))
+            throw new Error('WORKSPACE_WATCH_INVALID');
+        const sessions = input.topics.sessions === true;
+        const changes = input.topics.changes === true;
+        const rawFiles = input.topics.files;
+        let files;
+        if (rawFiles !== undefined) {
+            if (!isPlainRecord(rawFiles) || typeof rawFiles.path !== 'string')
+                throw new Error('WORKSPACE_WATCH_INVALID');
+            const limit = rawFiles.limit;
+            if ((rawFiles.cursor !== undefined && typeof rawFiles.cursor !== 'string') ||
+                (limit !== undefined &&
+                    (typeof limit !== 'number' || !Number.isInteger(limit) || limit < 1 || limit > 200)))
+                throw new Error('WORKSPACE_WATCH_INVALID');
+            files = {
+                path: rawFiles.path,
+                ...(typeof rawFiles.cursor === 'string' ? { cursor: rawFiles.cursor } : {}),
+                ...(typeof rawFiles.limit === 'number' ? { limit: rawFiles.limit } : {})
+            };
+        }
+        if (!sessions && !changes && files === undefined)
+            throw new Error('WORKSPACE_WATCH_INVALID');
+        return { sessions, changes, files };
+    }
+    workspaceWatchKey(input) {
+        return `${this.workspaceWatchSessionHash(input)}:${input.watchId}`;
+    }
+    workspaceWatchSessionHash(input) {
+        return typeof input.__workspaceWatchSessionHash === 'string'
+            ? input.__workspaceWatchSessionHash
+            : 'local-test';
+    }
+    createWorkspaceWatch(workspaceId, watchId, sessionHash, topics) {
+        const key = `${sessionHash}:${watchId}`;
+        this.removeWorkspaceWatch(workspaceId, key);
+        const watch = {
+            workspaceId,
+            watchId,
+            sessionHash,
+            expiresAt: Date.now() + WORKSPACE_WATCH_TTL_MS,
+            topics,
+            timer: undefined
+        };
+        watch.timer = setTimeout(() => this.removeWorkspaceWatch(workspaceId, key), WORKSPACE_WATCH_TTL_MS);
+        watch.timer.unref();
+        const watches = this.workspaceWatches.get(workspaceId) ?? new Map();
+        watches.set(key, watch);
+        this.workspaceWatches.set(workspaceId, watches);
+        if (topics.sessions)
+            this.ensureWorkspaceSessionWatch(workspaceId);
+        return watch;
+    }
+    renewWorkspaceWatch(workspaceId, watchId) {
+        const watch = this.workspaceWatches.get(workspaceId)?.get(watchId);
+        if (watch === undefined || watch.expiresAt <= Date.now()) {
+            this.removeWorkspaceWatch(workspaceId, watchId);
+            return undefined;
+        }
+        clearTimeout(watch.timer);
+        watch.expiresAt = Date.now() + WORKSPACE_WATCH_TTL_MS;
+        watch.timer = setTimeout(() => this.removeWorkspaceWatch(workspaceId, watchId), WORKSPACE_WATCH_TTL_MS);
+        watch.timer.unref();
+        return watch;
+    }
+    removeWorkspaceWatch(workspaceId, watchId) {
+        const watches = this.workspaceWatches.get(workspaceId);
+        const watch = watches?.get(watchId);
+        if (watch === undefined)
+            return;
+        clearTimeout(watch.timer);
+        watches?.delete(watchId);
+        if (watches?.size === 0)
+            this.workspaceWatches.delete(workspaceId);
+        if (!this.workspaceWatchTopicActive(workspaceId, 'sessions'))
+            this.stopWorkspaceSessionWatch(workspaceId);
+    }
+    clearWorkspaceWatches(workspaceId) {
+        const watches = this.workspaceWatches.get(workspaceId);
+        if (watches === undefined)
+            return;
+        for (const watch of watches.values())
+            clearTimeout(watch.timer);
+        this.workspaceWatches.delete(workspaceId);
+        this.workspaceWatchRevisions.delete(workspaceId);
+        this.stopWorkspaceSessionWatch(workspaceId);
+    }
+    ensureWorkspaceSessionWatch(workspaceId) {
+        if (this.workspaceSessionWatchTimers.has(workspaceId))
+            return;
+        const timer = setInterval(() => void this.refreshWorkspaceSessionWatch(workspaceId), WORKSPACE_SESSION_WATCH_INTERVAL_MS);
+        timer.unref();
+        this.workspaceSessionWatchTimers.set(workspaceId, timer);
+        void this.refreshWorkspaceSessionWatch(workspaceId);
+    }
+    stopWorkspaceSessionWatch(workspaceId) {
+        const timer = this.workspaceSessionWatchTimers.get(workspaceId);
+        if (timer !== undefined)
+            clearInterval(timer);
+        this.workspaceSessionWatchTimers.delete(workspaceId);
+        this.workspaceSessionWatchSignatures.delete(workspaceId);
+        this.workspaceSessionWatchReads.delete(workspaceId);
+    }
+    async cachedWorkspaceSessions(workspaceId) {
+        const cached = this.workspaceSessionCache.get(workspaceId);
+        if (cached !== undefined && cached.expiresAt > Date.now())
+            return cached.sessions;
+        const inFlight = this.workspaceSessionCacheReads.get(workspaceId);
+        if (inFlight !== undefined)
+            return inFlight;
+        const discovery = this.discoverWorkspaceSessions(workspaceId)
+            .then((sessions) => {
+            this.workspaceSessionCache.set(workspaceId, {
+                sessions,
+                expiresAt: Date.now() + WORKSPACE_SESSION_CACHE_TTL_MS
+            });
+            return sessions;
+        })
+            .finally(() => this.workspaceSessionCacheReads.delete(workspaceId));
+        this.workspaceSessionCacheReads.set(workspaceId, discovery);
+        return discovery;
+    }
+    async refreshWorkspaceSessionWatch(workspaceId) {
+        const current = this.workspaceSessionWatchReads.get(workspaceId);
+        if (current !== undefined)
+            return current;
+        const refresh = this.performWorkspaceSessionWatchRefresh(workspaceId).finally(() => {
+            this.workspaceSessionWatchReads.delete(workspaceId);
+        });
+        this.workspaceSessionWatchReads.set(workspaceId, refresh);
+        return refresh;
+    }
+    async performWorkspaceSessionWatchRefresh(workspaceId) {
+        if (!this.workspaceWatchTopicActive(workspaceId, 'sessions'))
+            return this.stopWorkspaceSessionWatch(workspaceId);
+        try {
+            const page = await this.executeNodeOperation('session.list', { workspaceId, limit: 20 });
+            const signature = JSON.stringify(page);
+            const previous = this.workspaceSessionWatchSignatures.get(workspaceId);
+            this.workspaceSessionWatchSignatures.set(workspaceId, signature);
+            if (previous === undefined || previous === signature)
+                return;
+            const revision = (this.workspaceWatchRevisions.get(workspaceId) ?? 0) + 1;
+            this.workspaceWatchRevisions.set(workspaceId, revision);
+            this.emitWorkbenchEvent('workspace', { workspaceId, topic: 'sessions', revision });
+        }
+        catch {
+            // A later bounded interval retries; no stale session state is fabricated.
+        }
+    }
+    workspaceWatchTopicActive(workspaceId, topic) {
+        return [...(this.workspaceWatches.get(workspaceId)?.values() ?? [])].some((watch) => topic === 'files' ? watch.topics.files !== undefined : watch.topics[topic]);
+    }
+    invalidateWorkspaceWatchTopics(workspaceId) {
+        this.invalidateWorkspaceChanges(workspaceId);
+        for (const topic of ['files', 'changes']) {
+            if (!this.workspaceWatchTopicActive(workspaceId, topic))
+                continue;
+            const revision = (this.workspaceWatchRevisions.get(workspaceId) ?? 0) + 1;
+            this.workspaceWatchRevisions.set(workspaceId, revision);
+            this.emitWorkbenchEvent('workspace', { workspaceId, topic, revision });
+        }
+    }
+    invalidateWorkspaceChanges(workspaceId) {
+        this.workspaceChangesReads.delete(workspaceId);
+        this.workspaceChangesCache.delete(workspaceId);
+        this.workspaceChangesVersions.set(workspaceId, (this.workspaceChangesVersions.get(workspaceId) ?? 0) + 1);
+    }
     fileAccessOptions() {
         if (this.config === undefined)
             return {};
@@ -1688,7 +2044,27 @@ export class NodeConnector {
                     input.limit < 1 ||
                     input.limit > 200)))
             throw new Error('FILE_SEARCH_LIMIT_EXCEEDED');
-        return searchWorkspaceFiles(workspace.path, input.query, typeof input.cursor === 'string' ? input.cursor : undefined, typeof input.limit === 'number' ? input.limit : undefined, this.fileAccessOptions());
+        const index = this.workspaceFileIndex(workspace);
+        return index.search(input.query, typeof input.cursor === 'string' ? input.cursor : undefined, typeof input.limit === 'number' ? input.limit : undefined);
+    }
+    workspaceFileIndex(workspace) {
+        let index = this.workspaceFileIndexes.get(workspace.id);
+        if (index === undefined) {
+            if (this.workspaceFileIndexes.size >= WORKSPACE_FILE_INDEX_CACHE_LIMIT) {
+                const oldest = this.workspaceFileIndexes.entries().next().value;
+                if (oldest !== undefined) {
+                    const [oldestWorkspaceId, oldestIndex] = oldest;
+                    oldestIndex.dispose();
+                    this.workspaceFileIndexes.delete(oldestWorkspaceId);
+                }
+            }
+            index = new WorkspaceFileIndex(workspace.path, this.fileAccessOptions(), {
+                onInvalidated: () => this.invalidateWorkspaceWatchTopics(workspace.id)
+            });
+        }
+        this.workspaceFileIndexes.delete(workspace.id);
+        this.workspaceFileIndexes.set(workspace.id, index);
+        return index;
     }
     async preflightWorkspaceUploads(workspace, input) {
         if ((input.directory !== undefined && typeof input.directory !== 'string') ||
@@ -1816,6 +2192,7 @@ export class NodeConnector {
         }
         clearTimeout(upload.timer);
         this.workspaceUploads.delete(upload.id);
+        this.invalidateWorkspaceWatchTopics(upload.workspaceId);
         if (upload.composerAttachment !== undefined) {
             this.composerAttachments.set(upload.composerAttachment.id, {
                 id: upload.composerAttachment.id,
@@ -1918,12 +2295,16 @@ export class NodeConnector {
     async currentChangesForWorkspace(workspace) {
         if (workspace.kind !== 'GIT_WORKSPACE')
             throw new Error('WORKSPACE_NOT_GIT');
+        const cached = this.workspaceChangesCache.get(workspace.id);
+        if (cached !== undefined && cached.expiresAt > Date.now())
+            return cached.value;
         const existing = this.workspaceChangesReads.get(workspace.id);
         if (existing !== undefined)
             return existing;
+        const version = this.workspaceChangesVersions.get(workspace.id) ?? 0;
         const request = this.workspaceChangesLimiter.run(async () => {
             const summary = await readCurrentChangesSummary(workspace.path);
-            return {
+            const value = {
                 branch: summary.branch,
                 changes: summary.changes.map((change) => ({
                     ...change,
@@ -1936,6 +2317,12 @@ export class NodeConnector {
                     diffAvailable: change.state !== 'UNTRACKED'
                 }))
             };
+            if ((this.workspaceChangesVersions.get(workspace.id) ?? 0) === version)
+                this.workspaceChangesCache.set(workspace.id, {
+                    value,
+                    expiresAt: Date.now() + WORKSPACE_CHANGES_CACHE_TTL_MS
+                });
+            return value;
         });
         this.workspaceChangesReads.set(workspace.id, request);
         try {
@@ -2005,34 +2392,19 @@ export class NodeConnector {
             officialCandidates.push({ thread, workspace: targetWorkspace, cwd });
         }
         // A selected Workspace still needs the complete native directory scan for
-        // source coverage, but it is independent of App Server status reads. Start
-        // both paths together and bound JSON-RPC reads so dozens of old threads do
-        // not serialize the visible Codex list or overload one App Server.
+        // source coverage, but it is independent of App Server discovery. Start
+        // both paths together. The list response is the discovery source; do not
+        // read every thread here because most external threads are not loaded by
+        // this App Server and would be reported as unavailable anyway.
         const nativePromise = discoverAllNativeSessions('codex');
-        const official = await mapWithConcurrency(officialCandidates, 8, async (candidate) => {
-            try {
-                // Discovery only verifies that the official thread remains readable
-                // and obtains its activity state.  Loading every historical turn here
-                // makes the list cost proportional to the full conversation corpus;
-                // the selected Chat fetches `includeTurns: true` separately.
-                const detail = await this.codexClient.readThread(candidate.thread.id, false);
-                this.codexExternalActivity.set(candidate.thread.id, codexThreadActivity(detail));
-            }
-            catch {
-                // A listing can race archival/deletion. It must not manufacture a
-                // session entry whose native history is no longer readable.
-                return undefined;
-            }
-            return this.directNativeSession({
-                workspace: candidate.workspace,
-                runner: 'codex',
-                externalSessionId: candidate.thread.id,
-                cwd: candidate.cwd,
-                ...(candidate.thread.title === undefined ? {} : { title: candidate.thread.title }),
-                titleOrigin: 'OFFICIAL'
-            });
-        });
-        const sessions = official.filter((session) => session !== undefined);
+        const sessions = officialCandidates.map((candidate) => this.directNativeSession({
+            workspace: candidate.workspace,
+            runner: 'codex',
+            externalSessionId: candidate.thread.id,
+            cwd: candidate.cwd,
+            ...(candidate.thread.title === undefined ? {} : { title: candidate.thread.title }),
+            titleOrigin: 'OFFICIAL'
+        }));
         const native = await nativePromise;
         for (const entry of native) {
             const targetWorkspace = workspace ??
@@ -2132,11 +2504,74 @@ export class NodeConnector {
         this.rememberDirectNativeSessions(sessions);
         return sessions;
     }
+    async discoverWorkspaceSessions(workspaceId) {
+        const database = this.database;
+        if (database === undefined)
+            throw new Error('NODE_DATABASE_UNAVAILABLE');
+        const workspace = database.getWorkspace(workspaceId);
+        if (workspace === undefined)
+            throw new Error('WORKSPACE_NOT_FOUND');
+        const [codex, claude] = await Promise.all([
+            this.discoverCodexSessions(workspaceId).then((result) => result.sessions),
+            (async () => {
+                let official = [];
+                try {
+                    official = await this.claudeClient.listSessions(workspace.path);
+                }
+                catch {
+                    // Local transcript discovery remains authoritative when the SDK list is unavailable.
+                }
+                const native = await discoverNativeSessions('claude-code', workspace.path);
+                return this.directClaudeSessions(workspace, 'claude-code', [
+                    ...official.flatMap((item) => {
+                        const parsed = claudeDiscoveredSession(item, workspace.path);
+                        return parsed === undefined ? [] : [parsed];
+                    }),
+                    ...native
+                ]);
+            })()
+        ]);
+        const sessions = deduplicateDirectSessions([...codex, ...claude]);
+        this.rememberDirectNativeSessions(sessions);
+        return sessions;
+    }
     async resolveDirectNativeSession(sessionId) {
         const cached = this.directNativeSessions.get(sessionId);
         if (cached !== undefined)
             return cached;
-        return (await this.listDirectNativeSessions()).find((session) => session.id === sessionId);
+        const discovered = (await this.listDirectNativeSessions()).find((session) => session.id === sessionId);
+        if (discovered !== undefined)
+            return discovered;
+        const record = this.database
+            ?.listWorkspaces()
+            .flatMap((workspace) => this.database?.listSessionRecords(workspace.id) ?? [])
+            .find((candidate) => candidate.id === sessionId);
+        if (record === undefined)
+            return undefined;
+        const workspace = this.database?.getWorkspace(record.workspaceId);
+        if (workspace === undefined)
+            return undefined;
+        return {
+            id: record.id,
+            nodeId: this.config?.nodeId ?? 'recorded-session',
+            workspaceId: record.workspaceId,
+            runner: record.runner,
+            externalSessionId: record.id,
+            nativeControl: 'EXTERNAL',
+            channelToken: null,
+            cwd: workspace.path,
+            model: record.metadata.model,
+            effort: record.metadata.effort,
+            access: record.metadata.access,
+            customTitle: record.metadata.customTitle,
+            runnerTitle: record.metadata.runnerTitle,
+            pinnedAt: record.pinOrder === null ? null : 1,
+            pinOrder: record.pinOrder,
+            externalDiscovered: false,
+            titleSource: record.metadata.customTitle === null ? 'RUNNER' : 'CUSTOM',
+            lastActivityAt: 0,
+            createdAt: 0
+        };
     }
     /**
      * A rename is Node-local metadata, so an external transcript receives a
@@ -2419,6 +2854,19 @@ export class NodeConnector {
         this.sessionWatches.set(session.id, watch);
         return { expiresAt: watch.expiresAt };
     }
+    renewNativeSessionWatch(session) {
+        if (this.hasManagedActiveRun(session)) {
+            this.stopNativeSessionWatch(session.id);
+            return undefined;
+        }
+        const watch = this.sessionWatches.get(session.id);
+        if (watch === undefined || watch.expiresAt <= Date.now()) {
+            this.stopNativeSessionWatch(session.id);
+            return undefined;
+        }
+        watch.expiresAt = Date.now() + SESSION_WATCH_TTL_MS;
+        return { expiresAt: watch.expiresAt };
+    }
     stopNativeSessionWatch(sessionId) {
         const watch = this.sessionWatches.get(sessionId);
         if (watch === undefined)
@@ -2426,7 +2874,7 @@ export class NodeConnector {
         clearInterval(watch.timer);
         this.sessionWatches.delete(sessionId);
     }
-    async refreshWatchedSession(sessionId) {
+    async refreshWatchedSession(sessionId, limit = 10) {
         const watch = this.sessionWatches.get(sessionId);
         if (watch === undefined)
             return undefined;
@@ -2436,7 +2884,7 @@ export class NodeConnector {
             this.stopNativeSessionWatch(sessionId);
             return undefined;
         }
-        const refresh = this.performWatchedSessionRefresh(sessionId, watch);
+        const refresh = this.performWatchedSessionRefresh(sessionId, watch, limit);
         watch.refresh = refresh;
         try {
             return await refresh;
@@ -2446,7 +2894,7 @@ export class NodeConnector {
                 watch.refresh = undefined;
         }
     }
-    async performWatchedSessionRefresh(sessionId, watch) {
+    async performWatchedSessionRefresh(sessionId, watch, limit = 10) {
         try {
             const session = this.runtime.getAgentSession(sessionId) ??
                 (await this.resolveDirectNativeSession(sessionId));
@@ -2463,18 +2911,22 @@ export class NodeConnector {
                 watch.sessionSignature = sessionSignature;
                 this.emitWorkbenchEvent('session', { session: presentedSession });
             }
-            const page = await this.readConversationHistoryPage(session, { limit: 10 });
+            const page = await this.readConversationHistoryPage(session, { limit });
             // A missing transcript is not a harmless empty update: continuing to
             // renew an observer that has lost both official and native history would
             // retain its timer forever. Treat it like every other read failure.
             watch.failures = 0;
-            const signature = JSON.stringify(page.turns);
+            // `initial` may return a larger page than the background observer. The
+            // observer's change signature remains fixed to the newest 10 Turns, so
+            // switching back to its normal page size cannot manufacture an update.
+            const observedPage = page.turns.length <= 10 ? page : { ...page, turns: page.turns.slice(0, 10) };
+            const signature = JSON.stringify(observedPage.turns);
             if (signature === watch.signature)
                 return page;
             watch.signature = signature;
             // 历史页按最新到最早排列，而 Web 会把单个实时 Turn 插到最新端。
             // 因此逐帧推送必须反向，最终投影仍保持最新到最早。
-            for (const turn of [...page.turns].reverse())
+            for (const turn of [...observedPage.turns].reverse())
                 this.emitWorkbenchEvent('conversation', { turn });
             return page;
         }
@@ -2679,6 +3131,8 @@ export class NodeConnector {
             customTitle: metadata?.customTitle ?? null,
             runnerTitle,
             pinnedAt: metadata?.pinnedAt ?? null,
+            pinOrder: metadata?.pinOrder ?? null,
+            externalDiscovered: true,
             titleSource: metadata?.customTitle === null || metadata?.customTitle === undefined
                 ? runnerTitle === null
                     ? 'AUTO'
@@ -2688,7 +3142,7 @@ export class NodeConnector {
             createdAt: timestamp
         };
     }
-    /** DB caches confirmed Codex names and shields a pending rename from stale discovery results. */
+    /** A pending Codex rename shields the UI from stale discovery until Runner confirms it. */
     nativeSessionRunnerTitle(metadata, input) {
         if (input.runner !== 'codex')
             return input.title ?? null;
@@ -2707,24 +3161,17 @@ export class NodeConnector {
             }
             return cached ?? input.title;
         }
-        if (input.title !== cached) {
-            this.database?.saveNativeSessionMetadata({
-                runner: 'codex',
-                externalSessionId: input.externalSessionId,
-                workspaceId: input.workspace.id,
-                runnerTitle: input.title,
-                runnerTitlePending: false
-            });
-        }
         return input.title;
     }
     /** Runner-specific title persistence: Codex owns its thread name; Claude metadata is Node-local. */
     async renameRunnerSession(session, input) {
         if (session.runner === 'codex') {
-            if (session.externalSessionId === null || input.title === undefined)
+            if (session.externalSessionId === null)
                 return;
-            await this.codexClient.start();
-            await this.codexClient.setThreadName(session.externalSessionId, input.title ?? '');
+            if (input.title !== undefined) {
+                await this.codexClient.start();
+                await this.codexClient.setThreadName(session.externalSessionId, input.title ?? '');
+            }
             const database = this.database;
             if (database === undefined)
                 throw new Error('NODE_DATABASE_UNAVAILABLE');
@@ -2732,8 +3179,10 @@ export class NodeConnector {
                 runner: 'codex',
                 externalSessionId: session.externalSessionId,
                 workspaceId: session.workspaceId,
-                runnerTitle: input.title,
-                runnerTitlePending: input.title !== null && input.title.trim().length > 0,
+                ...(input.title === undefined ? {} : { runnerTitle: input.title }),
+                ...(input.title === undefined
+                    ? {}
+                    : { runnerTitlePending: input.title !== null && input.title.trim().length > 0 }),
                 ...(input.pinned === undefined ? {} : { pinned: input.pinned })
             });
             return;
@@ -2912,6 +3361,8 @@ export class NodeConnector {
                 this.emitRunEvent(runId, 'run.running', { threadId, turnId }, 'RUNNING');
             }
             catch (error) {
+                if (this.completeCancelledRun(runId, cwd))
+                    return;
                 this.emitRunEvent(runId, 'run.failed', { code: error instanceof Error ? error.message : 'CODEX_RUN_FAILED' }, 'FAILED');
                 this.codexRuns.delete(runId);
                 this.activeRuns.delete(runId);
@@ -3236,7 +3687,8 @@ export class NodeConnector {
         if (run === undefined)
             return false;
         if (run.status === 'CANCELLING') {
-            this.emitRunEvent(runId, 'run.completed', { status: 'CANCELLED' }, 'CANCELLED');
+            const status = this.interruptRequestedRuns.has(runId) ? 'INTERRUPTED' : 'CANCELLED';
+            this.emitRunEvent(runId, 'run.completed', { status }, status);
         }
         else if (!isTerminalRunStatus(run.status)) {
             return false;
@@ -3248,6 +3700,15 @@ export class NodeConnector {
         return true;
     }
     presentSession(session) {
+        if (session.externalSessionId !== null && this.database !== undefined) {
+            const metadata = this.database.getNativeSessionMetadata(session.runner, session.externalSessionId, session.workspaceId);
+            if (metadata !== undefined)
+                session = {
+                    ...session,
+                    pinnedAt: metadata.pinnedAt,
+                    pinOrder: metadata.pinOrder
+                };
+        }
         if (session.runner !== 'codex') {
             const active = this.hasManagedActiveRun(session);
             if (this.capabilities.claudeCode.available && session.nativeControl === 'MAR_MANAGED') {
@@ -3326,7 +3787,11 @@ export class NodeConnector {
             : this.hasManagedActiveRun(session)
                 ? 'MANAGED_ACTIVE'
                 : session.nativeControl === 'EXTERNAL'
-                    ? (this.codexExternalActivity.get(session.id) ?? 'UNAVAILABLE')
+                    ? // Discovery deliberately uses thread/list only. Until a selected
+                        // session is read, treat activity as idle/unknown; takeover and
+                        // message handling still perform the authoritative read immediately
+                        // before resuming the external thread.
+                        (this.codexExternalActivity.get(session.id) ?? 'IDLE')
                     : 'IDLE';
         return {
             ...session,
@@ -3639,7 +4104,7 @@ export class NodeConnector {
             manifestVersion: 1,
             revision,
             observedAt: Date.now(),
-            platform: this.capabilities.platform === 'win32' ? 'windows' : 'linux',
+            platform: this.capabilities.platform,
             architecture: this.capabilities.architecture,
             conversation: {
                 available: true,
@@ -3673,7 +4138,7 @@ export class NodeConnector {
                 available: true,
                 reasonCode: null,
                 supportsPty: this.capabilities.platform === 'linux',
-                supportsConPty: this.capabilities.platform === 'win32',
+                supportsConPty: this.capabilities.platform === 'windows',
                 supportsReplay: true,
                 supportsReadonlyAttach: true,
                 supportsTakeover: true,
@@ -4551,21 +5016,6 @@ function presentClaudeContextUsage(usage) {
         percentage: usage.percentage
     };
 }
-async function mapWithConcurrency(values, concurrency, map) {
-    const result = new Array(values.length);
-    let next = 0;
-    const worker = async () => {
-        while (true) {
-            const index = next;
-            next += 1;
-            if (index >= values.length)
-                return;
-            result[index] = await map(values[index]);
-        }
-    };
-    await Promise.all(Array.from({ length: Math.min(concurrency, values.length) }, worker));
-    return result;
-}
 function isNativeHistory(value) {
     return (typeof value === 'object' &&
         value !== null &&
@@ -4674,7 +5124,9 @@ function nativeUserClientMessageId(entry, createdAt, runtimeTurns) {
         if (clientMessageId === null || payload.text !== entry.text)
             continue;
         const runtimeCreatedAt = user.startedAt ?? turn.startedAt;
-        if (runtimeCreatedAt !== null && runtimeCreatedAt !== undefined && Math.abs(createdAt - runtimeCreatedAt) > 60_000)
+        if (runtimeCreatedAt !== null &&
+            runtimeCreatedAt !== undefined &&
+            Math.abs(createdAt - runtimeCreatedAt) > 60_000)
             continue;
         return clientMessageId;
     }
@@ -5199,38 +5651,74 @@ function sessionPage(sessions, input) {
         input.limit <= MAX_SESSION_PAGE_SIZE
         ? input.limit
         : DEFAULT_SESSION_PAGE_SIZE;
-    const cursor = typeof input.cursor === 'string' ? parseSessionPageCursor(input.cursor) : undefined;
-    const ordered = [...sessions].sort((left, right) => right.lastActivityAt - left.lastActivityAt || left.id.localeCompare(right.id, 'en'));
+    const cursor = typeof input.cursor === 'string' ? input.cursor : undefined;
+    const ordered = [...sessions].sort(compareSessionPageEntries);
+    const cursorEntry = cursor === undefined ? undefined : parseSessionPageCursor(cursor);
     const afterCursor = cursor === undefined
         ? ordered
-        : ordered.filter((session) => session.lastActivityAt < cursor.lastActivityAt ||
-            (session.lastActivityAt === cursor.lastActivityAt &&
-                session.id.localeCompare(cursor.id, 'en') > 0));
-    const page = afterCursor.slice(0, limit);
+        : cursorEntry === undefined
+            ? []
+            : ordered.filter((session) => compareSessionPageEntries(session, cursorEntry) > 0);
+    const pinned = ordered.filter((session) => session.pinOrder !== null && session.pinOrder !== undefined);
+    const pinnedIndexes = new Map(pinned.map((session, index) => [session.id, index]));
+    const page = afterCursor.slice(0, limit).map((session) => {
+        const pinIndex = pinnedIndexes.get(session.id);
+        if (pinIndex === undefined)
+            return session;
+        return {
+            ...session,
+            canMovePinUp: pinIndex > 0,
+            canMovePinDown: pinIndex < pinned.length - 1
+        };
+    });
     const last = page.at(-1);
     return {
         sessions: page,
         nextCursor: last !== undefined && afterCursor.length > page.length ? createSessionPageCursor(last) : null
     };
 }
-function createSessionPageCursor(session) {
-    return `${session.lastActivityAt}:${encodeURIComponent(session.id)}`;
-}
-function parseSessionPageCursor(value) {
-    const separator = value.indexOf(':');
-    if (separator <= 0 || separator === value.length - 1)
-        return undefined;
-    const lastActivityAt = Number(value.slice(0, separator));
-    if (!Number.isFinite(lastActivityAt))
-        return undefined;
+function parseSessionPageCursor(cursor) {
     try {
-        const id = decodeURIComponent(value.slice(separator + 1));
-        return id.length === 0 ? undefined : { lastActivityAt, id };
+        const value = JSON.parse(decodeURIComponent(cursor));
+        if (!Array.isArray(value) || value.length !== 3)
+            return undefined;
+        const [pinOrder, lastActivityAt, id] = value;
+        if ((pinOrder !== null && (typeof pinOrder !== 'number' || !Number.isFinite(pinOrder))) ||
+            (lastActivityAt !== null &&
+                (typeof lastActivityAt !== 'number' || !Number.isFinite(lastActivityAt))) ||
+            typeof id !== 'string')
+            return undefined;
+        return {
+            id,
+            lastActivityAt: lastActivityAt ?? 0,
+            pinOrder,
+            externalDiscovered: lastActivityAt !== null
+        };
     }
     catch {
         return undefined;
     }
 }
+function createSessionPageCursor(session) {
+    return encodeURIComponent(JSON.stringify([
+        session.pinOrder ?? null,
+        session.externalDiscovered === false ? null : session.lastActivityAt,
+        session.id
+    ]));
+}
+function compareSessionPageEntries(left, right) {
+    const leftPinned = left.pinOrder !== null && left.pinOrder !== undefined;
+    const rightPinned = right.pinOrder !== null && right.pinOrder !== undefined;
+    if (leftPinned !== rightPinned)
+        return leftPinned ? -1 : 1;
+    if (leftPinned && rightPinned)
+        return (left.pinOrder - right.pinOrder || left.id.localeCompare(right.id));
+    const leftFound = left.externalDiscovered !== false;
+    const rightFound = right.externalDiscovered !== false;
+    if (leftFound !== rightFound)
+        return leftFound ? -1 : 1;
+    return right.lastActivityAt - left.lastActivityAt || left.id.localeCompare(right.id, 'en');
+}
 function compactRunnerText(value, limit) {
     return value.length <= limit ? value : `${value.slice(0, Math.max(0, limit - 1))}…`;
 }