texlite 0.6.0 → 0.6.6

package/dist/server/app.js

@@ -1,45 +1,55 @@
 import fs from "node:fs";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
 import { monitorEventLoopDelay, performance } from "node:perf_hooks";
 import Fastify from "fastify";
 import cookie from "@fastify/cookie";
 import multipart from "@fastify/multipart";
 import staticPlugin from "@fastify/static";
 import websocket from "@fastify/websocket";
-import { activeAdminCount } from "./db.js";
-import { createSessionToken, hashPassword, verifyPassword, digestToken } from "./security.js";
+import { activeAdminCount, pruneExpiredSessions } from "./db.js";
+import { createSessionToken, hashPassword, verifyPassword, digestToken, LoginRateLimiter } from "./security.js";
 import { currentUser, publicUser, requireAdmin, requireUser } from "./auth.js";
 import { accessibleProject, canEdit } from "./projects.js";
-import { createProjectFiles, duplicateProjectFiles, listProjectFiles, listProjectFilesAsync, outputRoot, removeProjectDirectory, resolveSourcePath, safeRelativePath, sourceRoot } from "./files.js";
-import { CompileQueue, ProjectCompileCoordinator, listPublishedCompileArtifacts, pruneOrphanedCompileRuns } from "./compiler.js";
+import { createProjectFiles, duplicateProjectFiles, assertNoSourceSymlinks, listProjectFiles, listProjectFilesAsync, outputRoot, pruneTrashDirectory, removeProjectDirectory, resolveSourcePath, safeRelativePath, sourceRoot } from "./files.js";
+import { CompileQueue, ProjectCompileCoordinator, listPublishedCompileArtifacts, pruneOrphanedCompileRuns, reconcilePublishedCompileRuns } from "./compiler.js";
 import { createSourceAnchor, offsetToLine, reanchorFileComments } from "./anchors.js";
 import { extractProjectZip } from "./zip.js";
-import { createProjectArchive } from "./archive.js";
-import { CollaborationService } from "./collaboration.js";
+import { writeProjectArchive } from "./archive.js";
+import { CollaborationService, isCollaborativeTextFile, maxCollaborativeFileBytes } from "./collaboration.js";
+import { ProjectMutationCoordinator } from "./projectMutations.js";
 import { ProjectGitService } from "./git.js";
 import { LatexCompletionService } from "./latexCompletion.js";
 import { ProjectHistoryService } from "./history.js";
 import { LatexFormatterService } from "./latexFormatter.js";
-import { buildProjectOutline } from "./projectOutline.js";
+import { ProjectOutlineService } from "./projectOutline.js";
 import { replaceProject, searchProject } from "./projectSearch.js";
 import { MetricRegistry } from "./metrics.js";
 import { compileMainFile } from "./compileArtifacts.js";
-import { apiError, contentDisposition } from "./http.js";
+import { apiError, contentDisposition, ValidationError } from "./http.js";
 import { registerCompileRoutes } from "./routes/compile.js";
 const now = () => new Date().toISOString();
+const SESSION_CLEANUP_INTERVAL_MS = 15 * 60_000;
+function escapeLikePattern(value) {
+    return value.replace(/[\\%_]/g, "\\$&");
+}
+export function escapeGlobPattern(value) {
+    return value.replace(/[*?[]/g, "[$&]");
+}
 function text(value, name, max = 200) {
     if (typeof value !== "string" || !value.trim() || value.length > max) {
-        throw new Error(`${name}格式不正确`);
+        throw new ValidationError(`${name}格式不正确`);
     }
     return value.trim();
 }
 function dictionaryWord(value) {
     if (typeof value !== "string")
-        throw new Error("自定义词格式不正确");
+        throw new ValidationError("自定义词格式不正确");
     const word = value.trim();
     if (!word || word.length > 64 || /[\s\\{}$%]/u.test(word))
-        throw new Error("自定义词格式不正确");
+        throw new ValidationError("自定义词格式不正确");
     return word;
 }
 const tagColors = ["red", "orange", "yellow", "green", "blue", "purple", "gray"];
@@ -63,7 +73,44 @@ function tagsForProjects(db, projectIds, userId) {
     }
     return result;
 }
-function projectJson(project, tags = []) {
+function commentsSummaryForProjects(db, projectIds) {
+    const result = new Map();
+    if (!projectIds.length)
+        return result;
+    for (let index = 0; index < projectIds.length; index += 100) {
+        const chunk = projectIds.slice(index, index + 100);
+        const placeholders = chunk.map(() => "?").join(", ");
+        const rows = db.prepare(`
+      SELECT project_id,
+        COUNT(*) AS total_count,
+        SUM(CASE WHEN resolved = 0 THEN 1 ELSE 0 END) AS unresolved_count
+      FROM comments
+      WHERE project_id IN (${placeholders})
+      GROUP BY project_id
+    `).all(...chunk);
+        for (const row of rows) {
+            result.set(row.project_id, {
+                totalCount: Number(row.total_count) || 0,
+                unresolvedCount: Number(row.unresolved_count) || 0
+            });
+        }
+    }
+    return result;
+}
+function commentsSummaryForProject(db, projectId) {
+    const row = db.prepare(`
+    SELECT
+      COUNT(*) AS total_count,
+      SUM(CASE WHEN resolved = 0 THEN 1 ELSE 0 END) AS unresolved_count
+    FROM comments
+    WHERE project_id = ?
+  `).get(projectId);
+    return {
+        totalCount: Number(row?.total_count) || 0,
+        unresolvedCount: Number(row?.unresolved_count) || 0
+    };
+}
+function projectJson(project, tags = [], commentsSummary) {
     return {
         id: project.id,
         ownerId: project.owner_id,
@@ -78,6 +125,8 @@ function projectJson(project, tags = []) {
         engine: project.engine,
         permission: project.permission,
         tags,
+        unresolvedCommentCount: commentsSummary?.unresolvedCount ?? 0,
+        commentCount: commentsSummary?.totalCount ?? 0,
         archived: Boolean(project.archived),
         createdAt: project.created_at,
         updatedAt: project.updated_at
@@ -87,11 +136,53 @@ function touchProject(db, projectId, userId) {
     db.prepare("UPDATE projects SET updated_at = ?, last_modified_by = ? WHERE id = ?")
         .run(now(), userId, projectId);
 }
+function requireActiveUser(db, user) {
+    const current = db.prepare("SELECT disabled FROM users WHERE id = ?").get(user.id);
+    if (!current || current.disabled) {
+        throw Object.assign(new Error("用户已被禁用或删除"), { statusCode: 401, code: "AUTH_REQUIRED" });
+    }
+}
+/**
+ * Authorization must be checked again after a queued mutation acquires its
+ * project lock.  A member can be revoked, or ownership can be transferred,
+ * while the request is waiting behind another filesystem operation.
+ */
+function requireEditableProject(db, projectId, user) {
+    requireActiveUser(db, user);
+    const project = accessibleProject(db, projectId, user);
+    if (!project)
+        throw Object.assign(new Error("项目不存在"), { statusCode: 404, code: "PROJECT_NOT_FOUND" });
+    if (!canEdit(project))
+        throw Object.assign(new Error("没有编辑权限"), { statusCode: 403, code: "PROJECT_EDIT_FORBIDDEN" });
+    return project;
+}
+/** Owner permission includes an administrator's effective owner access. */
+function requireProjectOwnerPermission(db, projectId, user) {
+    requireActiveUser(db, user);
+    const project = accessibleProject(db, projectId, user);
+    if (!project)
+        throw Object.assign(new Error("项目不存在"), { statusCode: 404, code: "PROJECT_NOT_FOUND" });
+    if (project.permission !== "owner") {
+        throw Object.assign(new Error("只有项目所有者可以执行此操作"), { statusCode: 403, code: "PROJECT_OWNER_ONLY" });
+    }
+    return project;
+}
+/** Operations such as ownership transfer require the actual stored owner. */
+function requireActualProjectOwner(db, projectId, user) {
+    requireActiveUser(db, user);
+    const project = accessibleProject(db, projectId, user);
+    if (!project)
+        throw Object.assign(new Error("项目不存在"), { statusCode: 404, code: "PROJECT_NOT_FOUND" });
+    if (project.owner_id !== user.id) {
+        throw Object.assign(new Error("只有当前项目所有者可以执行此操作"), { statusCode: 403, code: "PROJECT_OWNER_ONLY" });
+    }
+    return project;
+}
 function projectTextSnapshot(config, projectId) {
     const versionedText = (filePath) => /(?:\.tex|\.bib|\.sty|\.cls|\.txt|\.md|latexmkrc)$/i.test(filePath);
     return new Map(listProjectFiles(config, projectId).filter((entry) => entry.type === "file" && versionedText(entry.path)).map((entry) => {
         const absolute = resolveSourcePath(config, projectId, entry.path);
-        return [entry.path, fs.statSync(absolute).size <= 5 * 1024 * 1024 ? fs.readFileSync(absolute, "utf8") : ""];
+        return [entry.path, fs.statSync(absolute).size <= maxCollaborativeFileBytes(config) ? fs.readFileSync(absolute, "utf8") : ""];
     }));
 }
 function reanchorProjectSnapshot(db, projectId, before, after) {
@@ -129,6 +220,30 @@ function commentsForFile(db, config, projectId, filePath) {
     const rows = db.prepare(`SELECT c.*, u.username AS author_username, u.display_name AS author_display_name FROM comments c
     LEFT JOIN users u ON u.id = c.author_id WHERE c.project_id = ? AND c.file_path = ? ORDER BY c.created_at`)
         .all(projectId, filePath);
+    if (!rows.length)
+        return [];
+    const replies = db.prepare(`SELECT reply.*, user.username AS author_username, user.display_name AS author_display_name
+    FROM comment_replies reply
+    JOIN comments c ON c.id = reply.comment_id
+    LEFT JOIN users user ON user.id = reply.author_id
+    WHERE c.project_id = ? AND c.file_path = ?
+    ORDER BY reply.created_at`)
+        .all(projectId, filePath);
+    const replyMap = new Map();
+    for (const reply of replies) {
+        const list = replyMap.get(reply.comment_id) ?? [];
+        list.push({
+            id: reply.id,
+            authorId: reply.author_id,
+            authorUsername: reply.author_username,
+            authorDisplayName: reply.author_display_name,
+            content: reply.content,
+            createdAt: reply.created_at,
+            updatedAt: reply.updated_at,
+            editedAt: reply.edited_at
+        });
+        replyMap.set(reply.comment_id, list);
+    }
     return rows.map((comment) => ({
         id: comment.id,
         authorId: comment.author_id,
@@ -145,7 +260,7 @@ function commentsForFile(db, config, projectId, filePath) {
         createdAt: comment.created_at,
         updatedAt: comment.updated_at,
         editedAt: comment.edited_at,
-        replies: repliesForComment(db, comment.id)
+        replies: replyMap.get(comment.id) ?? []
     }));
 }
 export async function buildApp(config, db, options = {}) {
@@ -160,6 +275,7 @@ export async function buildApp(config, db, options = {}) {
     eventLoopDelay.enable();
     const history = new ProjectHistoryService(config, db);
     const latexCompletions = new LatexCompletionService(config);
+    const projectOutlines = new ProjectOutlineService(config);
     const latexFormatter = new LatexFormatterService();
     const recordHistory = (projectId, userId, reason, paths) => {
         try {
@@ -174,7 +290,12 @@ export async function buildApp(config, db, options = {}) {
         metrics.record("collaboration.persist", durationMs);
         recordHistory(projectId, userId, "autosave", paths);
     });
+    const projectMutations = new ProjectMutationCoordinator(collaboration);
     const projectGit = new ProjectGitService(config, db, options.githubFetch);
+    const loginLimiter = new LoginRateLimiter();
+    for (const row of db.prepare("SELECT id FROM projects").all()) {
+        reconcilePublishedCompileRuns(config, db, row.id);
+    }
     db.prepare(`UPDATE compile_runs SET status = 'failed',
     log = CASE WHEN log = '' THEN 'Server restarted before compilation finished.' ELSE log END,
     finished_at = ? WHERE status IN ('queued', 'running')`).run(now());
@@ -191,10 +312,16 @@ export async function buildApp(config, db, options = {}) {
             }
         }
         const remove = db.prepare("DELETE FROM compile_runs WHERE id = ?");
-        for (const run of completed)
-            if (!keep.has(run.id))
-                remove.run(run.id);
+        db.transaction(() => {
+            for (const run of completed)
+                if (!keep.has(run.id))
+                    remove.run(run.id);
+        })();
     };
+    // No second TexLite instance can mutate the data directory while the
+    // instance lock is held. Finish cleanup before accepting requests so a
+    // freshly started server never races a stale trash/tmp removal.
+    await pruneTrashDirectory(config);
     for (const row of db.prepare("SELECT id FROM projects").all()) {
         history.enforceRetention(row.id);
         pruneCompileRuns(row.id);
@@ -225,18 +352,39 @@ export async function buildApp(config, db, options = {}) {
     });
     app.setErrorHandler((error, _request, reply) => {
         app.log.error(error);
-        const status = typeof error === "object" && error !== null && "statusCode" in error && typeof error.statusCode === "number" ? error.statusCode : 400;
-        const message = error instanceof Error ? error.message : "请求格式不正确";
-        const code = typeof error === "object" && error !== null && "code" in error && typeof error.code === "string"
-            ? error.code : status >= 500 ? "SERVER_ERROR" : "REQUEST_INVALID";
-        void reply.code(status >= 500 ? 500 : status).send({
-            code, error: status >= 500 ? "服务器内部错误" : message
-        });
+        const rawStatus = typeof error === "object" && error !== null && "statusCode" in error && typeof error.statusCode === "number"
+            ? error.statusCode
+            : undefined;
+        const isClientError = rawStatus !== undefined && rawStatus >= 400 && rawStatus < 500;
+        const status = isClientError ? rawStatus : 500;
+        if (isClientError) {
+            const code = typeof error === "object" && error !== null && "code" in error && typeof error.code === "string"
+                ? error.code
+                : "REQUEST_INVALID";
+            const message = error instanceof Error ? error.message : "请求格式不正确";
+            const failedPaths = typeof error === "object" && error !== null && "failedPaths" in error
+                && Array.isArray(error.failedPaths)
+                && error.failedPaths.every((path) => typeof path === "string")
+                ? error.failedPaths.slice(0, 100)
+                : undefined;
+            void reply.code(status).send({
+                code,
+                error: message,
+                ...(failedPaths ? { failedPaths } : {})
+            });
+        }
+        else {
+            void reply.code(500).send({
+                code: "SERVER_ERROR",
+                error: "服务器内部错误"
+            });
+        }
     });
     app.get("/api/config", async () => ({
         siteName: config.siteName,
         adminEmail: config.adminEmail,
         maxUploadSizeMB: Math.floor(config.maxUploadBytes / 1024 / 1024),
+        maxCollaborativeFileSizeMB: Math.floor(maxCollaborativeFileBytes(config) / 1024 / 1024),
         allowedEngines: config.allowedEngines,
         allowProjectLatexmkrc: config.allowProjectLatexmkrc
     }));
@@ -255,6 +403,7 @@ export async function buildApp(config, db, options = {}) {
             },
             compileQueue: queue.stats(),
             collaboration: collaboration.stats(),
+            caches: { completions: latexCompletions.stats(), outlines: projectOutlines.stats() },
             durationsMs: metrics.summaries()
         };
     });
@@ -266,31 +415,38 @@ export async function buildApp(config, db, options = {}) {
         }
         const { id } = request.params;
         const startedAt = performance.now();
-        try {
-            collaboration.connect(socket, id, user);
-        }
-        finally {
-            metrics.record("collaboration.connect", performance.now() - startedAt);
-        }
+        void collaboration.connect(socket, id, user)
+            .finally(() => metrics.record("collaboration.connect", performance.now() - startedAt));
     });
     app.post("/api/auth/login", async (request, reply) => {
         const body = request.body;
         const username = text(body?.username, "用户名", 64);
+        const ip = request.ip || "127.0.0.1";
+        const rateLimitKey = `${ip}:${username.toLowerCase()}`;
+        if (loginLimiter.isLocked(rateLimitKey)) {
+            return apiError(reply, 429, "AUTH_RATE_LIMITED", "登录尝试过于频繁，账号已临时锁定，请在 15 分钟后再试");
+        }
         const password = typeof body?.password === "string" ? body.password : "";
         const user = db.prepare("SELECT * FROM users WHERE username = ? COLLATE NOCASE").get(username);
         if (!user || user.disabled || !(await verifyPassword(password, user.password_hash))) {
+            const result = loginLimiter.recordFailure(rateLimitKey);
+            if (result.locked) {
+                return apiError(reply, 429, "AUTH_RATE_LIMITED", "密码错误次数过多，账号已临时锁定，请在 15 分钟后再试");
+            }
             return apiError(reply, 401, "AUTH_INVALID", "用户名或密码错误");
         }
+        loginLimiter.reset(rateLimitKey);
         const session = createSessionToken();
         const createdAt = now();
         const expires = new Date(Date.now() + config.sessionDays * 86_400_000);
         db.prepare("INSERT INTO sessions (id, user_id, expires_at, created_at) VALUES (?, ?, ?, ?)")
             .run(session.digest, user.id, expires.toISOString(), createdAt);
+        const isSecure = request.protocol === "https" || request.headers["x-forwarded-proto"] === "https";
         reply.setCookie("texlite_session", session.token, {
             path: "/",
             httpOnly: true,
             sameSite: "strict",
-            secure: false,
+            secure: isSecure,
             expires
         });
         return { user: publicUser(user) };
@@ -341,7 +497,7 @@ export async function buildApp(config, db, options = {}) {
         const body = request.body;
         const username = text(body?.username, "用户名", 64);
         if (!/^[\p{L}\p{N}_.-]+$/u.test(username))
-            throw new Error("用户名只能包含字母、数字、点、横线或下划线");
+            return apiError(reply, 400, "USERNAME_INVALID", "用户名只能包含字母、数字、点、横线或下划线");
         const displayName = text(body?.displayName ?? username, "显示名称", 100);
         const password = typeof body?.password === "string" ? body.password : "";
         const role = body?.role === "admin" ? "admin" : "user";
@@ -382,6 +538,14 @@ export async function buildApp(config, db, options = {}) {
         }
         db.prepare(`UPDATE users SET display_name = ?, role = ?, disabled = ?, password_hash = ?, must_change_password = ?, can_create_projects = ? WHERE id = ?`)
             .run(displayName, role, disabled, passwordHash, mustChange, canCreateProjects, id);
+        // A disabled account must not regain access by being re-enabled while an
+        // old cookie is still within its normal lifetime. Password resets already
+        // revoke sessions above; disabling does the same for every active token.
+        if (disabled === 1)
+            db.prepare("DELETE FROM sessions WHERE user_id = ?").run(id);
+        if (disabled === 1 || (typeof body.password === "string" && body.password)) {
+            collaboration.disconnectUser(id, "用户已被禁用或密码已重置");
+        }
         const updated = db.prepare("SELECT * FROM users WHERE id = ?").get(id);
         return { user: publicUser(updated) };
     });
@@ -399,15 +563,27 @@ export async function buildApp(config, db, options = {}) {
         if (target.role === "admin" && activeAdminCount(db) <= 1) {
             return apiError(reply, 400, "LAST_ADMIN", "不能删除最后一个管理员");
         }
-        const owned = db.prepare("SELECT id FROM projects WHERE owner_id = ?").all(id);
-        for (const project of owned) {
-            if (body.deleteProjects)
-                collaboration.closeProject(project.id);
-            else
-                collaboration.flushProject(project.id);
-        }
+        let owned = [];
+        // Capture and mutate the complete owned-project set in the same synchronous
+        // transaction. There is deliberately no await before COMMIT: another
+        // request cannot transfer or create a project for this user between the
+        // snapshot and the owner/delete statements.
         db.exec("BEGIN IMMEDIATE");
         try {
+            const currentTarget = db.prepare("SELECT * FROM users WHERE id = ?").get(id);
+            if (!currentTarget)
+                throw Object.assign(new Error("用户不存在"), { statusCode: 404, code: "USER_NOT_FOUND" });
+            if (currentTarget.role === "admin" && activeAdminCount(db) <= 1) {
+                throw Object.assign(new Error("不能删除最后一个管理员"), { statusCode: 400, code: "LAST_ADMIN" });
+            }
+            owned = db.prepare("SELECT id FROM projects WHERE owner_id = ?").all(id);
+            if (!body.deleteProjects) {
+                // Persist any active drafts while the old owner row still exists. This
+                // is synchronous, so no edit can arrive between this flush and the
+                // ownership update below, and last_modified_by remains FK-safe.
+                for (const project of owned)
+                    projectMutations.flushProject(project.id);
+            }
             if (body.deleteProjects) {
                 db.prepare("DELETE FROM projects WHERE owner_id = ?").run(id);
             }
@@ -426,14 +602,23 @@ export async function buildApp(config, db, options = {}) {
             db.exec("ROLLBACK");
             throw error;
         }
-        if (body.deleteProjects) {
-            for (const project of owned)
-                removeProjectDirectory(config, project.id);
-        }
-        else {
-            for (const project of owned)
-                collaboration.resetProject(project.id);
-        }
+        // Requests already queued for the removed user fail their lock-time
+        // preflight. Cleanup is then serialized after them and invalidates any
+        // room initialization that started before the transaction committed.
+        for (const project of owned) {
+            await projectMutations.runExclusive(project.id, "admin user deletion cleanup", () => {
+                if (body.deleteProjects) {
+                    collaboration.resetProject(project.id);
+                    removeProjectDirectory(config, project.id);
+                    latexCompletions.invalidate(project.id);
+                    projectOutlines.invalidate(project.id);
+                }
+                else {
+                    collaboration.resetProject(project.id);
+                }
+            }, { flush: false });
+        }
+        collaboration.disconnectUser(id, "用户已被删除");
         return { ok: true, deletedProjects: body.deleteProjects ? owned.length : 0 };
     });
     app.get("/api/users", async (request, reply) => {
@@ -491,8 +676,8 @@ export async function buildApp(config, db, options = {}) {
         ];
         const params = { userId: user.id };
         if (search) {
-            conditions.push("(p.name LIKE :search OR owner.username LIKE :search OR owner.display_name LIKE :search)");
-            params.search = `%${search}%`;
+            conditions.push("(p.name LIKE :search ESCAPE '\\' OR owner.username LIKE :search ESCAPE '\\' OR owner.display_name LIKE :search ESCAPE '\\')");
+            params.search = `%${escapeLikePattern(search)}%`;
         }
         if (tagId) {
             conditions.push(`EXISTS (
@@ -520,9 +705,11 @@ export async function buildApp(config, db, options = {}) {
       ORDER BY ${sortColumn} DESC, p.name COLLATE NOCASE ASC
       LIMIT :limit OFFSET :offset`).all(rowsParams);
         const projects = rows;
-        const projectTags = tagsForProjects(db, projects.map((project) => project.id), user.id);
+        const projectIds = projects.map((project) => project.id);
+        const projectTags = tagsForProjects(db, projectIds, user.id);
+        const commentsSummaries = commentsSummaryForProjects(db, projectIds);
         return {
-            projects: projects.map((project) => projectJson({ ...project, archived: archivedOnly }, projectTags.get(project.id) ?? [])),
+            projects: projects.map((project) => projectJson({ ...project, archived: archivedOnly }, projectTags.get(project.id) ?? [], commentsSummaries.get(project.id))),
             pagination: { page: currentPage, pageSize, total, totalPages }
         };
     });
@@ -581,7 +768,7 @@ export async function buildApp(config, db, options = {}) {
         }
         catch (error) {
             removeProjectDirectory(config, project.id);
-            throw error;
+            return apiError(reply, 400, "ZIP_INVALID", error instanceof Error ? error.message : "无法解压 ZIP 文件");
         }
         recordHistory(project.id, user.id, "initial");
         return reply.code(201).send({ project: projectJson({
@@ -607,7 +794,17 @@ export async function buildApp(config, db, options = {}) {
             main_file: source.main_file, latexmkrc: source.latexmkrc, engine: source.engine, created_at: now(), updated_at: now()
         };
         try {
-            duplicateProjectFiles(config, source.id, project.id);
+            // Duplicate the source tree only after flushing the live Yjs room and
+            // while a short source barrier prevents autosave from changing files
+            // between directory entries. The copy is asynchronous, so a large
+            // project does not block the Node.js event loop for its entire duration.
+            await projectMutations.runConsistentRead(source.id, () => duplicateProjectFiles(config, source.id, project.id), {
+                preflight: () => {
+                    if (!accessibleProject(db, source.id, user)) {
+                        throw Object.assign(new Error("项目不存在"), { statusCode: 404, code: "PROJECT_NOT_FOUND" });
+                    }
+                }
+            });
             db.prepare(`INSERT INTO projects (id, owner_id, last_modified_by, name, main_file, latexmkrc, engine, created_at, updated_at)
         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
                 .run(project.id, project.owner_id, project.last_modified_by, project.name, project.main_file, project.latexmkrc, project.engine, project.created_at, project.updated_at);
@@ -630,7 +827,9 @@ export async function buildApp(config, db, options = {}) {
         const project = accessibleProject(db, id, user);
         if (!project)
             return apiError(reply, 404, "PROJECT_NOT_FOUND", "项目不存在");
-        return { project: projectJson(project, tagsForProject(db, id, user.id)) };
+        return {
+            project: projectJson(project, tagsForProject(db, id, user.id), commentsSummaryForProject(db, id))
+        };
     });
     app.get("/api/projects/:id/history", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -673,20 +872,25 @@ export async function buildApp(config, db, options = {}) {
             return apiError(reply, 404, "PROJECT_NOT_FOUND", "项目不存在");
         const query = request.query;
         const filePath = safeRelativePath(query.path ?? "");
-        const historical = history.readTextFile(id, versionId, filePath);
-        if (historical === null)
-            return apiError(reply, 415, "HISTORY_FILE_PREVIEW_UNSUPPORTED", "该历史文件不存在或不能作为文本比较", { path: filePath });
-        let comparison = "";
-        if (query.against) {
-            comparison = history.readTextFile(id, query.against, filePath) ?? "";
-        }
-        else {
-            const current = resolveSourcePath(config, id, filePath);
-            if (fs.existsSync(current) && fs.statSync(current).isFile() && fs.statSync(current).size <= 2 * 1024 * 1024) {
-                comparison = fs.readFileSync(current, "utf8");
+        return await projectMutations.runConsistentRead(id, () => {
+            const historical = history.readTextFile(id, versionId, filePath);
+            if (historical === null)
+                return apiError(reply, 415, "HISTORY_FILE_PREVIEW_UNSUPPORTED", "该历史文件不存在或不能作为文本比较", { path: filePath });
+            let comparison = "";
+            if (query.against) {
+                comparison = history.readTextFile(id, query.against, filePath) ?? "";
             }
-        }
-        return { path: filePath, historical, comparison, against: query.against ?? "current" };
+            else {
+                const current = resolveSourcePath(config, id, filePath);
+                if (fs.existsSync(current) && fs.statSync(current).isFile() && fs.statSync(current).size <= 2 * 1024 * 1024) {
+                    comparison = fs.readFileSync(current, "utf8");
+                }
+            }
+            return { path: filePath, historical, comparison, against: query.against ?? "current" };
+        }, { preflight: () => {
+                if (!accessibleProject(db, id, user))
+                    throw Object.assign(new Error("项目不存在"), { statusCode: 404, code: "PROJECT_NOT_FOUND" });
+            } });
     });
     app.patch("/api/projects/:id/history/:versionId", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -711,10 +915,16 @@ export async function buildApp(config, db, options = {}) {
         const project = accessibleProject(db, id, user);
         if (!project || project.permission !== "owner")
             return apiError(reply, 403, "PROJECT_OWNER_ONLY", "只有项目所有者可以删除历史版本");
-        collaboration.flushProject(id);
-        if (!history.deleteVersion(id, versionId))
-            return apiError(reply, 404, "HISTORY_VERSION_NOT_FOUND", "历史版本不存在");
-        return { ok: true, stats: history.stats(id) };
+        return await projectMutations.runWrite(id, () => {
+            if (!history.deleteVersion(id, versionId))
+                return apiError(reply, 404, "HISTORY_VERSION_NOT_FOUND", "历史版本不存在");
+            return { ok: true, stats: history.stats(id) };
+        }, { preflight: () => {
+                requireProjectOwnerPermission(db, id, user);
+                if (!history.version(versionId, id)) {
+                    throw Object.assign(new Error("历史版本不存在"), { statusCode: 404, code: "HISTORY_VERSION_NOT_FOUND" });
+                }
+            } });
     });
     app.delete("/api/projects/:id/history", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -724,9 +934,10 @@ export async function buildApp(config, db, options = {}) {
         const project = accessibleProject(db, id, user);
         if (!project || project.permission !== "owner")
             return apiError(reply, 403, "PROJECT_OWNER_ONLY", "只有项目所有者可以清空历史版本");
-        collaboration.flushProject(id);
-        history.clear(id);
-        return { ok: true, stats: history.stats(id) };
+        return await projectMutations.runWrite(id, () => {
+            history.clear(id);
+            return { ok: true, stats: history.stats(id) };
+        }, { preflight: () => { requireProjectOwnerPermission(db, id, user); } });
     });
     app.post("/api/projects/:id/history/:versionId/restore", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -738,15 +949,25 @@ export async function buildApp(config, db, options = {}) {
             return apiError(reply, 403, "PROJECT_EDIT_FORBIDDEN", "没有编辑权限");
         const body = request.body;
         const filePath = typeof body?.path === "string" ? safeRelativePath(body.path) : undefined;
-        collaboration.flushProject(id);
-        recordHistory(id, user.id, "checkpoint");
-        const before = projectTextSnapshot(config, id);
-        const restored = history.restore(id, versionId, filePath);
-        reanchorProjectSnapshot(db, id, before, projectTextSnapshot(config, id));
-        touchProject(db, id, user.id);
-        recordHistory(id, user.id, "restore", filePath ? [filePath] : undefined);
-        collaboration.resetProject(id);
-        return { ok: true, restoredPaths: restored.restoredPaths, project: projectJson(accessibleProject(db, id, user), tagsForProject(db, id, user.id)) };
+        return await projectMutations.runExclusive(id, "history restore", () => {
+            const currentProject = requireEditableProject(db, id, user);
+            recordHistory(id, user.id, "checkpoint");
+            const before = projectTextSnapshot(config, id);
+            const restored = history.restore(id, versionId, filePath);
+            reanchorProjectSnapshot(db, id, before, projectTextSnapshot(config, id));
+            touchProject(db, id, user.id);
+            recordHistory(id, user.id, "restore", filePath ? [filePath] : undefined);
+            return {
+                ok: true,
+                restoredPaths: restored.restoredPaths,
+                project: projectJson(accessibleProject(db, id, user) ?? currentProject, tagsForProject(db, id, user.id), commentsSummaryForProject(db, id))
+            };
+        }, { preflight: () => {
+                requireEditableProject(db, id, user);
+                if (!history.version(versionId, id)) {
+                    throw Object.assign(new Error("历史版本不存在"), { statusCode: 404, code: "HISTORY_VERSION_NOT_FOUND" });
+                }
+            } });
     });
     app.put("/api/projects/:id/archive", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -821,27 +1042,72 @@ export async function buildApp(config, db, options = {}) {
         if (!user)
             return;
         const { id } = request.params;
+        if (collaboration.isMaintaining(id))
+            return apiError(reply, 409, "PROJECT_BUSY", "项目正在执行源文件操作，请稍后重试");
         const project = accessibleProject(db, id, user);
         if (!project || project.permission !== "owner")
             return apiError(reply, 403, "PROJECT_OWNER_ONLY", "只有项目所有者可以修改项目设置");
         const body = request.body;
-        const name = typeof body.name === "string" ? text(body.name, "项目名称", 120) : project.name;
-        const mainFile = typeof body.mainFile === "string" ? safeRelativePath(body.mainFile) : project.main_file;
-        const engine = typeof body.engine === "string" && config.allowedEngines.includes(body.engine)
-            ? body.engine : project.engine;
-        const latexmkrc = body.latexmkrc === null || body.latexmkrc === ""
-            ? null
-            : typeof body.latexmkrc === "string" ? safeRelativePath(body.latexmkrc) : project.latexmkrc;
-        if (!fs.existsSync(resolveSourcePath(config, id, mainFile)))
-            return apiError(reply, 400, "MAIN_FILE_NOT_FOUND", "主文件不存在", { path: mainFile });
-        if (latexmkrc && !config.allowProjectLatexmkrc)
-            return apiError(reply, 400, "LATEXMKRC_DISABLED", "管理员已禁用项目级 latexmkrc");
-        if (latexmkrc && !fs.existsSync(resolveSourcePath(config, id, latexmkrc)))
-            return apiError(reply, 400, "LATEXMKRC_NOT_FOUND", "latexmkrc 文件不存在", { path: latexmkrc });
-        db.prepare("UPDATE projects SET name = ?, main_file = ?, latexmkrc = ?, engine = ?, updated_at = ?, last_modified_by = ? WHERE id = ?")
-            .run(name, mainFile, latexmkrc, engine, now(), user.id, id);
-        recordHistory(id, user.id, "settings", []);
-        return { project: projectJson(accessibleProject(db, id, user), tagsForProject(db, id, user.id)) };
+        return await projectMutations.runWrite(id, () => {
+            const currentProject = accessibleProject(db, id, user);
+            if (!currentProject || currentProject.permission !== "owner") {
+                return apiError(reply, 403, "PROJECT_OWNER_ONLY", "只有项目所有者可以修改项目设置");
+            }
+            const name = typeof body.name === "string" ? text(body.name, "项目名称", 120) : currentProject.name;
+            let mainFile = currentProject.main_file;
+            if (body.mainFile !== undefined) {
+                if (typeof body.mainFile !== "string" || !body.mainFile.trim()) {
+                    return apiError(reply, 400, "MAIN_FILE_INVALID", "主文件必须是存在的 .tex 文件");
+                }
+                mainFile = safeRelativePath(body.mainFile);
+            }
+            const engine = typeof body.engine === "string" && config.allowedEngines.includes(body.engine)
+                ? body.engine : currentProject.engine;
+            const latexmkrc = body.latexmkrc === null || body.latexmkrc === ""
+                ? null
+                : typeof body.latexmkrc === "string" ? safeRelativePath(body.latexmkrc) : currentProject.latexmkrc;
+            if (!mainFile.toLocaleLowerCase().endsWith(".tex")) {
+                return apiError(reply, 400, "MAIN_FILE_INVALID", "主文件必须是 .tex 文件", { path: mainFile });
+            }
+            const mainFileAbsolute = resolveSourcePath(config, id, mainFile);
+            let stat = null;
+            try {
+                stat = fs.statSync(mainFileAbsolute);
+            }
+            catch (error) {
+                if (error.code === "ENOENT") {
+                    return apiError(reply, 400, "MAIN_FILE_NOT_FOUND", "主文件不存在", { path: mainFile });
+                }
+                throw error;
+            }
+            if (!stat.isFile()) {
+                return apiError(reply, 400, "MAIN_FILE_INVALID", "主文件必须是常规文件，不能是目录", { path: mainFile });
+            }
+            if (latexmkrc && !config.allowProjectLatexmkrc)
+                return apiError(reply, 400, "LATEXMKRC_DISABLED", "管理员已禁用项目级 latexmkrc");
+            if (latexmkrc) {
+                const rcAbsolute = resolveSourcePath(config, id, latexmkrc);
+                let rcStat = null;
+                try {
+                    rcStat = fs.statSync(rcAbsolute);
+                }
+                catch (error) {
+                    if (error.code === "ENOENT") {
+                        return apiError(reply, 400, "LATEXMKRC_NOT_FOUND", "latexmkrc 文件不存在", { path: latexmkrc });
+                    }
+                    throw error;
+                }
+                if (!rcStat.isFile()) {
+                    return apiError(reply, 400, "LATEXMKRC_INVALID", "latexmkrc 必须是常规文件，不能是目录", { path: latexmkrc });
+                }
+            }
+            db.prepare("UPDATE projects SET name = ?, main_file = ?, latexmkrc = ?, engine = ?, updated_at = ?, last_modified_by = ? WHERE id = ?")
+                .run(name, mainFile, latexmkrc, engine, now(), user.id, id);
+            recordHistory(id, user.id, "settings", []);
+            return {
+                project: projectJson(accessibleProject(db, id, user), tagsForProject(db, id, user.id), commentsSummaryForProject(db, id))
+            };
+        }, { preflight: () => { requireProjectOwnerPermission(db, id, user); } });
     });
     app.post("/api/projects/:id/tags", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -858,7 +1124,10 @@ export async function buildApp(config, db, options = {}) {
         db.prepare("INSERT OR IGNORE INTO user_project_tag_links (project_id, tag_id, created_at) VALUES (?, ?, ?)")
             .run(id, body.tagId, now());
         const tags = tagsForProject(db, id, user.id);
-        return reply.code(201).send({ tags, project: projectJson(accessibleProject(db, id, user), tags) });
+        return reply.code(201).send({
+            tags,
+            project: projectJson(accessibleProject(db, id, user), tags, commentsSummaryForProject(db, id))
+        });
     });
     app.delete("/api/projects/:id/tags/:tagId", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -872,9 +1141,13 @@ export async function buildApp(config, db, options = {}) {
       AND EXISTS (SELECT 1 FROM user_tags WHERE id = ? AND user_id = ?)`)
             .run(tagId, id, tagId, user.id);
         const tags = tagsForProject(db, id, user.id);
-        return { tags, project: projectJson(accessibleProject(db, id, user), tags) };
+        return {
+            tags,
+            project: projectJson(accessibleProject(db, id, user), tags, commentsSummaryForProject(db, id))
+        };
     });
     const requireGitOwner = (projectId, user) => {
+        requireActiveUser(db, user);
         const project = accessibleProject(db, projectId, user);
         if (!project)
             throw Object.assign(new Error("项目不存在"), { statusCode: 404, code: "PROJECT_NOT_FOUND" });
@@ -887,7 +1160,9 @@ export async function buildApp(config, db, options = {}) {
         if (!user)
             return;
         const { id } = request.params;
-        return { status: await projectGit.status(requireGitOwner(id, user)) };
+        return await projectMutations.runConsistentRead(id, async () => {
+            return { status: await projectGit.status(requireGitOwner(id, user)) };
+        }, { preflight: () => { requireGitOwner(id, user); } });
     });
     app.put("/api/projects/:id/git/token", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -897,14 +1172,19 @@ export async function buildApp(config, db, options = {}) {
         const body = request.body;
         if (typeof body.token !== "string")
             return apiError(reply, 400, "GIT_TOKEN_INVALID", "请输入 GitHub token");
-        return { status: await projectGit.configureToken(requireGitOwner(id, user), body.token) };
+        const token = body.token;
+        return await projectMutations.runSerialized(id, async () => {
+            return { status: await projectGit.configureToken(requireGitOwner(id, user), token) };
+        }, { preflight: () => { requireGitOwner(id, user); } });
     });
     app.delete("/api/projects/:id/git/token", async (request, reply) => {
         const user = requireUser(request, reply, db);
         if (!user)
             return;
         const { id } = request.params;
-        return { status: await projectGit.removeToken(requireGitOwner(id, user)) };
+        return await projectMutations.runSerialized(id, async () => {
+            return { status: await projectGit.removeToken(requireGitOwner(id, user)) };
+        }, { preflight: () => { requireGitOwner(id, user); } });
     });
     app.post("/api/projects/:id/git/repository", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -914,34 +1194,45 @@ export async function buildApp(config, db, options = {}) {
         const body = request.body;
         if (typeof body.name !== "string")
             return apiError(reply, 400, "GIT_REPOSITORY_NAME_INVALID", "请输入 GitHub 仓库名称");
-        return { status: await projectGit.createGitHubRepository(requireGitOwner(id, user), body.name.trim(), body.private !== false) };
+        const repositoryName = body.name.trim();
+        return await projectMutations.runSerialized(id, async () => {
+            return { status: await projectGit.createGitHubRepository(requireGitOwner(id, user), repositoryName, body.private !== false) };
+        }, { preflight: () => { requireGitOwner(id, user); } });
     });
     app.post("/api/projects/:id/git/commit", async (request, reply) => {
         const user = requireUser(request, reply, db);
         if (!user)
             return;
         const { id } = request.params;
-        const project = requireGitOwner(id, user);
+        if (collaboration.isMaintaining(id))
+            return apiError(reply, 409, "PROJECT_BUSY", "项目正在执行源文件操作，请稍后重试");
         const body = request.body;
-        collaboration.flushProject(id);
-        const commit = await projectGit.commit(project, user, typeof body.message === "string" ? body.message : "");
-        return reply.code(201).send({ commit, status: await projectGit.status(project) });
+        return await projectMutations.runExclusive(id, "Git commit", async () => {
+            const project = requireGitOwner(id, user);
+            const commit = await projectGit.commit(project, user, typeof body.message === "string" ? body.message : "");
+            return reply.code(201).send({ commit, status: await projectGit.status(project) });
+        }, { preflight: () => { requireGitOwner(id, user); } });
     });
     app.post("/api/projects/:id/git/push", async (request, reply) => {
         const user = requireUser(request, reply, db);
         if (!user)
             return;
         const { id } = request.params;
-        const project = requireGitOwner(id, user);
-        collaboration.flushProject(id);
-        return { status: await projectGit.push(project) };
+        if (collaboration.isMaintaining(id))
+            return apiError(reply, 409, "PROJECT_BUSY", "项目正在执行源文件操作，请稍后重试");
+        return await projectMutations.runSerialized(id, async () => {
+            const project = requireGitOwner(id, user);
+            return { status: await projectGit.push(project) };
+        }, { flush: false, preflight: () => { requireGitOwner(id, user); } });
     });
     app.get("/api/projects/:id/git/history", async (request, reply) => {
         const user = requireUser(request, reply, db);
         if (!user)
             return;
         const { id } = request.params;
-        return { commits: await projectGit.history(requireGitOwner(id, user)) };
+        return await projectMutations.runConsistentRead(id, async () => {
+            return { commits: await projectGit.history(requireGitOwner(id, user)) };
+        }, { preflight: () => { requireGitOwner(id, user); } });
     });
     app.get("/api/projects/:id/git/diff", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -949,44 +1240,48 @@ export async function buildApp(config, db, options = {}) {
             return;
         const { id } = request.params;
         const { revision } = request.query;
-        const project = requireGitOwner(id, user);
-        collaboration.flushProject(id);
-        return projectGit.diff(project, revision);
+        return await projectMutations.runConsistentRead(id, async () => {
+            const project = requireGitOwner(id, user);
+            return projectGit.diff(project, revision);
+        }, { preflight: () => { requireGitOwner(id, user); } });
     });
     app.post("/api/projects/:id/git/checkout", async (request, reply) => {
         const user = requireUser(request, reply, db);
         if (!user)
             return;
         const { id } = request.params;
-        const project = requireGitOwner(id, user);
+        requireGitOwner(id, user);
         const body = request.body;
         if (body.revision !== null && typeof body.revision !== "string")
             return apiError(reply, 400, "GIT_REVISION_INVALID", "请选择要 checkout 的 Git 版本");
-        collaboration.flushProject(id);
-        recordHistory(id, user.id, "checkpoint");
-        const before = projectTextSnapshot(config, id);
-        const revision = await projectGit.checkout(project, body.revision, body.force === true);
-        reanchorProjectSnapshot(db, id, before, projectTextSnapshot(config, id));
-        touchProject(db, id, user.id);
-        recordHistory(id, user.id, "git");
-        collaboration.resetProject(id);
-        return { revision, status: await projectGit.status(project) };
+        const revisionInput = body.revision === null ? null : body.revision;
+        return await projectMutations.runExclusive(id, "Git checkout", async () => {
+            const currentProject = requireGitOwner(id, user);
+            recordHistory(id, user.id, "checkpoint");
+            const before = projectTextSnapshot(config, id);
+            const revision = await projectGit.checkout(currentProject, revisionInput, body.force === true);
+            reanchorProjectSnapshot(db, id, before, projectTextSnapshot(config, id));
+            touchProject(db, id, user.id);
+            recordHistory(id, user.id, "git");
+            return { revision, status: await projectGit.status(currentProject) };
+        }, { preflight: () => { requireGitOwner(id, user); } });
     });
     app.post("/api/projects/:id/git/discard", async (request, reply) => {
         const user = requireUser(request, reply, db);
         if (!user)
             return;
         const { id } = request.params;
-        const project = requireGitOwner(id, user);
-        collaboration.flushProject(id);
-        recordHistory(id, user.id, "checkpoint");
-        const before = projectTextSnapshot(config, id);
-        await projectGit.discardChanges(project);
-        reanchorProjectSnapshot(db, id, before, projectTextSnapshot(config, id));
-        touchProject(db, id, user.id);
-        recordHistory(id, user.id, "git");
-        collaboration.resetProject(id);
-        return { status: await projectGit.status(project) };
+        requireGitOwner(id, user);
+        return await projectMutations.runExclusive(id, "Git restore", async () => {
+            const currentProject = requireGitOwner(id, user);
+            recordHistory(id, user.id, "checkpoint");
+            const before = projectTextSnapshot(config, id);
+            await projectGit.discardChanges(currentProject);
+            reanchorProjectSnapshot(db, id, before, projectTextSnapshot(config, id));
+            touchProject(db, id, user.id);
+            recordHistory(id, user.id, "git");
+            return { status: await projectGit.status(currentProject) };
+        }, { preflight: () => { requireGitOwner(id, user); } });
     });
     app.get("/api/projects/:id/download", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -996,12 +1291,30 @@ export async function buildApp(config, db, options = {}) {
         const project = accessibleProject(db, id, user);
         if (!project)
             return apiError(reply, 404, "PROJECT_NOT_FOUND", "项目不存在");
-        collaboration.flushProject(id);
-        const archive = createProjectArchive(config, id);
+        const temporaryDirectory = path.join(config.dataDir, "tmp");
+        const temporaryArchive = path.join(temporaryDirectory, `project-${id}-${randomUUID()}.zip`);
+        try {
+            await fs.promises.mkdir(temporaryDirectory, { recursive: true, mode: 0o700 });
+            await projectMutations.runConsistentRead(id, () => writeProjectArchive(config, id, temporaryArchive), {
+                preflight: () => {
+                    const current = accessibleProject(db, id, user);
+                    if (!current)
+                        throw Object.assign(new Error("项目不存在"), { statusCode: 404, code: "PROJECT_NOT_FOUND" });
+                }
+            });
+        }
+        catch (error) {
+            await fs.promises.rm(temporaryArchive, { force: true }).catch(() => undefined);
+            throw error;
+        }
         const filename = `${project.name}.zip`;
         reply.header("Content-Type", "application/zip");
         reply.header("Content-Disposition", contentDisposition(filename, "attachment"));
-        return reply.send(archive.outputStream);
+        const stream = fs.createReadStream(temporaryArchive);
+        const cleanup = () => { void fs.promises.rm(temporaryArchive, { force: true }).catch(() => undefined); };
+        stream.once("close", cleanup);
+        stream.once("error", cleanup);
+        return reply.send(stream);
     });
     app.delete("/api/projects/:id", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -1011,10 +1324,14 @@ export async function buildApp(config, db, options = {}) {
         const project = accessibleProject(db, id, user);
         if (!project || project.permission !== "owner")
             return apiError(reply, 403, "PROJECT_DELETE_FORBIDDEN", "只有项目所有者可以删除项目");
-        collaboration.closeProject(id);
-        db.prepare("DELETE FROM projects WHERE id = ?").run(id);
-        removeProjectDirectory(config, id);
-        return { ok: true };
+        return await projectMutations.runExclusive(id, "project deletion", () => {
+            collaboration.resetProject(id);
+            removeProjectDirectory(config, id);
+            db.prepare("DELETE FROM projects WHERE id = ?").run(id);
+            latexCompletions.invalidate(id);
+            projectOutlines.invalidate(id);
+            return { ok: true };
+        }, { preflight: () => { requireProjectOwnerPermission(db, id, user); } });
     });
     app.get("/api/projects/:id/files", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -1024,9 +1341,18 @@ export async function buildApp(config, db, options = {}) {
         if (!accessibleProject(db, id, user))
             return apiError(reply, 404, "PROJECT_NOT_FOUND", "项目不存在");
         // Directory walks can be slow on external/project-mounted storage. Keep
-        // this request off the event loop so the retained-PDF metadata and PDF
-        // stream can be served while the file tree is being collected.
-        return { files: await listProjectFilesAsync(config, id) };
+        // this request off the event loop and unblocked by Yjs room initialization
+        // so the file tree and retained-PDF stream can be served concurrently, but
+        // still serialize it with source-tree mutations and collaborative flushes.
+        return await projectMutations.runFilesystemRead(id, async () => ({
+            files: await listProjectFilesAsync(config, id)
+        }), {
+            preflight: () => {
+                if (!accessibleProject(db, id, user)) {
+                    throw Object.assign(new Error("项目不存在"), { statusCode: 404, code: "PROJECT_NOT_FOUND" });
+                }
+            }
+        });
     });
     app.post("/api/projects/:id/format", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -1045,11 +1371,17 @@ export async function buildApp(config, db, options = {}) {
         }
         if (typeof body?.source !== "string")
             return apiError(reply, 400, "FORMAT_SOURCE_INVALID", "待格式化内容格式不正确");
-        if (Buffer.byteLength(body.source, "utf8") > config.maxUploadBytes) {
+        const source = body.source;
+        if (Buffer.byteLength(source, "utf8") > config.maxUploadBytes) {
             return apiError(reply, 413, "FILE_TOO_LARGE", `单个文件不能超过 ${Math.floor(config.maxUploadBytes / 1024 / 1024)} MB`, { path: filePath });
         }
         try {
-            return await latexFormatter.format(body.source, sourceRoot(config, id));
+            return await projectMutations.runConsistentRead(id, () => {
+                assertNoSourceSymlinks(config, id);
+                return latexFormatter.format(source, sourceRoot(config, id));
+            }, {
+                preflight: () => { requireEditableProject(db, id, user); }
+            });
         }
         catch (formatError) {
             const statusCode = typeof formatError === "object" && formatError !== null && "statusCode" in formatError && typeof formatError.statusCode === "number"
@@ -1072,10 +1404,20 @@ export async function buildApp(config, db, options = {}) {
         const mainFile = compileMainFile(config, id, project.main_file, query.mainFile);
         if (!mainFile)
             return apiError(reply, 400, "MAIN_DOCUMENT_INVALID", "所选文件不是有效的 LaTeX 主文档");
-        collaboration.flushProject(id);
         const startedAt = performance.now();
         try {
-            return { outline: buildProjectOutline(config, id, mainFile), mainFile };
+            return await projectMutations.runConsistentRead(id, async () => ({
+                outline: await projectOutlines.build(id, mainFile), mainFile
+            }), {
+                preflight: () => {
+                    const current = accessibleProject(db, id, user);
+                    if (!current)
+                        throw Object.assign(new Error("项目不存在"), { statusCode: 404, code: "PROJECT_NOT_FOUND" });
+                    const selected = compileMainFile(config, id, current.main_file, query.mainFile);
+                    if (!selected || selected !== mainFile)
+                        throw Object.assign(new Error("所选文件不是有效的 LaTeX 主文档"), { statusCode: 400, code: "MAIN_DOCUMENT_INVALID" });
+                }
+            });
         }
         finally {
             metrics.record("outline.build", performance.now() - startedAt);
@@ -1089,13 +1431,17 @@ export async function buildApp(config, db, options = {}) {
         if (!accessibleProject(db, id, user))
             return apiError(reply, 404, "PROJECT_NOT_FOUND", "项目不存在");
         const query = request.query;
-        collaboration.flushProject(id);
         const startedAt = performance.now();
         try {
-            return await searchProject(config, id, {
+            return await projectMutations.runConsistentRead(id, () => searchProject(config, id, {
                 query: query.q ?? "",
                 caseSensitive: query.caseSensitive === "1",
                 wholeWord: query.wholeWord === "1"
+            }), {
+                preflight: () => {
+                    if (!accessibleProject(db, id, user))
+                        throw Object.assign(new Error("项目不存在"), { statusCode: 404, code: "PROJECT_NOT_FOUND" });
+                }
             });
         }
         finally {
@@ -1114,23 +1460,25 @@ export async function buildApp(config, db, options = {}) {
         if (typeof body.query !== "string" || typeof body.replacement !== "string" || body.replacement.length > 100_000) {
             return apiError(reply, 400, "SEARCH_QUERY_INVALID", "搜索或替换内容格式不正确");
         }
-        collaboration.flushProject(id);
-        const changed = await replaceProject(config, id, {
-            query: body.query,
-            caseSensitive: body.caseSensitive === true,
-            wholeWord: body.wholeWord === true
-        }, body.replacement);
-        let replacements = 0;
-        for (const file of changed) {
-            reanchorFileComments(db, id, file.path, file.previous, file.content);
-            collaboration.updateFile(id, file.path, file.content, user.id);
-            replacements += file.count;
-        }
-        if (changed.length) {
-            touchProject(db, id, user.id);
-            recordHistory(id, user.id, "file", changed.map((file) => file.path));
-        }
-        return { ok: true, replacements, files: changed.map((file) => file.path) };
+        return await projectMutations.runExclusive(id, "project-wide replace", async () => {
+            const changed = await replaceProject(config, id, {
+                query: body.query,
+                caseSensitive: body.caseSensitive === true,
+                wholeWord: body.wholeWord === true,
+                maxFileBytes: maxCollaborativeFileBytes(config)
+            }, body.replacement);
+            let replacements = 0;
+            for (const file of changed) {
+                reanchorFileComments(db, id, file.path, file.previous, file.content);
+                collaboration.updateFile(id, file.path, file.content, user.id);
+                replacements += file.count;
+            }
+            if (changed.length) {
+                touchProject(db, id, user.id);
+                recordHistory(id, user.id, "file", changed.map((file) => file.path));
+            }
+            return { ok: true, replacements, files: changed.map((file) => file.path) };
+        }, { preflight: () => { requireEditableProject(db, id, user); } });
     });
     app.get("/api/projects/:id/completions", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -1139,10 +1487,14 @@ export async function buildApp(config, db, options = {}) {
         const { id } = request.params;
         if (!accessibleProject(db, id, user))
             return apiError(reply, 404, "PROJECT_NOT_FOUND", "项目不存在");
-        collaboration.flushProject(id);
         const startedAt = performance.now();
         try {
-            return { index: await latexCompletions.build(id) };
+            return await projectMutations.runConsistentRead(id, async () => ({ index: await latexCompletions.build(id) }), {
+                preflight: () => {
+                    if (!accessibleProject(db, id, user))
+                        throw Object.assign(new Error("项目不存在"), { statusCode: 404, code: "PROJECT_NOT_FOUND" });
+                }
+            });
         }
         finally {
             metrics.record("completions.build", performance.now() - startedAt);
@@ -1153,23 +1505,33 @@ export async function buildApp(config, db, options = {}) {
         if (!user)
             return;
         const { id } = request.params;
+        if (collaboration.isMaintaining(id))
+            return apiError(reply, 409, "PROJECT_BUSY", "项目正在执行源文件操作，请稍后重试");
         const project = accessibleProject(db, id, user);
         if (!project || !canEdit(project))
             return apiError(reply, 403, "PROJECT_EDIT_FORBIDDEN", "没有编辑权限");
         const body = request.body;
         const folderPath = safeRelativePath(typeof body.path === "string" ? body.path : "");
-        const absolute = resolveSourcePath(config, id, folderPath);
-        if (fs.existsSync(absolute))
-            return apiError(reply, 409, "PATH_EXISTS", "同名文件或目录已存在", { path: folderPath });
-        fs.mkdirSync(absolute, { recursive: true, mode: 0o700 });
-        touchProject(db, id, user.id);
-        return reply.code(201).send({ ok: true, path: folderPath });
+        return await projectMutations.runWrite(id, () => {
+            const absolute = resolveSourcePath(config, id, folderPath);
+            if (fs.existsSync(absolute))
+                return apiError(reply, 409, "PATH_EXISTS", "同名文件或目录已存在", { path: folderPath });
+            fs.mkdirSync(absolute, { recursive: true, mode: 0o700 });
+            touchProject(db, id, user.id);
+            // Empty folders have no file entry to trigger a refresh on their own.
+            // Publish a source-tree event so other open sessions see the folder
+            // immediately instead of waiting for a later file operation.
+            collaboration.invalidateSourceTree(id, folderPath);
+            return reply.code(201).send({ ok: true, path: folderPath });
+        }, { preflight: () => { requireEditableProject(db, id, user); } });
     });
     app.patch("/api/projects/:id/path", async (request, reply) => {
         const user = requireUser(request, reply, db);
         if (!user)
             return;
         const { id } = request.params;
+        if (collaboration.isMaintaining(id))
+            return apiError(reply, 409, "PROJECT_BUSY", "项目正在执行源文件操作，请稍后重试");
         const project = accessibleProject(db, id, user);
         if (!project || !canEdit(project))
             return apiError(reply, 403, "PROJECT_EDIT_FORBIDDEN", "没有编辑权限");
@@ -1177,11 +1539,16 @@ export async function buildApp(config, db, options = {}) {
         const source = safeRelativePath(typeof body.source === "string" ? body.source : "");
         const destinationDirectory = body.destinationDirectory === "" ? ""
             : safeRelativePath(typeof body.destinationDirectory === "string" ? body.destinationDirectory : "");
+        const destination = destinationDirectory
+            ? `${destinationDirectory}/${path.posix.basename(source)}`
+            : path.posix.basename(source);
         const sourceAbsolute = resolveSourcePath(config, id, source);
         if (!fs.existsSync(sourceAbsolute))
             return apiError(reply, 404, "PATH_NOT_FOUND", "要移动的文件或目录不存在", { path: source });
-        const sourceStat = fs.statSync(sourceAbsolute);
-        if (sourceStat.isDirectory() && (destinationDirectory === source || destinationDirectory.startsWith(`${source}/`))) {
+        if (destination === source)
+            return { ok: true, path: source };
+        const initialSourceStat = fs.statSync(sourceAbsolute);
+        if (initialSourceStat.isDirectory() && (destinationDirectory === source || destinationDirectory.startsWith(`${source}/`))) {
             return apiError(reply, 400, "MOVE_INTO_SELF", "不能把目录移动到自身内部", { path: source });
         }
         const destinationRoot = destinationDirectory
@@ -1190,40 +1557,59 @@ export async function buildApp(config, db, options = {}) {
         if (!fs.existsSync(destinationRoot) || !fs.statSync(destinationRoot).isDirectory()) {
             return apiError(reply, 404, "DIRECTORY_NOT_FOUND", "目标目录不存在", { path: destinationDirectory });
         }
-        const destination = destinationDirectory
-            ? `${destinationDirectory}/${path.posix.basename(source)}`
-            : path.posix.basename(source);
-        if (destination === source)
-            return { ok: true, path: source };
         const destinationAbsolute = resolveSourcePath(config, id, destination);
         if (fs.existsSync(destinationAbsolute))
             return apiError(reply, 409, "PATH_EXISTS", "目标目录中存在同名文件或目录", { path: destination });
-        collaboration.flushProject(id);
-        fs.renameSync(sourceAbsolute, destinationAbsolute);
-        db.exec("BEGIN IMMEDIATE");
-        try {
-            const mainFile = movedProjectPath(project.main_file, source, destination);
-            const latexmkrc = movedProjectPath(project.latexmkrc, source, destination);
-            const changedAt = now();
-            db.prepare(`UPDATE projects SET main_file = ?, latexmkrc = ?, updated_at = ?, last_modified_by = ? WHERE id = ?`)
-                .run(mainFile, latexmkrc, changedAt, user.id, id);
-            const comments = db.prepare("SELECT id, file_path FROM comments WHERE project_id = ?").all(id);
-            const updateComment = db.prepare("UPDATE comments SET file_path = ?, updated_at = ? WHERE id = ?");
-            for (const comment of comments) {
-                const nextPath = movedProjectPath(comment.file_path, source, destination);
-                if (nextPath !== comment.file_path)
-                    updateComment.run(nextPath, changedAt, comment.id);
+        let currentProject = project;
+        const validateMove = () => {
+            currentProject = requireEditableProject(db, id, user);
+            assertNoSourceSymlinks(config, id);
+            if (!fs.existsSync(sourceAbsolute)) {
+                throw Object.assign(new Error("要移动的文件或目录不存在"), { statusCode: 404, code: "PATH_NOT_FOUND" });
             }
-            db.exec("COMMIT");
-        }
-        catch (error) {
-            db.exec("ROLLBACK");
-            fs.renameSync(destinationAbsolute, sourceAbsolute);
-            throw error;
-        }
-        collaboration.movePath(id, source, destination, user.id);
-        recordHistory(id, user.id, "file", [source, destination]);
-        return { ok: true, path: destination };
+            const sourceStat = fs.statSync(sourceAbsolute);
+            if (sourceStat.isDirectory() && (destinationDirectory === source || destinationDirectory.startsWith(`${source}/`))) {
+                throw Object.assign(new Error("不能把目录移动到自身内部"), { statusCode: 400, code: "MOVE_INTO_SELF" });
+            }
+            if (!fs.existsSync(destinationRoot) || !fs.statSync(destinationRoot).isDirectory()) {
+                throw Object.assign(new Error("目标目录不存在"), { statusCode: 404, code: "DIRECTORY_NOT_FOUND" });
+            }
+            if (fs.existsSync(destinationAbsolute)) {
+                throw Object.assign(new Error("目标目录中存在同名文件或目录"), { statusCode: 409, code: "PATH_EXISTS" });
+            }
+        };
+        return await projectMutations.runExclusive(id, "move project path", () => {
+            fs.renameSync(sourceAbsolute, destinationAbsolute);
+            let hasCommentUpdates = false;
+            db.exec("BEGIN IMMEDIATE");
+            try {
+                const mainFile = movedProjectPath(currentProject.main_file, source, destination);
+                const latexmkrc = movedProjectPath(currentProject.latexmkrc, source, destination);
+                const changedAt = now();
+                db.prepare(`UPDATE projects SET main_file = ?, latexmkrc = ?, updated_at = ?, last_modified_by = ? WHERE id = ?`)
+                    .run(mainFile, latexmkrc, changedAt, user.id, id);
+                const comments = db.prepare("SELECT id, file_path FROM comments WHERE project_id = ?").all(id);
+                const updateComment = db.prepare("UPDATE comments SET file_path = ?, updated_at = ? WHERE id = ?");
+                for (const comment of comments) {
+                    const nextPath = movedProjectPath(comment.file_path, source, destination);
+                    if (nextPath !== comment.file_path) {
+                        updateComment.run(nextPath, changedAt, comment.id);
+                        hasCommentUpdates = true;
+                    }
+                }
+                db.exec("COMMIT");
+            }
+            catch (error) {
+                db.exec("ROLLBACK");
+                fs.renameSync(destinationAbsolute, sourceAbsolute);
+                throw error;
+            }
+            collaboration.movePath(id, source, destination, user.id);
+            if (hasCommentUpdates)
+                collaboration.signalComments(id);
+            recordHistory(id, user.id, "file", [source, destination]);
+            return { ok: true, path: destination };
+        }, { preflight: validateMove });
     });
     app.get("/api/projects/:id/file/raw", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -1234,9 +1620,25 @@ export async function buildApp(config, db, options = {}) {
             return apiError(reply, 404, "PROJECT_NOT_FOUND", "项目不存在");
         const query = request.query;
         const filePath = safeRelativePath(query.path ?? "");
-        const absolute = resolveSourcePath(config, id, filePath);
-        if (!fs.existsSync(absolute) || !fs.statSync(absolute).isFile())
-            return apiError(reply, 404, "FILE_NOT_FOUND", "文件不存在", { path: filePath });
+        const temporaryDirectory = path.join(config.dataDir, "tmp");
+        const temporaryFile = path.join(temporaryDirectory, `file-${id}-${randomUUID()}`);
+        try {
+            await fs.promises.mkdir(temporaryDirectory, { recursive: true, mode: 0o700 });
+            await projectMutations.runConsistentRead(id, async () => {
+                const absolute = resolveSourcePath(config, id, filePath);
+                if (!fs.existsSync(absolute) || !fs.statSync(absolute).isFile()) {
+                    throw Object.assign(new Error("文件不存在"), { statusCode: 404, code: "FILE_NOT_FOUND" });
+                }
+                await fs.promises.copyFile(absolute, temporaryFile);
+            }, { preflight: () => {
+                    if (!accessibleProject(db, id, user))
+                        throw Object.assign(new Error("项目不存在"), { statusCode: 404, code: "PROJECT_NOT_FOUND" });
+                } });
+        }
+        catch (error) {
+            await fs.promises.rm(temporaryFile, { force: true }).catch(() => undefined);
+            throw error;
+        }
         const extension = path.extname(filePath).toLocaleLowerCase();
         const contentTypes = {
             ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp",
@@ -1248,8 +1650,12 @@ export async function buildApp(config, db, options = {}) {
         reply.header("Content-Type", contentType);
         reply.header("Content-Disposition", contentDisposition(path.basename(filePath), downloading ? "attachment" : "inline"));
         reply.header("Cache-Control", "private, no-cache");
-        reply.header("Content-Length", fs.statSync(absolute).size);
-        return reply.send(fs.createReadStream(absolute));
+        reply.header("Content-Length", fs.statSync(temporaryFile).size);
+        const stream = fs.createReadStream(temporaryFile);
+        const cleanup = () => { void fs.promises.rm(temporaryFile, { force: true }).catch(() => undefined); };
+        stream.once("close", cleanup);
+        stream.once("error", cleanup);
+        return reply.send(stream);
     });
     app.get("/api/projects/:id/file", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -1259,12 +1665,19 @@ export async function buildApp(config, db, options = {}) {
         const { path: filePath } = request.query;
         if (!accessibleProject(db, id, user))
             return apiError(reply, 404, "PROJECT_NOT_FOUND", "项目不存在");
-        const absolute = resolveSourcePath(config, id, filePath ?? "");
-        if (!fs.existsSync(absolute) || !fs.statSync(absolute).isFile())
-            return apiError(reply, 404, "FILE_NOT_FOUND", "文件不存在", { path: filePath });
-        if (fs.statSync(absolute).size > 5 * 1024 * 1024)
-            return apiError(reply, 413, "FILE_TOO_LARGE", "文件过大，不能作为文本打开", { path: filePath });
-        return { path: safeRelativePath(filePath ?? ""), content: fs.readFileSync(absolute, "utf8") };
+        const relative = safeRelativePath(filePath ?? "");
+        return await projectMutations.runConsistentRead(id, () => {
+            const absolute = resolveSourcePath(config, id, relative);
+            if (!fs.existsSync(absolute) || !fs.statSync(absolute).isFile())
+                return apiError(reply, 404, "FILE_NOT_FOUND", "文件不存在", { path: relative });
+            if (isCollaborativeTextFile(relative) && fs.statSync(absolute).size > maxCollaborativeFileBytes(config)) {
+                return apiError(reply, 413, "FILE_TOO_LARGE", "协作文本文件过大，不能作为编辑器内容打开", { path: relative });
+            }
+            return { path: relative, content: fs.readFileSync(absolute, "utf8") };
+        }, { preflight: () => {
+                if (!accessibleProject(db, id, user))
+                    throw Object.assign(new Error("项目不存在"), { statusCode: 404, code: "PROJECT_NOT_FOUND" });
+            } });
     });
     // Creating a file is intentionally separate from updating one.  The editor
     // uses PUT for autosaves, but a user action such as "New file" must never
@@ -1274,91 +1687,122 @@ export async function buildApp(config, db, options = {}) {
         if (!user)
             return;
         const { id } = request.params;
+        if (collaboration.isMaintaining(id))
+            return apiError(reply, 409, "PROJECT_BUSY", "项目正在执行源文件操作，请稍后重试");
         const project = accessibleProject(db, id, user);
         if (!project || !canEdit(project))
             return apiError(reply, 403, "PROJECT_EDIT_FORBIDDEN", "没有编辑权限");
         const body = request.body;
         const filePath = safeRelativePath(typeof body.path === "string" ? body.path : "");
         if (typeof body.content !== "string")
-            throw new Error("文件内容格式不正确");
-        if (Buffer.byteLength(body.content, "utf8") > config.maxUploadBytes) {
-            return apiError(reply, 413, "FILE_TOO_LARGE", `单个文件不能超过 ${Math.floor(config.maxUploadBytes / 1024 / 1024)} MB`, { path: filePath, size: Math.floor(config.maxUploadBytes / 1024 / 1024) });
-        }
-        const absolute = resolveSourcePath(config, id, filePath);
-        try {
-            fs.mkdirSync(path.dirname(absolute), { recursive: true, mode: 0o700 });
-        }
-        catch (error) {
-            if (["EEXIST", "ENOTDIR"].includes(error.code ?? "")) {
-                return apiError(reply, 409, "PATH_EXISTS", "目标路径中的目录部分已被文件占用", { path: filePath });
+            return apiError(reply, 400, "FILE_CONTENT_INVALID", "文件内容格式不正确");
+        const content = body.content;
+        const byteLength = Buffer.byteLength(content, "utf8");
+        const limit = isCollaborativeTextFile(filePath) ? maxCollaborativeFileBytes(config) : config.maxUploadBytes;
+        if (byteLength > limit) {
+            return apiError(reply, 413, "FILE_TOO_LARGE", `该文件不能超过 ${Math.floor(limit / 1024 / 1024)} MB`, { path: filePath, size: Math.floor(limit / 1024 / 1024) });
+        }
+        return await projectMutations.runWrite(id, () => {
+            const absolute = resolveSourcePath(config, id, filePath);
+            try {
+                fs.mkdirSync(path.dirname(absolute), { recursive: true, mode: 0o700 });
             }
-            throw error;
-        }
-        try {
-            fs.writeFileSync(absolute, body.content, { encoding: "utf8", mode: 0o600, flag: "wx" });
-        }
-        catch (error) {
-            if (error.code === "EEXIST") {
-                return apiError(reply, 409, "FILE_EXISTS", "同名文件或目录已存在", { path: filePath });
+            catch (error) {
+                if (["EEXIST", "ENOTDIR"].includes(error.code ?? "")) {
+                    return apiError(reply, 409, "PATH_EXISTS", "目标路径中的目录部分已被文件占用", { path: filePath });
+                }
+                throw error;
             }
-            throw error;
-        }
-        touchProject(db, id, user.id);
-        collaboration.updateFile(id, filePath, body.content, user.id);
-        recordHistory(id, user.id, "file", [filePath]);
-        return reply.code(201).send({ ok: true, path: filePath, comments: commentsForFile(db, config, id, filePath) });
+            try {
+                fs.writeFileSync(absolute, content, { encoding: "utf8", mode: 0o600, flag: "wx" });
+            }
+            catch (error) {
+                if (error.code === "EEXIST") {
+                    return apiError(reply, 409, "FILE_EXISTS", "同名文件或目录已存在", { path: filePath });
+                }
+                throw error;
+            }
+            touchProject(db, id, user.id);
+            collaboration.updateFile(id, filePath, content, user.id);
+            recordHistory(id, user.id, "file", [filePath]);
+            return reply.code(201).send({ ok: true, path: filePath, comments: commentsForFile(db, config, id, filePath) });
+        }, { preflight: () => { requireEditableProject(db, id, user); } });
     });
     app.put("/api/projects/:id/file", async (request, reply) => {
         const user = requireUser(request, reply, db);
         if (!user)
             return;
         const { id } = request.params;
+        if (collaboration.isMaintaining(id))
+            return apiError(reply, 409, "PROJECT_BUSY", "项目正在执行源文件操作，请稍后重试");
         const project = accessibleProject(db, id, user);
         if (!project || !canEdit(project))
             return apiError(reply, 403, "PROJECT_EDIT_FORBIDDEN", "没有编辑权限");
         const body = request.body;
         const filePath = safeRelativePath(typeof body.path === "string" ? body.path : "");
         if (typeof body.content !== "string")
-            throw new Error("文件内容格式不正确");
-        if (Buffer.byteLength(body.content, "utf8") > config.maxUploadBytes) {
-            return apiError(reply, 413, "FILE_TOO_LARGE", `单个文件不能超过 ${Math.floor(config.maxUploadBytes / 1024 / 1024)} MB`, { path: filePath, size: Math.floor(config.maxUploadBytes / 1024 / 1024) });
-        }
-        const absolute = resolveSourcePath(config, id, filePath);
-        fs.mkdirSync(path.dirname(absolute), { recursive: true, mode: 0o700 });
-        const previousContent = fs.existsSync(absolute) ? fs.readFileSync(absolute, "utf8") : "";
-        reanchorFileComments(db, id, filePath, previousContent, body.content);
-        fs.writeFileSync(absolute, body.content, { encoding: "utf8", mode: 0o600 });
-        touchProject(db, id, user.id);
-        collaboration.updateFile(id, filePath, body.content, user.id);
-        recordHistory(id, user.id, "file", [filePath]);
-        return { ok: true, comments: commentsForFile(db, config, id, filePath) };
+            return apiError(reply, 400, "FILE_CONTENT_INVALID", "文件内容格式不正确");
+        const content = body.content;
+        const byteLength = Buffer.byteLength(content, "utf8");
+        const limit = isCollaborativeTextFile(filePath) ? maxCollaborativeFileBytes(config) : config.maxUploadBytes;
+        if (byteLength > limit) {
+            return apiError(reply, 413, "FILE_TOO_LARGE", `该文件不能超过 ${Math.floor(limit / 1024 / 1024)} MB`, { path: filePath, size: Math.floor(limit / 1024 / 1024) });
+        }
+        return await projectMutations.runWrite(id, () => {
+            const absolute = resolveSourcePath(config, id, filePath);
+            fs.mkdirSync(path.dirname(absolute), { recursive: true, mode: 0o700 });
+            const previousContent = fs.existsSync(absolute) ? fs.readFileSync(absolute, "utf8") : "";
+            reanchorFileComments(db, id, filePath, previousContent, content);
+            fs.writeFileSync(absolute, content, { encoding: "utf8", mode: 0o600 });
+            touchProject(db, id, user.id);
+            collaboration.updateFile(id, filePath, content, user.id);
+            recordHistory(id, user.id, "file", [filePath]);
+            return { ok: true, comments: commentsForFile(db, config, id, filePath) };
+        }, { preflight: () => { requireEditableProject(db, id, user); } });
     });
     app.delete("/api/projects/:id/file", async (request, reply) => {
         const user = requireUser(request, reply, db);
         if (!user)
             return;
         const { id } = request.params;
+        if (collaboration.isMaintaining(id))
+            return apiError(reply, 409, "PROJECT_BUSY", "项目正在执行源文件操作，请稍后重试");
         const { path: filePath } = request.query;
+        const relative = safeRelativePath(filePath ?? "");
         const project = accessibleProject(db, id, user);
         if (!project || !canEdit(project))
             return apiError(reply, 403, "PROJECT_EDIT_FORBIDDEN", "没有编辑权限");
-        const relative = safeRelativePath(filePath ?? "");
-        if (relative === project.main_file || project.main_file.startsWith(`${relative}/`)) {
-            return apiError(reply, 400, "MAIN_FILE_DELETE_FORBIDDEN", "不能删除当前主文件或包含主文件的目录", { path: relative });
-        }
-        if (!fs.existsSync(resolveSourcePath(config, id, relative)))
-            return apiError(reply, 404, "PATH_NOT_FOUND", "文件或目录不存在", { path: relative });
-        fs.rmSync(resolveSourcePath(config, id, relative), { recursive: true, force: true });
-        touchProject(db, id, user.id);
-        collaboration.removePath(id, relative);
-        recordHistory(id, user.id, "file", [relative]);
-        return { ok: true };
+        return await projectMutations.runWrite(id, () => {
+            const currentProject = requireEditableProject(db, id, user);
+            if (relative === currentProject.main_file || currentProject.main_file.startsWith(`${relative}/`)) {
+                return apiError(reply, 400, "MAIN_FILE_DELETE_FORBIDDEN", "不能删除当前主文件或包含主文件的目录", { path: relative });
+            }
+            const absolute = resolveSourcePath(config, id, relative, { allowFinalSymlink: true });
+            try {
+                fs.lstatSync(absolute);
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return apiError(reply, 404, "PATH_NOT_FOUND", "文件或目录不存在", { path: relative });
+                throw error;
+            }
+            fs.rmSync(absolute, { recursive: true, force: true });
+            const deleteResult = db.prepare("DELETE FROM comments WHERE project_id = ? AND (file_path = ? OR file_path GLOB ?)").run(id, relative, `${escapeGlobPattern(relative)}/*`);
+            touchProject(db, id, user.id);
+            collaboration.removePath(id, relative);
+            if (deleteResult.changes > 0)
+                collaboration.signalComments(id);
+            recordHistory(id, user.id, "file", [relative]);
+            return { ok: true };
+        }, { preflight: () => { requireEditableProject(db, id, user); } });
     });
     app.post("/api/projects/:id/upload", async (request, reply) => {
         const user = requireUser(request, reply, db);
         if (!user)
             return;
         const { id } = request.params;
+        if (collaboration.isMaintaining(id))
+            return apiError(reply, 409, "PROJECT_BUSY", "项目正在执行源文件操作，请稍后重试");
         const project = accessibleProject(db, id, user);
         if (!project || !canEdit(project))
             return apiError(reply, 403, "PROJECT_EDIT_FORBIDDEN", "没有编辑权限");
@@ -1367,34 +1811,98 @@ export async function buildApp(config, db, options = {}) {
             return apiError(reply, 400, "UPLOAD_EMPTY", "没有收到上传文件");
         const { directory, overwrite } = request.query;
         const relative = safeRelativePath(directory ? `${safeRelativePath(directory)}/${part.filename}` : part.filename);
-        const absolute = resolveSourcePath(config, id, relative);
+        const uploadLimit = isCollaborativeTextFile(relative) ? maxCollaborativeFileBytes(config) : config.maxUploadBytes;
+        const tmpDir = path.join(config.dataDir, "tmp");
+        fs.mkdirSync(tmpDir, { recursive: true, mode: 0o700 });
+        const tmpPath = path.join(tmpDir, `upload-${randomUUID()}.tmp`);
+        let byteLength = 0;
         try {
-            fs.mkdirSync(path.dirname(absolute), { recursive: true, mode: 0o700 });
+            const limiter = new Transform({
+                transform(chunk, _encoding, callback) {
+                    byteLength += chunk.length;
+                    if (byteLength > uploadLimit) {
+                        callback(new Error("FILE_TOO_LARGE"));
+                    }
+                    else {
+                        callback(null, chunk);
+                    }
+                }
+            });
+            await pipeline(part.file, limiter, fs.createWriteStream(tmpPath, { mode: 0o600 }));
         }
         catch (error) {
-            if (["EEXIST", "ENOTDIR"].includes(error.code ?? "")) {
-                return apiError(reply, 409, "PATH_EXISTS", "目标路径中的目录部分已被文件占用", { path: relative });
+            if (fs.existsSync(tmpPath)) {
+                try {
+                    fs.unlinkSync(tmpPath);
+                }
+                catch { /* ignore */ }
+            }
+            if (error instanceof Error && error.message === "FILE_TOO_LARGE") {
+                return apiError(reply, 413, "FILE_TOO_LARGE", `该文件不能超过 ${Math.floor(uploadLimit / 1024 / 1024)} MB`, { path: relative, size: Math.floor(uploadLimit / 1024 / 1024) });
             }
             throw error;
         }
-        const uploaded = await part.toBuffer();
-        const replacing = overwrite === "1";
-        if (fs.existsSync(absolute) && fs.statSync(absolute).isDirectory()) {
-            return apiError(reply, 409, "PATH_EXISTS", "目标路径是一个目录", { path: relative });
-        }
         try {
-            fs.writeFileSync(absolute, uploaded, { mode: 0o600, flag: replacing ? "w" : "wx" });
+            return await projectMutations.runWrite(id, () => {
+                const absolute = resolveSourcePath(config, id, relative);
+                try {
+                    fs.mkdirSync(path.dirname(absolute), { recursive: true, mode: 0o700 });
+                }
+                catch (error) {
+                    if (["EEXIST", "ENOTDIR"].includes(error.code ?? "")) {
+                        return apiError(reply, 409, "PATH_EXISTS", "目标路径中的目录部分已被文件占用", { path: relative });
+                    }
+                    throw error;
+                }
+                const replacing = overwrite === "1";
+                if (fs.existsSync(absolute) && fs.statSync(absolute).isDirectory()) {
+                    return apiError(reply, 409, "PATH_EXISTS", "目标路径是一个目录", { path: relative });
+                }
+                if (!replacing && fs.existsSync(absolute)) {
+                    return apiError(reply, 409, "FILE_EXISTS", "同名文件已存在", { path: relative });
+                }
+                const collaborativeText = isCollaborativeTextFile(relative);
+                let previousContent = null;
+                if (replacing && collaborativeText && fs.existsSync(absolute)) {
+                    // runWrite() has flushed any live Yjs edits before entering this
+                    // callback. Prefer the room's text so comment anchors are based on
+                    // exactly what collaborators last saved, then fall back to disk for
+                    // projects without an active collaboration room.
+                    previousContent = collaboration.fileContent(id, relative);
+                    if (previousContent === null)
+                        previousContent = fs.readFileSync(absolute, "utf8");
+                }
+                try {
+                    fs.renameSync(tmpPath, absolute);
+                }
+                catch {
+                    fs.copyFileSync(tmpPath, absolute);
+                    fs.unlinkSync(tmpPath);
+                }
+                touchProject(db, id, user.id);
+                if (collaborativeText) {
+                    const content = fs.readFileSync(absolute, "utf8");
+                    if (previousContent !== null && previousContent !== content) {
+                        reanchorFileComments(db, id, relative, previousContent, content);
+                        collaboration.signalComments(id);
+                    }
+                    collaboration.updateFile(id, relative, content, user.id);
+                }
+                else {
+                    collaboration.invalidateSourceTree(id, relative);
+                }
+                recordHistory(id, user.id, "file", [relative]);
+                return reply.code(201).send({ ok: true, path: relative });
+            }, { preflight: () => { requireEditableProject(db, id, user); } });
         }
-        catch (error) {
-            if (error.code === "EEXIST") {
-                return apiError(reply, 409, "FILE_EXISTS", "同名文件已存在", { path: relative });
+        finally {
+            if (fs.existsSync(tmpPath)) {
+                try {
+                    fs.unlinkSync(tmpPath);
+                }
+                catch { /* ignore */ }
             }
-            throw error;
         }
-        touchProject(db, id, user.id);
-        collaboration.updateFile(id, relative, uploaded.toString("utf8"), user.id);
-        recordHistory(id, user.id, "file", [relative]);
-        return reply.code(201).send({ ok: true, path: relative });
     });
     app.get("/api/projects/:id/members", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -1426,34 +1934,44 @@ export async function buildApp(config, db, options = {}) {
         const target = db.prepare("SELECT id FROM users WHERE id = ? AND disabled = 0").get(body.userId);
         if (!target)
             return apiError(reply, 404, "USER_NOT_FOUND", "用户不存在或已被禁用");
-        collaboration.flushProject(id);
-        const changedAt = now();
-        db.exec("BEGIN IMMEDIATE");
-        try {
-            // The new owner may already be a shared member. The previous owner keeps
-            // edit access so a transfer does not unexpectedly lock them out.
-            db.prepare("DELETE FROM project_members WHERE project_id = ? AND user_id = ?").run(id, target.id);
-            db.prepare(`INSERT INTO project_members (project_id, user_id, permission, created_at)
-        VALUES (?, ?, 'edit', ?)
-        ON CONFLICT(project_id, user_id) DO UPDATE SET permission = 'edit'`)
-                .run(id, user.id, changedAt);
-            db.prepare("UPDATE projects SET owner_id = ?, last_modified_by = ?, updated_at = ? WHERE id = ?")
-                .run(target.id, user.id, changedAt, id);
-            // A project token belongs to the account that supplied it. Preserve the
-            // local repository/remote metadata, but require the new owner to add
-            // their own credential before the next GitHub operation.
-            db.prepare("UPDATE project_git_settings SET token_ciphertext = NULL, github_login = NULL, updated_at = ? WHERE project_id = ?")
-                .run(changedAt, id);
-            db.exec("COMMIT");
-        }
-        catch (error) {
-            db.exec("ROLLBACK");
-            throw error;
-        }
-        collaboration.resetProject(id);
-        return {
-            project: projectJson(accessibleProject(db, id, user), tagsForProject(db, id, user.id))
-        };
+        return await projectMutations.runExclusive(id, "project transfer", () => {
+            const currentTarget = db.prepare("SELECT id FROM users WHERE id = ? AND disabled = 0").get(body.userId);
+            // The synchronous preflight immediately precedes maintenance, so this
+            // lookup cannot change before the operation starts.
+            if (!currentTarget)
+                throw Object.assign(new Error("用户不存在或已被禁用"), { statusCode: 404, code: "USER_NOT_FOUND" });
+            const changedAt = now();
+            db.exec("BEGIN IMMEDIATE");
+            try {
+                // The new owner may already be a shared member. The previous owner keeps
+                // edit access so a transfer does not unexpectedly lock them out.
+                db.prepare("DELETE FROM project_members WHERE project_id = ? AND user_id = ?").run(id, currentTarget.id);
+                db.prepare(`INSERT INTO project_members (project_id, user_id, permission, created_at)
+          VALUES (?, ?, 'edit', ?)
+          ON CONFLICT(project_id, user_id) DO UPDATE SET permission = 'edit'`)
+                    .run(id, user.id, changedAt);
+                db.prepare("UPDATE projects SET owner_id = ?, last_modified_by = ?, updated_at = ? WHERE id = ?")
+                    .run(currentTarget.id, user.id, changedAt, id);
+                // A project token belongs to the account that supplied it. Preserve the
+                // local repository/remote metadata, but require the new owner to add
+                // their own credential before the next GitHub operation.
+                db.prepare("UPDATE project_git_settings SET token_ciphertext = NULL, github_login = NULL, updated_at = ? WHERE project_id = ?")
+                    .run(changedAt, id);
+                db.exec("COMMIT");
+            }
+            catch (error) {
+                db.exec("ROLLBACK");
+                throw error;
+            }
+            return {
+                project: projectJson(accessibleProject(db, id, user), tagsForProject(db, id, user.id), commentsSummaryForProject(db, id))
+            };
+        }, { preflight: () => {
+                requireActualProjectOwner(db, id, user);
+                if (!db.prepare("SELECT 1 FROM users WHERE id = ? AND disabled = 0").get(body.userId)) {
+                    throw Object.assign(new Error("用户不存在或已被禁用"), { statusCode: 404, code: "USER_NOT_FOUND" });
+                }
+            } });
     });
     app.put("/api/projects/:id/members/:userId", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -1465,12 +1983,16 @@ export async function buildApp(config, db, options = {}) {
             return apiError(reply, 403, "MEMBERS_MANAGE_FORBIDDEN", "只有项目所有者可以管理成员");
         if (userId === project.owner_id)
             return apiError(reply, 400, "OWNER_MEMBER_FORBIDDEN", "项目所有者不能作为成员添加");
+        if (!db.prepare("SELECT 1 FROM users WHERE id = ? AND disabled = 0").get(userId)) {
+            return apiError(reply, 404, "USER_NOT_FOUND", "用户不存在或已被禁用");
+        }
         const body = request.body;
         const permission = body.permission === "edit" ? "edit" : "read";
         db.prepare(`INSERT INTO project_members (project_id, user_id, permission, created_at) VALUES (?, ?, ?, ?)
       ON CONFLICT(project_id, user_id) DO UPDATE SET permission = excluded.permission`)
             .run(id, userId, permission, now());
         touchProject(db, id, user.id);
+        collaboration.notifyPermissionChanged(id, userId, permission);
         return { ok: true };
     });
     app.delete("/api/projects/:id/members/:userId", async (request, reply) => {
@@ -1483,6 +2005,7 @@ export async function buildApp(config, db, options = {}) {
             return apiError(reply, 403, "MEMBERS_MANAGE_FORBIDDEN", "只有项目所有者可以管理成员");
         db.prepare("DELETE FROM project_members WHERE project_id = ? AND user_id = ?").run(id, userId);
         touchProject(db, id, user.id);
+        collaboration.notifyPermissionChanged(id, userId, "revoked");
         return { ok: true };
     });
     app.get("/api/projects/:id/comments", async (request, reply) => {
@@ -1494,7 +2017,14 @@ export async function buildApp(config, db, options = {}) {
         if (!accessibleProject(db, id, user))
             return apiError(reply, 404, "PROJECT_NOT_FOUND", "项目不存在");
         const relative = safeRelativePath(filePath ?? "");
-        return { comments: commentsForFile(db, config, id, relative) };
+        return {
+            comments: await projectMutations.runConsistentRead(id, () => commentsForFile(db, config, id, relative), {
+                preflight: () => {
+                    if (!accessibleProject(db, id, user))
+                        throw Object.assign(new Error("项目不存在"), { statusCode: 404, code: "PROJECT_NOT_FOUND" });
+                }
+            })
+        };
     });
     app.post("/api/projects/:id/comments", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -1506,27 +2036,31 @@ export async function buildApp(config, db, options = {}) {
         const body = request.body;
         const createdAt = now();
         const filePath = safeRelativePath(typeof body.path === "string" ? body.path : "");
-        collaboration.flushProject(id);
-        const absolute = resolveSourcePath(config, id, filePath);
-        if (!fs.existsSync(absolute))
-            return apiError(reply, 404, "COMMENT_FILE_NOT_FOUND", "批注文件不存在");
-        const source = fs.readFileSync(absolute, "utf8");
-        if (!Number.isInteger(body.startOffset) || !Number.isInteger(body.endOffset)) {
-            return apiError(reply, 400, "COMMENT_RANGE_INVALID", "批注缺少有效的源码区间");
-        }
-        const anchor = createSourceAnchor(source, Number(body.startOffset), Number(body.endOffset));
-        const comment = {
-            id: randomUUID(), filePath,
-            content: text(body.content, "批注", 5000)
-        };
-        db.prepare(`INSERT INTO comments
-      (id, project_id, file_path, author_id, selected_text, start_offset, end_offset,
-       context_before, context_after, orphaned, start_line, end_line, content, created_at, updated_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?)`)
-            .run(comment.id, id, comment.filePath, user.id, anchor.selectedText, anchor.startOffset, anchor.endOffset, anchor.contextBefore, anchor.contextAfter, offsetToLine(source, anchor.startOffset), offsetToLine(source, anchor.endOffset), comment.content, createdAt, createdAt);
-        const created = commentsForFile(db, config, id, filePath).find((item) => item.id === comment.id);
-        collaboration.signalComments(id);
-        return reply.code(201).send({ comment: created });
+        return await projectMutations.runWrite(id, () => {
+            const absolute = resolveSourcePath(config, id, filePath);
+            if (!fs.existsSync(absolute))
+                return apiError(reply, 404, "COMMENT_FILE_NOT_FOUND", "批注文件不存在");
+            const source = fs.readFileSync(absolute, "utf8");
+            if (!Number.isInteger(body.startOffset) || !Number.isInteger(body.endOffset)) {
+                return apiError(reply, 400, "COMMENT_RANGE_INVALID", "批注缺少有效的源码区间");
+            }
+            const anchor = createSourceAnchor(source, Number(body.startOffset), Number(body.endOffset));
+            const comment = {
+                id: randomUUID(), filePath,
+                content: text(body.content, "批注", 5000)
+            };
+            db.prepare(`INSERT INTO comments
+        (id, project_id, file_path, author_id, selected_text, start_offset, end_offset,
+         context_before, context_after, orphaned, start_line, end_line, content, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?)`)
+                .run(comment.id, id, comment.filePath, user.id, anchor.selectedText, anchor.startOffset, anchor.endOffset, anchor.contextBefore, anchor.contextAfter, offsetToLine(source, anchor.startOffset), offsetToLine(source, anchor.endOffset), comment.content, createdAt, createdAt);
+            const created = commentsForFile(db, config, id, filePath).find((item) => item.id === comment.id);
+            collaboration.signalComments(id);
+            return reply.code(201).send({ comment: created });
+        }, { preflight: () => {
+                if (!accessibleProject(db, id, user))
+                    throw Object.assign(new Error("项目不存在"), { statusCode: 404, code: "PROJECT_NOT_FOUND" });
+            } });
     });
     app.post("/api/projects/:id/comments/:commentId/replies", async (request, reply) => {
         const user = requireUser(request, reply, db);
@@ -1638,7 +2172,7 @@ export async function buildApp(config, db, options = {}) {
         collaboration.signalComments(id);
         return { ok: true };
     });
-    registerCompileRoutes(app, { config, db, collaboration, compileCoordinator, metrics, pruneCompileRuns });
+    registerCompileRoutes(app, { config, db, collaboration, projectMutations, compileCoordinator, metrics, pruneCompileRuns });
     app.addHook("onRequest", async (request) => {
         if (request.url.startsWith("/api/") && request.url !== "/api/auth/login" && request.url !== "/api/health" && request.url !== "/api/config") {
             const token = request.cookies.texlite_session;
@@ -1657,5 +2191,20 @@ export async function buildApp(config, db, options = {}) {
             return reply.sendFile("index.html");
         });
     }
+    const cleanupExpiredSessions = () => {
+        try {
+            pruneExpiredSessions(db, now());
+            loginLimiter.prune();
+        }
+        catch (error) {
+            app.log.error({ err: error }, "Failed to prune expired sessions");
+        }
+    };
+    // Clean up at startup as well as periodically so long-running deployments do
+    // not retain one row per historical login indefinitely.
+    cleanupExpiredSessions();
+    const sessionCleanupTimer = setInterval(cleanupExpiredSessions, SESSION_CLEANUP_INTERVAL_MS);
+    sessionCleanupTimer.unref();
+    app.addHook("onClose", async () => { clearInterval(sessionCleanupTimer); });
     return app;
 }