dsh-config-manager 0.1.84 → 0.1.85

package/lib/core/messages.d.ts

@@ -172,6 +172,7 @@ export declare const zh: {
     readonly 'host.exportTimeout': '导出超时（5 分钟）：导出过程未完成，请重试；若反复超时请检查 profile 依赖状态';
     readonly 'host.syncPushTimeout': '同步推送超时（5 分钟）：请检查网络与仓库可达性后重试';
     readonly 'host.syncPullTimeout': '同步拉取超时（5 分钟）：请检查网络与仓库可达性后重试';
+    readonly 'host.syncStatusTimeout': '同步状态读取超时（10 秒）：DSH 凭据服务或工作副本自检没有在预算内返回，请重试';
     readonly 'host.workspaceUnavailable': 'workspaceRegistry 服务不可用，无法写入工作区';
     readonly 'host.workspaceMissingTarget': '目标机不存在工作区 {id}（无法登记会话）';
     readonly 'host.sessionStoreShapeUnknown': '宿主会话存储列举（sessionPersistence.list()）的元素形状无法解析（探测形状 {shape}，{count} 个元素全部认不出）：父子关系判定放弃，绝不当作「本机没有父子关系」（请升级 DSH，或把该形状反馈给插件）';

package/lib/core/messages.js

@@ -161,6 +161,7 @@ export const zh = {
     'host.exportTimeout': '导出超时（5 分钟）：导出过程未完成，请重试；若反复超时请检查 profile 依赖状态',
     'host.syncPushTimeout': '同步推送超时（5 分钟）：请检查网络与仓库可达性后重试',
     'host.syncPullTimeout': '同步拉取超时（5 分钟）：请检查网络与仓库可达性后重试',
+    'host.syncStatusTimeout': '同步状态读取超时（10 秒）：DSH 凭据服务或工作副本自检没有在预算内返回，请重试',
     'host.workspaceUnavailable': 'workspaceRegistry 服务不可用，无法写入工作区',
     'host.workspaceMissingTarget': '目标机不存在工作区 {id}（无法登记会话）',
     'host.sessionStoreShapeUnknown': '宿主会话存储列举（sessionPersistence.list()）的元素形状无法解析（探测形状 {shape}，{count} 个元素全部认不出）：父子关系判定放弃，绝不当作「本机没有父子关系」（请升级 DSH，或把该形状反馈给插件）',
@@ -650,6 +651,7 @@ export const en = {
     'host.exportTimeout': 'Export timed out (5 min): the export did not complete, please retry; if it keeps timing out, check the profile dependency state',
     'host.syncPushTimeout': 'Sync push timed out (5 min): check network and repository reachability, then retry',
     'host.syncPullTimeout': 'Sync pull timed out (5 min): check network and repository reachability, then retry',
+    'host.syncStatusTimeout': 'Sync status timed out (10 s): the DSH credential service or work-copy self-check did not return within budget; please retry',
     'host.workspaceUnavailable': 'workspaceRegistry service unavailable; cannot write the workspace',
     'host.workspaceMissingTarget': 'Workspace {id} does not exist on this machine (cannot attach the session)',
     'host.sessionStoreShapeUnknown': 'Cannot parse the elements returned by the host session store (sessionPersistence.list(); probed shape {shape}, none of the {count} elements is recognizable): parent/child detection is abandoned rather than treated as "no parent relations on this machine" (please upgrade DSH or report this shape to the plugin)',

package/lib/index.d.ts

@@ -77,7 +77,7 @@ export declare const name = "config-manager";
 /** Services required before the engine can mount (present in every profile). */
 export declare const inject: string[];
 /** Plugin version, kept in sync with package.json ("version"). */
-export declare const PLUGIN_VERSION = "0.1.84";
+export declare const PLUGIN_VERSION = "0.1.85";
 /**
  * Star 引导弹窗指向的 GitHub 仓库（用户引导点 Star 的目标）。
  * 与 package.json 的 repository 字段保持一致；界面不可改（硬编码，参照
@@ -812,7 +812,9 @@ export type RouteEnvInferred = {
     syncDir: string;
     syncPasswordConfigured: (ref: string) => Promise<boolean>;
     syncWorkDir: {
-        inspect: (repoUrl: string) => Promise<{
+        inspect: (repoUrl: string, opts?: {
+            detail?: boolean;
+        }) => Promise<{
             facts: GitWorkDirFacts;
         } | {
             error: string;

package/lib/index.js

@@ -136,7 +136,7 @@ export const name = 'config-manager';
 /** Services required before the engine can mount (present in every profile). */
 export const inject = ['settings', 'credentials'];
 /** Plugin version, kept in sync with package.json ("version"). */
-export const PLUGIN_VERSION = '0.1.84';
+export const PLUGIN_VERSION = '0.1.85';
 /** Plugin own package name — excluded from its own exported plugins list. */
 const PLUGIN_NAME = 'dsh-config-manager';
 /**
@@ -2981,12 +2981,12 @@ function makeRoutes(deps) {
             syncWorkDir: {
                 // 自检失败（git 不可用 / 工作副本异常）→ 返回 { error }，**不让整个状态接口 500**，
                 // 也不伪装成「工作副本不存在」。
-                inspect: async (repoUrl) => {
+                inspect: async (repoUrl, opts = {}) => {
                     try {
                         // issue #104 建议 3：`/sync/status` 要回传「领先远端提交数 / 远端快照数」，
-                        // 用户看不见积压，就会在「以为在备份」的状态下一直失败。detail 多出的几条命令
-                        // 都是本地只读（rev-list / status / ls-tree），不发网络请求。
-                        return { facts: await makeGitTransport(repoUrl).inspectWorkDir({ detail: true }) };
+                        // 用户看不见积压就会在「以为在备份」的状态下一直失败。detail 那几条是本地只读但各起
+                        // 一次 git 进程（Windows 约 80 ms）⇒ 缺省完整（WorkDirCard 要），路由可传 false。
+                        return { facts: await makeGitTransport(repoUrl).inspectWorkDir({ detail: opts.detail !== false }) };
                     }
                     catch (err) {
                         return { error: err instanceof Error ? err.message : String(err) };

package/lib/routes/sync.js

@@ -4,7 +4,7 @@
  * W1（host-entry#F-02/#F-03）：路由只在这里声明一次 —— endpoint({ path, methods }, handler) 的
  * path/methods 就是唯一声明处；围栏、方法判定与顶层异常处理由 src/routes/kit.ts 在注册点统一提供。
  */
-import { endpoint, requireJsonObject, readJsonBody, writeJson } from './kit.js';
+import { endpoint, queryParam, requireJsonObject, readJsonBody, writeJson } from './kit.js';
 import { EnvironmentLockUnavailableError, runWithMutationLock } from '../utils/env-lock.js';
 import { FileSnapshotStore } from '../core/index.js';
 import { rollback as performRollback } from '../core/rollback.js';
@@ -129,81 +129,103 @@ export function syncRoutes(env) {
         }
         return out;
     };
+    /**
+     * /sync/status 的取值体。
+     *
+     * 只读端点也碰两处**不可控延迟**：DSH credentials 服务（describe/resolve）与 git 工作副本自检
+     * （子进程 + 工作副本锁）。任一处永不返回时，裸 await 会让 HTTP 响应永不被写出 ——
+     * 首页首屏会永久停在骨架（2026-10 现场：/sync/status 300 s 无响应，其余只读端点均毫秒级）。
+     * ⇒ 整个组装套总预算，超时如实报 503，保证请求有界返回。
+     */
+    const SYNC_STATUS_BUDGET_MS = 10_000;
+    /**
+     * @param workDirDetail 是否连「领先远端提交数 / 未提交改动 / 远端快照数」一起自检。
+     *   那三项多起 5 条 git 子进程（Windows 每次约 80 ms；实测完整自检 585 ms、端点 730 ms）。
+     *   只有同步页的 WorkDirCard 渲染它们 —— 首页与产物库只问「工作副本是否跟随配置地址」。
+     */
+    const collectSyncStatus = async (opts) => {
+        // 完整双命名空间配置：repoUrl / webdav.url 无论当前通道都回填，
+        // 保证 UI 在 git ↔ webdav 间切换时另一通道的地址不丢失
+        const full = await readFullSyncConfig(syncDir);
+        const state = await loadSyncState(syncDir);
+        const [cred, webdavCred] = await Promise.all([
+            credentials.describe(credentialRef(SYNC_CREDENTIAL_REF)),
+            credentials.describe(credentialRef(SYNC_WEBDAV_CREDENTIAL_REF)),
+        ]);
+        const transport = parseSyncChannel(full?.transport) ?? 'git';
+        // m-self：插件 UI 偏好（上次选择的同步通道；ui-prefs.json，随 self 分区进备份）
+        const uiPrefs = await readUiPrefs(syncDir);
+        // webdav 配置视图（配置过即返回，与当前通道无关：供表单在 git ↔ webdav 切换时回填）
+        const webdav = full?.webdav !== undefined
+            ? {
+                url: full.webdav.url,
+                // username 非敏感可回显，供表单回填
+                username: full.webdav.username,
+                usernameConfigured: typeof full.webdav.username === 'string' && full.webdav.username !== '',
+                passwordConfigured: webdavCred.configured,
+            }
+            : undefined;
+        // 云端点配置视图（只回 secretStored 布尔；与当前通道无关，配置过即回填）
+        const cloud = await cloudChannelViews(full, credentials);
+        // issue #79 / #104 建议 3：git 工作副本是否已跟随 repoUrl，外加「领先远端提交数 /
+        // 远端快照数」（只读自检；后者是「本地一直没真正备份」的预警依据）。
+        // 读不出来时**如实回传错误**（workDirError），不让状态接口静默少一块信息。
+        const gitRepoUrl = full?.git?.repoUrl ?? '';
+        let workDir = null;
+        if (gitRepoUrl !== '')
+            workDir = await syncWorkDir.inspect(gitRepoUrl, { detail: opts.workDirDetail });
+        return {
+            ok: true,
+            configured: full !== null,
+            transport,
+            repoUrl: full?.git?.repoUrl,
+            credentialConfigured: cred.configured,
+            credentialWritable: cred.writable === true,
+            // webdav 配置状态（无 secret 值：口令用 passwordConfigured 布尔标记）
+            ...(webdav !== undefined ? { webdav } : {}),
+            // 云端点：当前活动 s3 兼容商 / gist 的非密配置（无任何密钥值）
+            ...(cloud.s3 === undefined ? {} : { s3: cloud.s3 }),
+            ...(cloud.gist === undefined ? {} : { gist: cloud.gist }),
+            // 已保存的云端点 provider 清单（切换 provider 时回填用；只有名字，无任何值）
+            cloudSavedProviders: await listCloudConfiguredProviders(syncDir),
+            lastSyncAt: state.lastSyncAt === '' ? undefined : state.lastSyncAt,
+            // 方案 A（同步页按钮瘦身）：是否存在同步基线（本地祖先指针）。**只回布尔，绝不回快照 id** ——
+            // 界面据此在「有基线 → 三方裁决视图 / 无基线 → 导入确认」之间分派；缺省 undefined 按无基线处理。
+            hasBaseline: state.lastSnapshotId !== '',
+            sectionCount: Object.keys(state.sections).length,
+            lastTransport: state.transport,
+            // 上次选择的同步通道（磁盘 ui-prefs；UI 回填优先于此，localStorage 仅兜底）
+            lastSyncChannel: uiPrefs.lastSyncChannel,
+            // 可同步分区目录（「高级/自定义导出」勾选列表；只含 portable，无 secret 值）
+            syncSections: syncSectionCatalog,
+            // 当前分区选择（默认/高级模式 + 勾选分区；当前激活通道；UI 回填用，自动同步共用）
+            syncSelection: await selectionView(transport),
+            // 全部通道的分区选择（git/webdav 各自独立；UI 按当前 tab 取对应通道）
+            syncSelectionByChannel: await selectionViewByChannel(),
+            // 全部通道的同步密码保存状态（加密/解密；只回布尔，值永不回传浏览器）
+            syncCredentialsByChannel: await syncCredentialsByChannelView(),
+            // 自动同步当前状态（当前激活通道；供 UI 顶部开关回填；§3.9）
+            autosync: await buildAutosyncStatus(syncDir, transport),
+            // 全部通道的自动同步状态（git/webdav 各自独立；UI 按当前 tab 取对应通道）
+            autosyncByChannel: await buildAutosyncStatusByChannel(syncDir),
+            // 工作副本事实（仅 git 且配置了地址时返回；'facts' = 自检成功，'error' = 自检读不出来）
+            ...(workDir === null ? {} : { workDir }),
+        };
+    };
     return [
         // ------------------------------------------------------ sync/status
         // m-sync-ui：同步状态（通道配置 / 凭据状态 / 上次同步 / 分区数）。只读，无 secret 值。
         endpoint({ path: '/api/dsh-config-manager/sync/status', methods: ['GET'] }, async (req, res) => {
             try {
-                // 完整双命名空间配置：repoUrl / webdav.url 无论当前通道都回填，
-                // 保证 UI 在 git ↔ webdav 间切换时另一通道的地址不丢失
-                const full = await readFullSyncConfig(syncDir);
-                const state = await loadSyncState(syncDir);
-                const [cred, webdavCred] = await Promise.all([
-                    credentials.describe(credentialRef(SYNC_CREDENTIAL_REF)),
-                    credentials.describe(credentialRef(SYNC_WEBDAV_CREDENTIAL_REF)),
-                ]);
-                const transport = parseSyncChannel(full?.transport) ?? 'git';
-                // m-self：插件 UI 偏好（上次选择的同步通道；ui-prefs.json，随 self 分区进备份）
-                const uiPrefs = await readUiPrefs(syncDir);
-                // webdav 配置视图（配置过即返回，与当前通道无关：供表单在 git ↔ webdav 切换时回填）
-                const webdav = full?.webdav !== undefined
-                    ? {
-                        url: full.webdav.url,
-                        // username 非敏感可回显，供表单回填
-                        username: full.webdav.username,
-                        usernameConfigured: typeof full.webdav.username === 'string' && full.webdav.username !== '',
-                        passwordConfigured: webdavCred.configured,
-                    }
-                    : undefined;
-                // 云端点配置视图（只回 secretStored 布尔；与当前通道无关，配置过即回填）
-                const cloud = await cloudChannelViews(full, credentials);
-                // issue #79 / #104 建议 3：git 工作副本是否已跟随 repoUrl，外加「领先远端提交数 /
-                // 远端快照数」（只读自检；后者是「本地一直没真正备份」的预警依据）。
-                // 读不出来时**如实回传错误**（workDirError），不让状态接口静默少一块信息。
-                const gitRepoUrl = full?.git?.repoUrl ?? '';
-                let workDir = null;
-                if (gitRepoUrl !== '')
-                    workDir = await syncWorkDir.inspect(gitRepoUrl);
-                writeJson(res, 200, {
-                    ok: true,
-                    configured: full !== null,
-                    transport,
-                    repoUrl: full?.git?.repoUrl,
-                    credentialConfigured: cred.configured,
-                    credentialWritable: cred.writable === true,
-                    // webdav 配置状态（无 secret 值：口令用 passwordConfigured 布尔标记）
-                    ...(webdav !== undefined ? { webdav } : {}),
-                    // 云端点：当前活动 s3 兼容商 / gist 的非密配置（无任何密钥值）
-                    ...(cloud.s3 === undefined ? {} : { s3: cloud.s3 }),
-                    ...(cloud.gist === undefined ? {} : { gist: cloud.gist }),
-                    // 已保存的云端点 provider 清单（切换 provider 时回填用；只有名字，无任何值）
-                    cloudSavedProviders: await listCloudConfiguredProviders(syncDir),
-                    lastSyncAt: state.lastSyncAt === '' ? undefined : state.lastSyncAt,
-                    // 方案 A（同步页按钮瘦身）：是否存在同步基线（本地祖先指针）。**只回布尔，绝不回快照 id** ——
-                    // 界面据此在「有基线 → 三方裁决视图 / 无基线 → 导入确认」之间分派；缺省 undefined 按无基线处理。
-                    hasBaseline: state.lastSnapshotId !== '',
-                    sectionCount: Object.keys(state.sections).length,
-                    lastTransport: state.transport,
-                    // 上次选择的同步通道（磁盘 ui-prefs；UI 回填优先于此，localStorage 仅兜底）
-                    lastSyncChannel: uiPrefs.lastSyncChannel,
-                    // 可同步分区目录（「高级/自定义导出」勾选列表；只含 portable，无 secret 值）
-                    syncSections: syncSectionCatalog,
-                    // 当前分区选择（默认/高级模式 + 勾选分区；当前激活通道；UI 回填用，自动同步共用）
-                    syncSelection: await selectionView(transport),
-                    // 全部通道的分区选择（git/webdav 各自独立；UI 按当前 tab 取对应通道）
-                    syncSelectionByChannel: await selectionViewByChannel(),
-                    // 全部通道的同步密码保存状态（加密/解密；只回布尔，值永不回传浏览器）
-                    syncCredentialsByChannel: await syncCredentialsByChannelView(),
-                    // 自动同步当前状态（当前激活通道；供 UI 顶部开关回填；§3.9）
-                    autosync: await buildAutosyncStatus(syncDir, transport),
-                    // 全部通道的自动同步状态（git/webdav 各自独立；UI 按当前 tab 取对应通道）
-                    autosyncByChannel: await buildAutosyncStatusByChannel(syncDir),
-                    // 工作副本事实（仅 git 且配置了地址时返回；'facts' = 自检成功，'error' = 自检读不出来）
-                    ...(workDir === null ? {} : { workDir }),
-                });
+                // detail=0：跳过 workDir 的 ahead / dirty / remoteSnapshots（省 5 次 git 子进程启动）。
+                // 缺省仍做完整自检 —— 老调用方按原语义继续拿到全部字段，关掉时那三项如实回 null。
+                const workDirDetail = queryParam(new URL(req.url ?? '/', 'http://localhost'), 'detail') !== '0';
+                writeJson(res, 200, await withTimeout(collectSyncStatus({ workDirDetail }), SYNC_STATUS_BUDGET_MS, msg('host.syncStatusTimeout')));
             }
             catch (error) {
-                writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+                const message = error instanceof Error ? error.message : String(error);
+                // 预算耗尽 = 暂不可用（503）；其余异常仍是 500。两者都让客户端拿到明确错误而不是空等。
+                writeJson(res, message === msg('host.syncStatusTimeout') ? 503 : 500, { error: message });
             }
         }),
         // ------------------------------------------------------ sync/workdir/reset
@@ -819,7 +841,7 @@ export function syncRoutes(env) {
                     ...(pathMappings.length === 0 ? {} : { pathMappings }),
                 }), ROUTE_TIMEOUT_MS, msg('host.syncPullTimeout'));
                 if (!preview.ok || preview.plan === null || preview.analysis === null) {
-                    writeJson(res, 200, { ok: false, syncSessionId: '', snapshotId: preview.snapshotId, items: [], needsReview: false, compatibility: 'unsupported', message: preview.message ?? msg('route.syncPreviewFailed') });
+                    writeJson(res, 200, { ok: false, syncSessionId: '', snapshotId: preview.snapshotId, items: [], needsReview: false, compatibility: 'unsupported', message: preview.message ?? msg('route.syncPreviewFailed'), reason: preview.reason });
                     return;
                 }
                 // T1：abort 处置在**预览阶段**就阻断（此刻仍零写入：临时 ZIP 与内存会话都还没登记）。

package/lib/sync/git/git-transport.d.ts

@@ -37,6 +37,8 @@ export interface GitWorkDirFacts {
      */
     remoteSnapshots: number | null;
 }
+/** 清空自检缓存（测试隔离用；生产路径由 `withWorkdir` 逐 key 失效）。 */
+export declare function clearInspectFactsCache(): void;
 /** 凭据提供者：token 只从这里读取，绝不在任何地方持久化 */
 export interface GitCredentialProvider {
     getToken(): Promise<string>;

package/lib/sync/git/git-transport.js

@@ -35,6 +35,31 @@ import { zhMsg } from '../../core/messages.js';
 import { withWorkdirLock, WorkdirLockError } from '../../utils/workdir-lock.js';
 import { fastForwardFetchArgs, fastForwardMergeArgs, isMissingRemoteRefError, parseCurrentBranch } from '../../utils/git-fast-forward.js';
 const execFileAsync = promisify(execFile);
+/**
+ * 工作副本自检结果的短 TTL 缓存（`inspectWorkDir`，2026-10-27）。
+ *
+ * 为什么需要：自检的每个字段都是一次 `git.exe` 进程启动，Windows 上每次 ~80 ms 固定开销
+ * （实测 detail 版 7 条命令 = 585 ms，`GET /sync/status` 整体 730 ms）。它挂在状态接口上，
+ * 首页 / 同步页 / 切页 / 轮询会在几秒内重复索取，而工作副本状态不会在 10 秒里反复变化。
+ *
+ * 为什么放模块级而不是实例字段：`makeGitTransport()` 每次请求都新建实例（src/index.ts:3313），
+ * 实例级缓存等于没有缓存。
+ *
+ * 「完整事实」判定：`detail: true` 的结果是默认结果的超集 ⇒ 完整条目能满足任何请求，默认条目
+ * 不能满足 detail 请求；写回时 detail 结果总是覆盖，默认结果只在还没有完整条目时写入 ——
+ * 否则一次默认请求会把刚拿到的 ahead/dirty/remoteSnapshots 冲掉。
+ *
+ * 失效：`withWorkdir` 在除自检之外的每条路径收尾后都删掉本 key（写操作必然可能改变事实）。
+ */
+const INSPECT_FACTS_TTL_MS = 10_000;
+const inspectFactsCache = new Map();
+function inspectFactsCacheKey(workDir, repoUrl) {
+    return workDir + '\u0000' + repoUrl;
+}
+/** 清空自检缓存（测试隔离用；生产路径由 `withWorkdir` 逐 key 失效）。 */
+export function clearInspectFactsCache() {
+    inspectFactsCache.clear();
+}
 /**
  * git 通道错误：继承统一错误基类（kind / retryable / status 分类对上层可见）。
  * 分类口径见 transport.ts 的 classifyNetworkErrorText / classifyHttpStatus。
@@ -370,7 +395,10 @@ export class GitTransport {
      */
     async probe() {
         await this.checkIsPrivate();
-        return { message: this.msg('sync.git.probeOk') };
+        // issue #115：ls-remote 只证明「能读」。写权限是**另一项**授权（细粒度 PAT 的 Contents: Read and write、
+        // SSH 部署密钥的 Allow write access），而传输层没有 REST 通道去查它 —— 宁可明说「写权限未验证」，
+        // 也不给一句「连接正常」让用户以为推送必然成功（真正暴露问题的地方是他的第一次推送）。
+        return { message: this.msg('sync.git.probeOk'), hint: this.msg('sync.git.probeReadOnlyHint') };
     }
     /* ---------------- 内部实现 ---------------- */
     /**
@@ -383,18 +411,9 @@ export class GitTransport {
      *
      * 可重入：内层（ensureRepo/pullFromRemote/adoptRemoteHistory 等）不重复取锁。
      */
-    async withWorkdir(fn) {
-        if (this.workdirLockDepth > 0) {
-            this.workdirLockDepth += 1;
-            try {
-                return await fn();
-            }
-            finally {
-                this.workdirLockDepth -= 1;
-            }
-        }
+    async withWorkdir(fn, opts = {}) {
         try {
-            return await withWorkdirLock(this.o.workDir, async () => {
+            if (this.workdirLockDepth > 0) {
                 this.workdirLockDepth += 1;
                 try {
                     return await fn();
@@ -402,15 +421,32 @@ export class GitTransport {
                 finally {
                     this.workdirLockDepth -= 1;
                 }
-            });
-        }
-        catch (err) {
-            // 等锁超时 = 别人正在同步（另一个 DSH 实例 / 另一个同步任务），不是通道故障：
-            // 给可操作文案并标记 retryable，别让它伪装成「git 命令失败」。
-            if (err instanceof WorkdirLockError) {
-                throw new GitTransportError(this.msg('sync.git.workdirBusy', { dir: this.o.workDir }), { kind: 'conflict', retryable: true });
             }
-            throw err;
+            try {
+                return await withWorkdirLock(this.o.workDir, async () => {
+                    this.workdirLockDepth += 1;
+                    try {
+                        return await fn();
+                    }
+                    finally {
+                        this.workdirLockDepth -= 1;
+                    }
+                });
+            }
+            catch (err) {
+                // 等锁超时 = 别人正在同步（另一个 DSH 实例 / 另一个同步任务），不是通道故障：
+                // 给可操作文案并标记 retryable，别让它伪装成「git 命令失败」。
+                if (err instanceof WorkdirLockError) {
+                    throw new GitTransportError(this.msg('sync.git.workdirBusy', { dir: this.o.workDir }), { kind: 'conflict', retryable: true });
+                }
+                throw err;
+            }
+        }
+        finally {
+            // 除纯只读自检外，任何操作都可能改变工作副本状态（push 改 ahead、fetch 改远端引用、
+            // 重建删目录、失败也可能已留下 commit）→ 收尾即丢弃自检缓存，绝不让「写后读」看到旧事实。
+            if (opts.readonly !== true)
+                inspectFactsCache.delete(inspectFactsCacheKey(this.o.workDir, this.o.repoUrl));
         }
     }
     async ensureRepo() {
@@ -499,8 +535,21 @@ export class GitTransport {
      * 因此放进 `detail: true`（供「重建工作副本」前评估数据量等场景显式索取）。
      */
     async inspectWorkDir(opts = {}) {
+        const key = inspectFactsCacheKey(this.o.workDir, this.o.repoUrl);
+        const detail = opts.detail === true;
+        const hit = inspectFactsCache.get(key);
+        // 命中即返回：不必排队等锁，也不必再 spawn 一条 git（这是首页/切页/轮询的常态路径）。
+        // 返回浅拷贝 —— 缓存条目绝不外泄给调用方修改。
+        if (hit !== undefined && Date.now() - hit.at < INSPECT_FACTS_TTL_MS && (hit.detail || !detail)) {
+            return { ...hit.facts };
+        }
         // 只读命令也要排队：与并发的 fetch/checkout 交错会让 status/rev-list 读到半更新状态
-        return this.withWorkdir(() => this.inspectWorkDirLocked(opts));
+        const facts = await this.withWorkdir(() => this.inspectWorkDirLocked(opts), { readonly: true });
+        const prev = inspectFactsCache.get(key);
+        if (detail || prev === undefined || !prev.detail) {
+            inspectFactsCache.set(key, { at: Date.now(), detail, facts });
+        }
+        return { ...facts };
     }
     async inspectWorkDirLocked(opts = {}) {
         const fsx = createSnapshotFs();
@@ -770,9 +819,13 @@ export class GitTransport {
                     throw new GitTransportError(this.hostKeyMessage(), { kind: 'auth', retryable: false });
                 }
                 // 推送 + 鉴权失败：git 原文只说「认证失败」——换成能照做的说明（令牌失效 / 无写权限 / 远端禁用了密码推送）
+                // issue #115：clone 的鉴权失败原文（remote: Write access to repository not granted / 403）读不出「缺哪种权限」，
+                // 换成点名 Contents: Read and write 的说明 —— 否则用户只会以为令牌坏了（细粒度 PAT 常只勾了 Administration）
                 const message = opts.requirePushToken === true && classified.kind === 'auth'
                     ? this.msg('sync.git.pushAuthFailed', { err: this.mask(result.stderr, token) })
-                    : this.msg('sync.git.cmdFailed', { args: args.join(' '), code: String(result.code), err: this.mask(result.stderr, token) });
+                    : args[0] === 'clone' && classified.kind === 'auth'
+                        ? this.msg('sync.git.cloneAuthFailed', { err: this.mask(result.stderr, token) })
+                        : this.msg('sync.git.cmdFailed', { args: args.join(' '), code: String(result.code), err: this.mask(result.stderr, token) });
                 throw new GitTransportError(message, classified);
             }
             return result;

package/lib/sync/messages.d.ts

@@ -66,6 +66,8 @@ export declare const zh: {
     readonly 'sync.webdav.collectionCreateFailed': '创建远端目录失败（HTTP {status}）：{path}';
     readonly 'sync.deviceNameFallback': '未命名设备';
     readonly 'sync.git.probeOk': '连接正常（远端可达、凭据可用）';
+    readonly 'sync.git.probeReadOnlyHint': '只验证了「能读」：推送还需要写权限（细粒度 PAT 的 Contents: Read and write；SSH 部署密钥需勾 Allow write access）。';
+    readonly 'sync.git.cloneAuthFailed': '读不到这个仓库（HTTP 401/403）：当前凭据对它没有读权限。细粒度 PAT 只勾 Administration 不够，必须勾 Contents: Read and write；classic PAT 需要 repo 域。';
 };
 export declare const en: Record<keyof typeof zh, string>;
 /** 本域活翻译器（与 core 的 engineMsg 同一实现；导入本模块即完成目录注册）。 */

package/lib/sync/messages.js

@@ -96,6 +96,8 @@ export const zh = {
     'sync.deviceNameFallback': '未命名设备',
     // ---------- git 通道连通性探针（cloud-sync 借鉴项 ②，补齐四通道） ----------
     'sync.git.probeOk': '连接正常（远端可达、凭据可用）',
+    'sync.git.probeReadOnlyHint': '只验证了「能读」：推送还需要写权限（细粒度 PAT 的 Contents: Read and write；SSH 部署密钥需勾 Allow write access）。',
+    'sync.git.cloneAuthFailed': '读不到这个仓库（HTTP 401/403）：当前凭据对它没有读权限。细粒度 PAT 只勾 Administration 不够，必须勾 Contents: Read and write；classic PAT 需要 repo 域。'
 };
 export const en = {
     'sync.ancestorSnapshotIdRequired': 'loadAncestor: snapshotId must not be empty',
@@ -164,6 +166,8 @@ export const en = {
     'sync.webdav.collectionCreateFailed': 'Failed to create the remote directory (HTTP {status}): {path}',
     'sync.deviceNameFallback': 'Unnamed device',
     'sync.git.probeOk': 'Connection OK (remote reachable, credentials accepted)',
+    'sync.git.probeReadOnlyHint': 'Only read access was verified: pushing also needs write access (Contents: Read and write for a fine-grained PAT; Allow write access for an SSH deploy key).',
+    'sync.git.cloneAuthFailed': 'Cannot read this repository (HTTP 401/403): the current credential has no read access to it. A fine-grained PAT needs Contents: Read and write — Administration alone is not enough; a classic PAT needs the repo scope.'
 };
 registerMessageCatalog({ id: 'sync-domain', zh, en });
 /** 本域活翻译器（与 core 的 engineMsg 同一实现；导入本模块即完成目录注册）。 */

package/lib/sync/sync-engine.d.ts

@@ -198,6 +198,7 @@ export interface SyncPreviewResult {
      */
     credentials?: Map<string, string>;
     message?: string;
+    reason?: 'remote-empty';
 }
 /** 自动应用执行器（P2b）报告 */
 export interface ApplyReport {
@@ -300,8 +301,7 @@ export interface MergePreview {
     /** 是否拿到了本地祖先副本（false = 退化为两方合并 → 所有双侧差异都会呈现为 conflict）。 */
     hasAncestor: boolean;
     sections: MergePreviewSectionView[];
-    /** 与 risk.ts 的 classifyMergePlan 同口径计数：
-     *  auto = 可自动应用的非冲突项，review = 需人工，conflicts = decision === 'conflict'，skipped = 'skip'。 */
+    /** 与 risk.ts 的 classifyMergePlan 同口径计数：auto = 可自动应用，review = 需人工，conflicts = 冲突，skipped = 跳过。 */
     summary: {
         auto: number;
         review: number;
@@ -309,6 +309,7 @@ export interface MergePreview {
         skipped: number;
     };
     message?: string;
+    reason?: 'remote-empty';
 }
 /**
  * 用户对**单个分区**的裁决（分区粒度：没有冲突项粒度 / 复合 id）。
@@ -607,8 +608,7 @@ export declare class SyncEngine {
     hasLocalChanges(): Promise<boolean>;
     /**
      * 一键同步预览：拉取远端（最新或指定历史快照）→ 转临时 ZIP → Importer 分析出计划。
-     * 与 pull 的区别：临时 ZIP **不清理**（由调用方 / 会话持有，供 apply-items 复用），
-     * 并返回完整 plan/analysis/snapshotId 供会话登记。
+     * 与 pull 的区别：临时 ZIP **不清理**（由调用方 / 会话持有，供 apply-items 复用），并返回完整 plan/analysis/snapshotId 供会话登记。
      * 调用方负责在会话消费或取消后清理 zipPath 所在目录。
      */
     preview(opts?: SyncPullOptions): Promise<SyncPreviewResult>;

package/lib/sync/sync-engine.js

@@ -1064,8 +1064,7 @@ export class SyncEngine {
     }
     /**
      * 一键同步预览：拉取远端（最新或指定历史快照）→ 转临时 ZIP → Importer 分析出计划。
-     * 与 pull 的区别：临时 ZIP **不清理**（由调用方 / 会话持有，供 apply-items 复用），
-     * 并返回完整 plan/analysis/snapshotId 供会话登记。
+     * 与 pull 的区别：临时 ZIP **不清理**（由调用方 / 会话持有，供 apply-items 复用），并返回完整 plan/analysis/snapshotId 供会话登记。
      * 调用方负责在会话消费或取消后清理 zipPath 所在目录。
      */
     async preview(opts = {}) {
@@ -1074,7 +1073,7 @@ export class SyncEngine {
         }
         const metas = await this.transport.list();
         if (metas.length === 0) {
-            return { ok: false, zipPath: '', plan: null, analysis: null, snapshotId: '', message: this.msg('sync.remoteEmpty') };
+            return { ok: false, zipPath: '', plan: null, analysis: null, snapshotId: '', message: this.msg('sync.remoteEmpty'), reason: 'remote-empty' };
         }
         const targetId = opts.snapshotId ?? metas[metas.length - 1].id;
         const snapshot = await this.transport.download(targetId);
@@ -1213,7 +1212,7 @@ export class SyncEngine {
         const snapshotId = this.lastMergedRemoteSnapshotId;
         if (snapshotId === null) {
             // merge() 已清掉全部缓存；这里如实报「远端无快照」（ok:false，而不是一个空成功）
-            return { ok: false, snapshotId: '', hasAncestor: false, sections: [], summary, message: this.msg('sync.remoteEmpty') };
+            return { ok: false, snapshotId: '', hasAncestor: false, sections: [], summary, reason: 'remote-empty', message: this.msg('sync.remoteEmpty') };
         }
         const split = classifyMergePlan(plan, { firstSync: false });
         summary.auto = split.autoApply.length;