dsh-config-manager 0.1.85 → 0.2.0

package/lib/core/path-browse.js

@@ -0,0 +1,134 @@
+/**
+ * 本机目录列举（宿主半）—— 「路径映射 → 选择本机路径」弹窗的唯一数据源。
+ *
+ * 为什么要有它
+ * ------------
+ * 导入向导的路径映射要求用户为一堆**绝对路径**指定本机新位置，而此前只能凭记忆手打
+ * （浏览器拿不到真实路径：File System Access API 只给 handle，`<input type="file">` 只给文件名）。
+ * 于是「路径选不对 = 导不进」全落在用户的打字准确性上。这里把「列目录」做成宿主能力，
+ * 浏览器只负责画界面。
+ *
+ * 边界
+ * ----
+ * - **只读**：只 readdir/stat，绝不创建、改写、删除任何东西；
+ * - **不产出文案**：`error` 是枚举码（not-found / denied / failed / not-absolute），
+ *   用户可见句子由客户端按字典解析（i18n 硬规则：引擎不写中文）；
+ * - 有界：单次列举最多 {@link BROWSE_ENTRY_LIMIT} 条并回报 `truncated`，盘符探测逐根带硬超时
+ *   （离线光驱/断开的网络盘 stat 会挂住，路由不许被一个 panic 盘符拖死）。
+ */
+import { readdir, stat } from 'node:fs/promises';
+import { dirname, join, parse } from 'node:path';
+import { homedir } from 'node:os';
+/** 单次列举上限：够翻一个源码目录，又不至于把响应体撑成几 MB。 */
+export const BROWSE_ENTRY_LIMIT = 500;
+/** 盘符/根探测的单项硬超时（ms）：断开的网络盘 stat 会长时间不返回。 */
+export const ROOT_PROBE_TIMEOUT_MS = 400;
+/** 带硬超时的 Promise（只为本模块的盘符探测服务；超时后原 promise 的迟到结果被丢弃）。 */
+function withDeadline(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { reject(new Error('timeout')); }, ms);
+        promise.then((value) => { clearTimeout(timer); resolve(value); }, (error) => { clearTimeout(timer); reject(error); });
+    });
+}
+/** 一个路径是不是「根」（Windows 盘符根 / POSIX 的 `/`）。 */
+function isRoot(target) {
+    return parse(target).root === target;
+}
+/**
+ * 本机根列表：Windows 上是**探测得到的**盘符根（不硬编码 C:），其余平台是 `/`。
+ * 探测逐根 400ms 超时；全部失败时至少给出 `parse(process.cwd()).root`，界面不至于空成白板。
+ */
+export async function listRoots() {
+    if (process.platform !== 'win32') {
+        return [{ name: '/', path: '/', kind: 'dir' }];
+    }
+    const letters = 'CDEFGHIJKLMNOPQRSTUVWXYZAB'.split('');
+    const probed = await Promise.all(letters.map(async (letter) => {
+        const root = `${letter}:\\`;
+        try {
+            const info = await withDeadline(stat(root), ROOT_PROBE_TIMEOUT_MS);
+            return info.isDirectory() ? root : null;
+        }
+        catch {
+            return null;
+        }
+    }));
+    const roots = probed.filter((root) => root !== null);
+    const fallback = parse(process.cwd()).root;
+    const ordered = roots.length > 0 ? roots : (fallback === '' ? [] : [fallback]);
+    return ordered.map((root) => ({ name: root, path: root, kind: 'dir' }));
+}
+/** 文件系统错误 → 原因码（只有 ENOENT 才叫「不存在」）。 */
+function errorCodeOf(error) {
+    const code = error?.code;
+    if (code === 'ENOENT' || code === 'ENOTDIR')
+        return 'not-found';
+    if (code === 'EACCES' || code === 'EPERM')
+        return 'denied';
+    return 'failed';
+}
+/** 名字排序：目录在前、同类按名字字典序（不依赖 locale，测试可复现）。 */
+function compareEntries(a, b) {
+    if (a.kind !== b.kind)
+        return a.kind === 'dir' ? -1 : 1;
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+}
+/**
+ * 列出一个目录（缺省 = 根列表）。
+ *
+ * `target` 缺省或空串 = 根列表；凡不是绝对路径一律 `not-absolute`（不猜基准目录 —— 猜错就列出别人的东西）。
+ * @param options.limit 覆盖 {@link BROWSE_ENTRY_LIMIT}。
+ */
+export async function browseDirectory(target, options) {
+    const limit = Math.max(1, Math.trunc(options?.limit ?? BROWSE_ENTRY_LIMIT));
+    const home = homedir();
+    const wanted = (target ?? '').trim();
+    if (wanted === '') {
+        const roots = await listRoots();
+        return { path: '', parent: null, home, entries: roots.slice(0, limit), truncated: roots.length > limit, error: null };
+    }
+    if (!parse(wanted).root) {
+        return { path: wanted, parent: null, home, entries: [], truncated: false, error: 'not-absolute' };
+    }
+    const current = parse(wanted).root === wanted ? wanted : wanted.replace(/[\\/]+$/, '');
+    let dirents;
+    try {
+        dirents = await readdir(current, { withFileTypes: true });
+    }
+    catch (error) {
+        return { path: current, parent: isRoot(current) ? null : dirname(current), home, entries: [], truncated: false, error: errorCodeOf(error) };
+    }
+    const entries = [];
+    for (const dirent of dirents) {
+        const entryPath = join(current, dirent.name);
+        if (dirent.isDirectory()) {
+            entries.push({ name: dirent.name, path: entryPath, kind: 'dir' });
+            continue;
+        }
+        if (dirent.isFile()) {
+            entries.push({ name: dirent.name, path: entryPath, kind: 'file' });
+            continue;
+        }
+        // 符号链接 / junction / 其它特殊项：跟随一次（读不到就整条丢掉，绝不猜类型）
+        try {
+            const info = await stat(entryPath);
+            if (info.isDirectory())
+                entries.push({ name: dirent.name, path: entryPath, kind: 'dir' });
+            else if (info.isFile())
+                entries.push({ name: dirent.name, path: entryPath, kind: 'file' });
+        }
+        catch {
+            // 断链：不展示（点了也进不去）
+        }
+    }
+    entries.sort(compareEntries);
+    return {
+        path: current,
+        parent: isRoot(current) ? null : dirname(current),
+        home,
+        entries: entries.slice(0, limit),
+        truncated: entries.length > limit,
+        error: null,
+    };
+}
+//# sourceMappingURL=path-browse.js.map

package/lib/foreign/claude-sessions.d.ts

@@ -37,7 +37,7 @@
  *  ③ **sessionId 不一致**：`input.recordSessionId` 存在且 ≠ `input.id` → 非致命发现
  *     `session-id-mismatch`（会话 id 仍以文件名 stem 为准，见 `TranscodeResult.findings`）。
  *  ④ **推理块**（Claude Code 的 `thinking` / `redacted_thinking`）：共享 IR 没有 reasoning
- *     承载位（docs/spec/known-gaps.md F-01）→ 计报 `thinking`，**绝不伪装成正文**；非 Claude 原生的
+ *     承载位（docs/maintenance/known-gaps.md F-01）→ 计报 `thinking`，**绝不伪装成正文**；非 Claude 原生的
  *     `{type:'reasoning',text:…}` 刻意保持既有口径（理由与切换方式见 `REASONING_BLOCK_TYPES`）。
  */
 import type { Stats } from 'node:fs';

package/lib/foreign/claude-sessions.js

@@ -28,7 +28,7 @@ function usageField(usage, key) {
  * 沿「对象带 text 才算文本」的兜底把它变成一个**空文本块** —— 内容静默丢失，且那个空块还会多插入
  * 一个换行。本仓其余 20+ 来源一律「推理不伪装成正文、只计数」（read-crush / read-opencode /
  * read-qwen / read-pi / read-openclaw …），这里对齐同一口径；共享 IR 无 reasoning 承载位这件事
- * 记在 docs/spec/known-gaps.md 的 F-01。
+ * 记在 docs/maintenance/known-gaps.md 的 F-01。
  *
  * **为什么不把 `{type:'reasoning', text:'…'}` 一并纳入**（如实记明，别当成漏掉）：
  *  ① Claude Code 不写这种块（它是别的导出器的归一命名，各来源自己的解析器已各自计报）；

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.85";
+export declare const PLUGIN_VERSION = "0.2.0";
 /**
  * Star 引导弹窗指向的 GitHub 仓库（用户引导点 Star 的目标）。
  * 与 package.json 的 repository 字段保持一致；界面不可改（硬编码，参照
@@ -130,7 +130,7 @@ export interface Config {
 /**
  * 本文件保留的 7 条路由的路径（被源码级守卫按文件窗口钉住，见下方 routesList 注释）。
  *
- * 其余 75 条路由的路径**声明在各自的组文件里**（src/routes/*.ts 的 endpoint({ path, methods })）——
+ * 其余 76 条路由的路径**声明在各自的组文件里**（src/routes/*.ts 的 endpoint({ path, methods })）——
  * 新增一条 API 只需那一条声明，不再有「常量表 + 路由对象」两处要同步。
  */
 export declare const API: {

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.85';
+export const PLUGIN_VERSION = '0.2.0';
 /** Plugin own package name — excluded from its own exported plugins list. */
 const PLUGIN_NAME = 'dsh-config-manager';
 /**
@@ -158,7 +158,7 @@ export const DEFAULT_GITHUB_CLIENT_ID = 'Ov23liq4i7n8UsylGRfb';
 /**
  * 本文件保留的 7 条路由的路径（被源码级守卫按文件窗口钉住，见下方 routesList 注释）。
  *
- * 其余 75 条路由的路径**声明在各自的组文件里**（src/routes/*.ts 的 endpoint({ path, methods })）——
+ * 其余 76 条路由的路径**声明在各自的组文件里**（src/routes/*.ts 的 endpoint({ path, methods })）——
  * 新增一条 API 只需那一条声明，不再有「常量表 + 路由对象」两处要同步。
  */
 export const API = {
@@ -3027,7 +3027,7 @@ function makeRoutes(deps) {
     /**
      * 路由表：本文件只保留被源码级守卫按**文件窗口**钉住的 7 条（host-entry 审计 F-04 记录的
      * tests/host/**、src/core/model-tools.test.ts、src/core/phase1-wiring.test.ts 的窗口断言）。
-     * 其余 75 条已按域拆到 src/routes/*.ts，由 buildRoutes 组装。
+     * 其余 76 条已按域拆到 src/routes/*.ts，由 buildRoutes 组装。
      * 注册顺序不影响匹配：命名路由必须互不相同（webServer 契约）。
      */
     const routeEnv = makeRouteEnv();

package/lib/market/security.js

@@ -102,7 +102,7 @@ export function validateMarketItem(itemId, manifestRaw, zipBytes) {
         if (!enabled)
             continue;
         // 市场条目禁止分区（BANNED_MARKET_SECTIONS：sessions 历史会话 / pluginFiles 任意文件 / self 本地环境）：
-        // 与 secrets 同级硬约束（产品决策 2026-08-19，guide docs/design/2026-08-19-market-repo-setup-guide.md）。
+        // 与 secrets 同级硬约束（产品决策 2026-08-19，guide docs/spec/market-index-v1.md）。
         if (BANNED_MARKET_SECTIONS.includes(sectionId)) {
             return { status: 'invalid', errors: [marketMsg('market.security.bannedSection', { section: sectionId })], warnings, manifest, internalManifest, sections: [], checksumsOk: true };
         }

package/lib/market/types.d.ts

@@ -26,7 +26,7 @@ export type MarketPublishMode = 'migrate' | 'share';
  */
 export declare const MAX_MARKET_ZIP_BYTES: number;
 /**
- * 市场条目禁止携带的分区（产品决策 2026-08-19，guide docs/design/2026-08-19-market-repo-setup-guide.md）：
+ * 市场条目禁止携带的分区（产品决策 2026-08-19，guide docs/spec/market-index-v1.md）：
  *  - sessions：历史会话，含个人交互记录/上下文；
  *  - pluginFiles：任意文件直通（目录放啥带啥），无内容过滤，最易泄漏 token/密钥文件；
  *  - self：本地环境专属（sync 通道 URL / WebDAV 地址 / 市场配置 / UI 偏好），无分享价值且泄漏环境信息。

package/lib/market/types.js

@@ -8,7 +8,7 @@ export const MARKET_ITEM_SCHEMA_VERSION = 1;
  */
 export const MAX_MARKET_ZIP_BYTES = 64 * 1024 * 1024;
 /**
- * 市场条目禁止携带的分区（产品决策 2026-08-19，guide docs/design/2026-08-19-market-repo-setup-guide.md）：
+ * 市场条目禁止携带的分区（产品决策 2026-08-19，guide docs/spec/market-index-v1.md）：
  *  - sessions：历史会话，含个人交互记录/上下文；
  *  - pluginFiles：任意文件直通（目录放啥带啥），无内容过滤，最易泄漏 token/密钥文件；
  *  - self：本地环境专属（sync 通道 URL / WebDAV 地址 / 市场配置 / UI 偏好），无分享价值且泄漏环境信息。

package/lib/routes/index.d.ts

@@ -3,7 +3,7 @@
  *
  * 顺序对匹配无影响：DSH webServer 的契约是「命名路由必须互不相同，注册顺序不影响请求」
  * （见 @deepseek-ai/dsh-host-webserver 的 WebServer 文档）。src/index.ts 保留的 7 条被源码级
- * 守卫按文件窗口钉住，其余 75 条在这里组装。
+ * 守卫按文件窗口钉住，其余 76 条在这里组装（总数 83：含 path-browse）。
  */
 import type { WebRoute } from './kit.ts';
 import type { RoutesEnv } from './context.ts';

package/lib/routes/index.js

@@ -11,6 +11,7 @@ import { meRoutes } from './me.js';
 import { historyRoutes } from './history.js';
 import { recoveryRoutes } from './recovery.js';
 import { sessionExportRoutes } from './session-export.js';
+import { pathBrowseRoutes } from './path-browse.js';
 export function buildRoutes(env) {
     return [
         ...importRoutes(env),
@@ -26,6 +27,7 @@ export function buildRoutes(env) {
         ...historyRoutes(env),
         ...recoveryRoutes(env),
         ...sessionExportRoutes(env),
+        ...pathBrowseRoutes(env),
     ];
 }
 //# sourceMappingURL=index.js.map

package/lib/routes/kit.d.ts

@@ -8,8 +8,8 @@
  * - 「每条路由首行 guard」这条安全不变量此前**只写在注释里**，零测试覆盖；
  * - 3 条 prefix 路由自造围栏（裸 isLoopbackRequest + 自判方法）。
  *
- * 计数口径（三路一致 = 82，勿再照抄旧审计初稿的计数 —— 那是计数口径 overcount）：
- *   路由快照 82 条 ＝ 现行 `endpoint()` 声明 82 条 ＝ 运行期 `buildRoutes()` 75 条 + `src/index.ts` 保留的 7 条。
+ * 计数口径（三路一致 = 83，勿再照抄旧审计初稿的计数 —— 那是计数口径 overcount）：
+ *   路由快照 83 条 ＝ 现行 `endpoint()` 声明 83 条 ＝ 运行期 `buildRoutes()` 76 条 + `src/index.ts` 保留的 7 条。
  * 增删路由后必须同步这段计数、`src/routes/index.ts` 的头注释与 parity 快照清单；`tests/route/route-parity.test.ts`
  * 的「路由计数散文」守卫会拿真实声明数逐条对账（写错即红灯）。
  *

package/lib/routes/path-browse.d.ts

@@ -0,0 +1,3 @@
+import type { WebRoute } from './kit.ts';
+import type { RoutesEnv } from './context.ts';
+export declare function pathBrowseRoutes(_env: RoutesEnv): WebRoute[];

package/lib/routes/path-browse.js

@@ -0,0 +1,63 @@
+/**
+ * 路由组：本机路径浏览（导入向导「路径映射」→ 选择本机路径弹窗的唯一数据源）。
+ *
+ * 为什么需要一条宿主路由：浏览器拿不到用户机器的真实目录树（File System Access API 只给 handle、
+ * `<input type="file">` 只给文件名），而路径映射要求为一堆绝对路径逐个指定本机新位置。
+ * 没有这条路由，用户只能凭记忆手打，打错就是「导不进」。
+ *
+ * 语义与边界
+ * ----------
+ * - **只读**：readdir/stat，绝不创建/改写/删除；不读文件内容；
+ * - POST 形态只**弹系统对话框**（core/native-path-picker.ts），同样不碰盘面；不可用时回
+ *   `reason:'unsupported'|'failed'`，客户端回落 GET 的内置浏览器 —— 对话框不是用户的操作死路；
+ * - 空 `path` = 「此电脑」根列表（Windows 盘符探测，见 core/path-browse.ts）；
+ * - 失败用枚举码回报（`error: 'not-found'|'denied'|'failed'|'not-absolute'`，成功为 null），
+ *   用户可见句子由客户端按字典解析 —— 引擎不写中文；
+ * - 有界：单次列举 500 条上限 + truncated 标记；整体套 withTimeout，不让一个 panic 盘符拖住请求。
+ */
+import { endpoint, errorMessage, queryParam, readJsonBody, writeJson } from './kit.js';
+import { browseDirectory } from '../core/path-browse.js';
+import { pickNativeDirectory } from '../core/native-path-picker.js';
+import { withTimeout } from './route-support.js';
+/** 单次列举的整体时限：正常目录远快于此；网络盘悬挂时宁可报错也不让请求挂着。 */
+const BROWSE_TIMEOUT_MS = 10_000;
+/** POST 可透传文本的长度上限：只用来当对话框的**起点**与**标题**，都不该是长文本。 */
+const PICK_TEXT_MAX = 512;
+/** 取请求体里的短文本字段：非字符串/空串/超长一律视为未提供（对话框走缺省值，不报错）。 */
+function pickText(body, key) {
+    const value = body?.[key];
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === '' || trimmed.length > PICK_TEXT_MAX ? undefined : trimmed;
+}
+export function pathBrowseRoutes(_env) {
+    return [
+        // ---------------------------------------------------- path-browse
+        // GET  ?path=<绝对路径>：列一层目录（目录在前）。path 缺省 = 根列表。
+        // POST { startPath?, title? }：弹**系统原生**目录选择器（Windows IFileOpenDialog / macOS
+        //      choose folder / Linux zenity·kdialog）。回 `{ ok:false, reason:'unsupported'|'failed' }`
+        //      时客户端回落到 GET 的内置浏览器 —— 同一条路径承载两种能力，避免为一个对话框新开一条路由。
+        //      标题由客户端按当前语言传进来（引擎不产中文）。
+        endpoint({ path: '/api/dsh-config-manager/path-browse', methods: ['GET', 'POST'] }, async (req, res) => {
+            if (req.method === 'POST') {
+                // 用户可能在系统对话框里逛几分钟 —— 时限由 core 的口子兜（10 分钟），此处不再叠加。
+                const body = await readJsonBody(req);
+                writeJson(res, 200, await pickNativeDirectory({
+                    startPath: pickText(body, 'startPath'),
+                    title: pickText(body, 'title'),
+                }));
+                return;
+            }
+            const url = new URL(req.url ?? '/', 'http://localhost');
+            try {
+                const result = await withTimeout(browseDirectory(queryParam(url, 'path')), BROWSE_TIMEOUT_MS, 'path browse timed out');
+                writeJson(res, 200, result);
+            }
+            catch (error) {
+                writeJson(res, 500, { error: errorMessage(error) });
+            }
+        }),
+    ];
+}
+//# sourceMappingURL=path-browse.js.map

package/lib/security/secret-scanner.js

@@ -72,7 +72,7 @@ const BEARER_TOKEN_CHARS = '[A-Za-z0-9._~+/=-]';
  * 于是 `bearer credentials are required` / `bearer authentication failed` / `BEARER HEADER NOT SET`
  * 这类纯小写或纯大写的英文词**不命中**；而 `bearer abc12345`、`BEARER AbCdEfGh`、`bearer <24+ 字符>` 命中。
  *
- * 已知残余（登记在 `docs/spec/known-gaps.md` G-36）：scheme 用非规范大小写**且** token 是 8–23 个**纯字母、
+ * 已知残余（登记在 `docs/maintenance/known-gaps.md` G-36）：scheme 用非规范大小写**且** token 是 8–23 个**纯字母、
  * 单一大小写**时本条不命中；规范 `Bearer …` 形态不受此限（上面那条 `bearer-token` 只要求 8+ 字符，行为不变）。
  */
 const BEARER_TOKEN_ANY_CASE = new RegExp(BEARER_SCHEME_ANY_CASE +

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

@@ -53,6 +53,15 @@ const execFileAsync = promisify(execFile);
  */
 const INSPECT_FACTS_TTL_MS = 10_000;
 const inspectFactsCache = new Map();
+/**
+ * 只读自检等锁的上限（2026-10-27）。
+ *
+ * 为什么和写路径不同：写操作本来就该等（一次 push 十几秒是正常的），但自检挂在
+ * `GET /sync/status` 上，同步任务持锁期间它等待是**纯损失** —— 界面要的只是「工作副本有没有跟随
+ * 当前地址」，拿不到锁就如实报忙，让请求有界返回（再退一步还有 10 s 的接口预算兜底）。此前它沿用
+ * 缺省的 300 s：一次自动同步持锁就能让同步页每次打开都白等 10 s（真机 2026-10-27）。
+ */
+const INSPECT_WORKDIR_LOCK_TIMEOUT_MS = 1_500;
 function inspectFactsCacheKey(workDir, repoUrl) {
     return workDir + '\u0000' + repoUrl;
 }
@@ -423,6 +432,8 @@ export class GitTransport {
                 }
             }
             try {
+                // 只读自检传短上限：它挂在状态接口上，等不起一次同步（见 INSPECT_WORKDIR_LOCK_TIMEOUT_MS）；
+                // 写路径不传，沿用缺省的 300 s。
                 return await withWorkdirLock(this.o.workDir, async () => {
                     this.workdirLockDepth += 1;
                     try {
@@ -431,7 +442,7 @@ export class GitTransport {
                     finally {
                         this.workdirLockDepth -= 1;
                     }
-                });
+                }, opts.lockTimeoutMs === undefined ? {} : { timeoutMs: opts.lockTimeoutMs });
             }
             catch (err) {
                 // 等锁超时 = 别人正在同步（另一个 DSH 实例 / 另一个同步任务），不是通道故障：
@@ -543,8 +554,12 @@ export class GitTransport {
         if (hit !== undefined && Date.now() - hit.at < INSPECT_FACTS_TTL_MS && (hit.detail || !detail)) {
             return { ...hit.facts };
         }
-        // 只读命令也要排队：与并发的 fetch/checkout 交错会让 status/rev-list 读到半更新状态
-        const facts = await this.withWorkdir(() => this.inspectWorkDirLocked(opts), { readonly: true });
+        // 只读命令也要排队：与并发的 fetch/checkout 交错会让 status/rev-list 读到半更新状态。
+        // 但排队必须有界（短上限）：拿不到锁就报「工作副本忙」，绝不把状态接口拖进 300 s 的等待。
+        const facts = await this.withWorkdir(() => this.inspectWorkDirLocked(opts), {
+            readonly: true,
+            lockTimeoutMs: INSPECT_WORKDIR_LOCK_TIMEOUT_MS,
+        });
         const prev = inspectFactsCache.get(key);
         if (detail || prev === undefined || !prev.detail) {
             inspectFactsCache.set(key, { at: Date.now(), detail, facts });

package/lib/ui/sync-settings-view.d.ts

@@ -511,4 +511,22 @@ export declare function workdirBacklog(workDir: {
     };
     error?: string;
 } | undefined): WorkdirBacklog;
+/**
+ * 「这一步该按哪个方向」—— 动作行只留一个 primary（issue 115：两个按钮并排、首次使用看不出该按哪个）。
+ *
+ * 判定只用**已确证**的远端事实，没证据就回落下行：一键同步先拉远端再三方合并、逐项确认，
+ * 不会拿本机默认值覆盖远端历史；上行推送才是产生新快照、改写远端历史的那个动作。
+ * 唯一让上行成为 primary 的情形是「远端确证零快照」（git 工作副本自检 remoteSnapshots === 0）：
+ * 此时同步无事可做，用户要的就是第一次备份。判定入口收在本函数里（channel 一并传入），
+ * 组件不用在调用点再判一次通道 —— 判据只有一处。
+ */
+export declare function pickSyncPrimary(statusInfo: {
+    workDir?: {
+        facts?: {
+            ahead?: number | null;
+            remoteSnapshots?: number | null;
+        };
+        error?: string;
+    };
+} | null | undefined, channel: string): 'push' | 'sync';
 export declare function formatSyncUrlPreview(url: string, max?: number): string;

package/lib/ui/sync-settings-view.js

@@ -562,6 +562,26 @@ export function workdirBacklog(workDir) {
         return { kind: 'never-synced', ahead };
     return { kind: 'ahead', ahead, remoteSnapshots };
 }
+/**
+ * 「这一步该按哪个方向」—— 动作行只留一个 primary（issue 115：两个按钮并排、首次使用看不出该按哪个）。
+ *
+ * 判定只用**已确证**的远端事实，没证据就回落下行：一键同步先拉远端再三方合并、逐项确认，
+ * 不会拿本机默认值覆盖远端历史；上行推送才是产生新快照、改写远端历史的那个动作。
+ * 唯一让上行成为 primary 的情形是「远端确证零快照」（git 工作副本自检 remoteSnapshots === 0）：
+ * 此时同步无事可做，用户要的就是第一次备份。判定入口收在本函数里（channel 一并传入），
+ * 组件不用在调用点再判一次通道 —— 判据只有一处。
+ */
+export function pickSyncPrimary(statusInfo, channel) {
+    // 只有 git 通道会做工作副本自检；别的通道没有这份事实，一律回落下行。
+    if (channel !== 'git')
+        return 'sync';
+    const backlog = workdirBacklog(statusInfo?.workDir);
+    if (backlog.kind === 'never-synced')
+        return 'push';
+    if (backlog.kind === 'clean' && backlog.remoteSnapshots === 0)
+        return 'push';
+    return 'sync';
+}
 export function formatSyncUrlPreview(url, max = 60) {
     return url.slice(0, max);
 }

package/lib/utils/workdir-lock.d.ts

@@ -19,7 +19,10 @@
  *  - 锁文件放 `os.tmpdir()`（按工作目录绝对路径哈希命名），**不写进工作副本**：
  *    工作副本还没 clone 出来也能先锁住，且绝不让 `git status` 看到脏文件；
  *  - 跨进程独占用 `open(path,'wx')`（O_EXCL，原子）；等待方轮询，超时抛 WorkdirLockError；
- *  - holder 崩溃留下的陈旧锁按 mtime 回收（超过 staleMs 才回收，避免误抢仍在跑的长时间任务）；
+ *  - holder 崩溃留下的陈旧锁：先问 holder pid 是否还存在（ESRCH ⇒ 已被杀，立即回收），
+ *    读不出 pid 或进程仍存活时才按 mtime 超过 staleMs 回收（避免误抢仍在跑的长时间任务）；
+ *  - 等待方是**有界**的：等文件锁与进程内链上排队共用同一个 timeoutMs 上限，超时即抛，
+ *    绝不在界面早已放弃之后仍去驱动工作副本；
  *  - 进程内再串一条 Promise 链：同进程两个 GitTransport 实例（autosync / 路由）共用同一条链，
  *    不依赖文件锁的轮询延迟。
  */
@@ -47,6 +50,27 @@ export interface WorkdirLockOptions {
 export declare function workdirLockKey(workDir: string): string;
 /** 锁文件路径（导出仅为测试与诊断；不要手工删一把可能被人持有的锁） */
 export declare function workdirLockPath(workDir: string): string;
+/**
+ * holder 进程是否还活着（三态：true = 存活、false = 确定已死、null = 判不了）。
+ *
+ * 为什么必须问：holder 被强杀时（DSH 重启 / 崩溃 / 任务管理器结束进程）`finally` 不会执行，
+ * 锁文件就留在 tmpdir 里；只按 mtime 判定要等满 staleMs（15 分钟）才接管。这段窗口里**所有**
+ * 同步与只读自检都排在锁上 —— 真机 2026-10-27：DSH 重启踩在一次 push 中间，pid 28888 的锁留在
+ * %TEMP%，之后每次打开同步页 `GET /sync/status` 都要等满 10 s 预算再 503。
+ *
+ * 误差方向：只有 `ESRCH`（pid 完全不存在）才判死；`EPERM`（进程存在但无权发信号，如 Linux 跨用户）
+ * 判活；pid 复用也会把「别人的锁」判成活 —— 两种误判都偏向保守（最多退化成 mtime 规则），
+ * 绝不会把仍在跑的 holder 的锁抢走。
+ */
+export declare function workdirLockHolderAlive(pid: unknown): boolean | null;
+/**
+ * 一次性清扫本机所有「holder 已死」的工作副本锁（每进程只跑一次）。
+ *
+ * 为什么需要：pid 回收只在**自己被这把锁挡住时**生效，而残留锁可能属于早已不再使用的工作目录
+ * （换过仓库、换过数据目录、临时实例）—— 它们永远不会再被查询，却一直躺在 %TEMP%（真机 2026-10-27
+ * 见到 8 个，最久 3.4 天）。只删 pid 确定不存在的锁：读不出 holder 的不动（保守，宁可留下）。
+ */
+export declare function pruneDeadWorkdirLocksOnce(): Promise<void>;
 /**
  * 在指定工作副本上串行执行 fn（同一目录的调用排队，跨进程同理）。
  *
@@ -54,5 +78,5 @@ export declare function workdirLockPath(workDir: string): string;
  * 不要在里面再调用会等这把锁的其他工作副本操作 —— 可重入请由调用方用自己的 depth 计数处理。
  */
 export declare function withWorkdirLock<T>(workDir: string, fn: () => Promise<T>, options?: WorkdirLockOptions): Promise<T>;
-/** 仅供测试：清空进程内串行链（不影响磁盘上的锁文件） */
+/** 仅供测试：清空进程内串行链与一次性清扫标记（不影响磁盘上的锁文件） */
 export declare function resetWorkdirLockChainsForTest(): void;