dsh-config-manager 0.2.3 → 0.3.0

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

@@ -7,8 +7,9 @@
  * - 加密快照（EncryptedSections 密文载荷，无法平铺为明文 JSON 分区）走「密文单文件」布局：
  *   整个快照 JSON 提交到 <workDir>/snapshots-encrypted/<id>.json（远端已存密文；
  *   本地工作副本即远端镜像，不产生额外明文审计副本）。
- * - 命令执行走 node:child_process execFile（promise 封装，数组参数无 shell 注入），
- *   始终使用系统 PATH 中的 git（固定命令 'git'），可注入 exec 便于测试。
+ * - 命令执行走 node:child_process spawn（数组参数无 shell 注入、无 maxBuffer 截断错误），
+ *   超时**整棵进程树**一起 kill（issue #122：只 SIGTERM git.exe 会留下 git-remote-https /
+ *   index-pack 孤儿继续下载）；始终使用系统 PATH 中的 git（固定命令 'git'），可注入 exec 便于测试。
  * - 认证：token 仅从注入的 credentials provider 读取（每次网络操作时 getToken()），
  *   经 git credential helper（store --file=<临时文件>）传给 git —— token 不进入 argv、
  *   不进入 repoUrl、不写入任何同步内容/commit message/日志；临时凭据文件用后即删。
@@ -17,15 +18,15 @@
  * - 契约：同 id 重复 upload = 覆盖（幂等友好：内容无变化时不产生 commit）；download 不存在抛错；
  *   delete 不存在视为成功。
  */
-import { execFile } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { promisify } from 'node:util';
 import { createSnapshotFs, joinFs } from '../fs.js';
 import { readSnapshotFromDir, SNAPSHOT_BLOB_REFS_SUFFIX, SNAPSHOT_KEEP_CONTENT, SNAPSHOT_KEEP_FILE, SNAPSHOT_MANIFEST_FILE, writeSnapshotToDir } from '../layout.js';
 import { BLOB_SECTIONS, gcBlobs, referencedBlobHashes } from '../blob-store.js';
 import { deserializeSnapshot, serializeSnapshot } from '../snapshot-json.js';
+import { classifyRepoUrl, isPrivateRepoHost } from '../sync-config.js';
 import { classifyNetworkErrorText, computeSnapshotMeta, DEFAULT_SYNC_TIMEOUT_MS, isEncryptedSections, SyncTransportError, withSyncRetry, } from '../transport.js';
 import { parseJsonSafe } from '../../utils/json.js';
 import { atomicWriteFile } from '../../utils/atomic-write.js';
@@ -35,7 +36,6 @@ import { SECTION_FILE_PREFIXES } from '../../schema/config.js';
 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）。
  *
@@ -97,10 +97,42 @@ const BLOBS_REL = 'blobs';
  * 远端分支的顶层出现别的名字 = 这不是本插件的同步仓库，合并它等于把别人的仓库内容搬进工作副本。
  */
 const ADOPT_ROOT_ALLOW = new Set([SNAPSHOTS_REL, SNAPSHOTS_ENCRYPTED_REL, BLOBS_REL]);
+/**
+ * 同步仓库只在这三个顶层目录里写内容 ⇒ partial clone 的 sparse-checkout 面与它同源（issue #122）。
+ * 远端仓库比同步内容大几个数量级时（报告者现场：1.8 GB 仓库 / 6 MB 内容），全量 clone 与全量 fetch
+ * 都要拉完整对象图，而工作副本真正需要的只有这三个目录。
+ */
+const SYNC_ROOT_DIRS = [...ADOPT_ROOT_ALLOW];
+/**
+ * 走网络的 git 子命令：一律附加低速上限（issue #122）。
+ *
+ * 为什么必须显式设：git 的默认 http 低速门限极宽松，链路被限速/黑洞时一条 fetch 能安静地耗到
+ * timeoutMs（120 s），再乘上重试次数 = 用户看到的就是「永久停在正在检查远端变更」。
+ * 30 s 内平均速率低于 1 KB/s 即明确失败，交给既有分类器判 timeout（瞬时、可重试）。
+ */
+const NETWORK_SUBCOMMANDS = new Set(['clone', 'fetch', 'push', 'ls-remote', 'pull']);
+const LOW_SPEED_ARGS = ['-c', 'http.lowSpeedLimit=1000', '-c', 'http.lowSpeedTime=30'];
+/**
+ * 协议护栏（SEC-12）：**所有** git 子进程恒带，与「这条命令走不走网络」无关。
+ *
+ * 为什么恒带而不是只给网络命令：危险的不只是远端协议本身 —— `ext::sh -c ...` / `file://`
+ * 这类地址在 clone/fetch 之外还能经 `remote set-url`、配置重载等路径被触发，而本插件的 repoUrl
+ * 来自用户可编辑的 sync-config.json 与可导入的配置包。把 `ext` 与 `file` 传输整体关掉，
+ * 就等于「repoUrl 无论被改成什么，都只能走 http/https/ssh 三种真协议」。
+ */
+const PROTOCOL_GUARD_ARGS = ['-c', 'protocol.ext.allow=never'];
+/** 网络仓库额外禁 file 传输（本地目录仓库是显式支持的用法，不能一刀切禁掉）。 */
+const FILE_PROTOCOL_GUARD_ARGS = ['-c', 'protocol.file.allow=never'];
+/** 报错/日志里回显的地址占位符：不带真实 repoUrl（脱敏由上层的 mask() 负责）。 */
+const REPO_URL_PLACEHOLDER = '[REPO_URL]';
 const DEFAULT_AUTHOR = { name: 'DSH Config Sync', email: 'sync@dsh.local' };
 const DEFAULT_CREDENTIAL_USERNAME = 'oauth2';
 /** 快照 id 安全字符集：字母数字开头，仅 . _ -；防路径穿越与 commit message 注入 */
 const SAFE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+/** git 对象 id（sha1 40 位 / sha256 64 位）—— ls-remote 输出与 rev-parse 结果共用同一判定 */
+const SHA_RE = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
+/** 老 git 不认新选项（partial clone 需 ≥2.19、cone sparse-checkout 需 ≥2.25）：据此回落全量 clone */
+const UNSUPPORTED_GIT_OPTION_RE = /unknown option|unrecognized argument|unknown switch|is not a git command|unsupported/i;
 /**
  * SSH 主机密钥校验失败（issue #79）：git 只回一句 `Host key verification failed`，
  * 用户拿不到任何可操作信息（要不要信任？怎么写 known_hosts？）。识别后换成可操作文案。
@@ -112,41 +144,132 @@ const SSH_HOST_KEY_RE = /host key verification failed|remote host identification
  * 这类失败与网络无关，必须给「改回地址或重建工作副本」的出口，而不是只丢一句原始 stderr。
  */
 const DIVERGED_HISTORY_RE = /refusing to merge unrelated histories|unrelated histories|not possible to fast-forward/i;
-const defaultExec = async (cmd, args, opts) => {
+/** 超时 kill 之后等 stdio 关闭的宽限：逃出进程组的孙进程可能一直握着管道（issue #122） */
+const EXEC_KILL_GRACE_MS = 5_000;
+/** 单条命令累计输出上限（与旧 execFile maxBuffer 同口径，超限即 kill） */
+const EXEC_MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
+/**
+ * 默认 git 执行器：spawn + **进程树** kill（issue #122）。
+ *
+ * 为什么不再用 execFile：它的 timeout 只对 git.exe 自己发 SIGTERM，而真正在下包的是 git.exe 的子进程
+ * （git-remote-https / git index-pack）。父进程被杀、孙进程继续写 tmp_pack_*，管道不关闭 ⇒ execFile 的
+ * promise 连超时错误都可能不返回 ⇒ 上层「正在检查远端变更...」永久挂起，下一轮重试再起一份，最终 N 份
+ * 并发下载同一个 pack。
+ * 这里改为：POSIX 上 detached 起独立进程组，超时对**整组**发 SIGKILL；Windows 上 `taskkill /T /F`；
+ * 无论 kill 是否成功，宽限期到点都带着已收集输出收尾 —— 绝不把「管道没关」变成上层无限等待。
+ *
+ * 导出仅供测试直接验证「超时 + 进程树 kill + 有界收尾」（issue #122 的验收面）。
+ */
+export const defaultGitExec = async (cmd, args, opts) => await new Promise((resolve) => {
+    const isWin = process.platform === 'win32';
+    // issue #120：credential helper 走 shell 且本机没有可用 shell 时，改用 env 注入认证头重试 ——
+    // 追加在继承的 process.env 上（env 缺省 = 完全继承，不改变既有行为）
+    const env = opts.env === undefined ? undefined : { ...process.env, ...opts.env };
+    let stdout = '';
+    let stderr = '';
+    let bytes = 0;
+    let settled = false;
+    let timedOut = false;
+    let overflow = false;
+    let timer = null;
+    let graceTimer = null;
+    let child = null;
+    const settle = (code) => {
+        if (settled)
+            return;
+        settled = true;
+        if (timer !== null)
+            clearTimeout(timer);
+        if (graceTimer !== null)
+            clearTimeout(graceTimer);
+        let text = stderr;
+        if (code !== 0) {
+            if (overflow && !/exceed/i.test(text))
+                text = `${text}\noutput exceeded ${String(EXEC_MAX_OUTPUT_BYTES)} bytes`;
+            if (text.trim() === '')
+                text = `git ${args[0] ?? ''} exited with code ${String(code)}`;
+            // 超时在 git 的 stderr 里常常是空的：补一句可判定的文字，让 transport.ts 的统一分类器
+            // 把它识别成 timeout（瞬时、可重试），而不是 unknown。
+            if (timedOut && !/timed out|timeout/i.test(text)) {
+                text = `git command timed out after ${String(opts.timeoutMs ?? 0)}ms: ${text}`;
+            }
+        }
+        resolve({ stdout, stderr: text, code });
+    };
+    const killTree = () => {
+        const pid = child?.pid;
+        if (pid === undefined)
+            return;
+        if (isWin) {
+            // 只 SIGTERM git.exe 会留下 git-remote-https / index-pack 孤儿（issue #122）⇒ 整棵树强杀
+            try {
+                spawn('taskkill', ['/pid', String(pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' })
+                    .on('error', () => { });
+            }
+            catch { /* 同上 */ }
+            return;
+        }
+        try {
+            process.kill(-pid, 'SIGKILL'); // 负 pid = 整个进程组（detached 起的子进程是组长）
+        }
+        catch {
+            try {
+                child?.kill('SIGKILL');
+            }
+            catch { /* 已退出 */ }
+        }
+    };
     try {
-        const { stdout, stderr } = await execFileAsync(cmd, args, {
-            cwd: opts.cwd,
-            timeout: opts.timeoutMs,
-            maxBuffer: 16 * 1024 * 1024,
+        child = spawn(cmd, args, {
+            ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
+            ...(env === undefined ? {} : { env }),
             windowsHide: true,
-            encoding: 'utf8',
-            // issue #120：credential helper 走 shell 且本机没有可用 shell 时，改用 env 注入认证头重试 ——
-            // 追加在继承的 process.env 上（env 缺省 = 完全继承，不改变既有行为）
-            env: opts.env === undefined ? undefined : { ...process.env, ...opts.env },
+            // POSIX：独立进程组，超时才可能连孙进程一起杀；Windows 用 taskkill /T
+            detached: !isWin,
+            stdio: ['ignore', 'pipe', 'pipe'],
         });
-        return { stdout: String(stdout), stderr: String(stderr), code: 0 };
     }
     catch (err) {
-        const e = err;
-        const detail = String(e.stderr ?? '') !== '' ? String(e.stderr) : (err instanceof Error ? err.message : String(err));
-        // 超时（execFile 到点 kill）在 git 的 stderr 里常常是空的：补一句可判定的文字，
-        // 让 transport.ts 的统一分类器把它识别成 timeout（瞬时、可重试），而不是 unknown。
-        const timedOut = e.killed === true || e.signal === 'SIGTERM' || e.code === 'ETIMEDOUT';
-        const stderr = timedOut && !/timed out|timeout/i.test(detail)
-            ? `git command timed out after ${String(opts.timeoutMs ?? 0)}ms: ${detail}`
-            : detail;
-        return {
-            stdout: String(e.stdout ?? ''),
-            stderr,
-            code: typeof e.code === 'number' ? e.code : 1,
-        };
+        resolve({ stdout: '', stderr: err instanceof Error ? err.message : String(err), code: 1 });
+        return;
     }
-};
+    const collect = (sink) => (chunk) => {
+        bytes += chunk.length;
+        if (bytes > EXEC_MAX_OUTPUT_BYTES) {
+            if (!overflow) {
+                overflow = true;
+                killTree();
+            }
+            return;
+        }
+        if (sink === 'out')
+            stdout += chunk.toString('utf8');
+        else
+            stderr += chunk.toString('utf8');
+    };
+    child.stdout?.on('data', collect('out'));
+    child.stderr?.on('data', collect('err'));
+    child.on('error', (err) => {
+        stderr = stderr === '' ? err.message : stderr;
+        settle(1);
+    });
+    child.on('close', (code) => { settle(typeof code === 'number' ? code : 1); });
+    if (opts.timeoutMs !== undefined) {
+        timer = setTimeout(() => {
+            timedOut = true;
+            killTree();
+            // 进程树 kill 之后管道仍可能被握着（逃出进程组的孙进程）⇒ 宽限期到点强制收尾
+            graceTimer = setTimeout(() => { settle(1); }, EXEC_KILL_GRACE_MS);
+        }, Math.max(1, opts.timeoutMs));
+    }
+});
 /** 实现 SyncTransport 的 git 通道。所有操作前 ensureRepo() 保证工作副本就绪，网络命令带凭据。 */
 export class GitTransport {
     type = 'git';
     o;
     repoReady = false;
+    /** 该工作副本是否 partial clone（remote.origin.promisor）；null = 尚未判定（issue #122） */
+    partialClone = null;
     /**
      * 工作副本锁的可重入深度：list/upload/download/delete 都会经 ensureRepo → reconcileOrigin，
      * rebuildWorkDir → adoptRemoteHistory 也各自嵌套；外层入口持锁，内层直接跑。
@@ -161,6 +284,8 @@ export class GitTransport {
      */
     readErrors = [];
     msg;
+    /** repoUrl 是否为网络地址（本地目录仓库 == false）：决定要不要额外禁 file 传输（SEC-12）。 */
+    networkRepo;
     constructor(options) {
         if (typeof options.repoUrl !== 'string' || options.repoUrl.length === 0) {
             throw new GitTransportError(zhMsg('sync.git.repoUrlRequired'));
@@ -173,6 +298,16 @@ export class GitTransport {
             throw new GitTransportError(zhMsg('sync.git.credentialsRequired'));
         }
         this.msg = options.msg ?? zhMsg;
+        // SEC-12：repoUrl 来自用户可编辑配置与可导入配置包 —— 构造期就收成「只能是真网络地址或本地目录」，
+        // 环回/私网/链路本地一律拒（把家目录配置推到 localhost 上的抓取器是最省事的外泄方式）。
+        // **已知行为变更**：局域网 NAS / 内网 git 服务器作为同步目标此后会被拒绝（见 sync-config.ts
+        // 的 isPrivateRepoHost 注释里的取舍说明），这是有意的安全收紧，不是回归。
+        // 地址本体不回显进错误（占位符代替），脱敏仍由 mask() 兜底。
+        const repoShape = classifyRepoUrl(options.repoUrl);
+        if (repoShape === null || (repoShape.kind !== 'local' && isPrivateRepoHost(repoShape.host))) {
+            throw new GitTransportError(this.msg('sync.git.repoUrlInvalid', { url: REPO_URL_PLACEHOLDER }));
+        }
+        this.networkRepo = repoShape.kind !== 'local';
         this.o = {
             repoUrl: options.repoUrl,
             workDir: options.workDir,
@@ -180,7 +315,7 @@ export class GitTransport {
             gitBin: 'git',
             timeoutMs: options.timeoutMs ?? DEFAULT_SYNC_TIMEOUT_MS,
             retry: options.retry ?? {},
-            exec: options.exec ?? defaultExec,
+            exec: options.exec ?? defaultGitExec,
             author: options.author ?? DEFAULT_AUTHOR,
             credentialUsername: options.credentialUsername ?? DEFAULT_CREDENTIAL_USERNAME,
         };
@@ -385,12 +520,12 @@ export class GitTransport {
     async checkIsPrivate() {
         if (this.privateHint !== null)
             return this.privateHint;
-        const anon = await this.runGit(['ls-remote', this.o.repoUrl], { allowNonZero: true, cwd: undefined });
+        const anon = await this.runGit(['ls-remote', '--', this.o.repoUrl], { allowNonZero: true, cwd: undefined });
         if (anon.code === 0) {
             this.privateHint = false;
             return false;
         }
-        const authed = await this.runGit(['ls-remote', this.o.repoUrl], { allowNonZero: true, cwd: undefined, withCredential: true });
+        const authed = await this.runGit(['ls-remote', '--', this.o.repoUrl], { allowNonZero: true, cwd: undefined, withCredential: true });
         if (authed.code === 0) {
             this.privateHint = true;
             return true;
@@ -489,13 +624,93 @@ export class GitTransport {
         await withSyncRetry(async () => {
             if (await fsx.exists(gitDir))
                 return;
-            await this.runGit(['clone', this.o.repoUrl, '.'], { cwd: this.o.workDir, withCredential: true });
+            await this.cloneIntoWorkDir();
         }, this.o.retry);
         // 仓库级提交身份（写入远端历史，可经 author 选项覆盖；不改全局配置）
         await this.runGit(['config', 'user.name', this.o.author.name]);
         await this.runGit(['config', 'user.email', this.o.author.email]);
         this.repoReady = true;
     }
+    /**
+     * 首次 clone（issue #122）：partial clone + sparse-checkout，只落地同步内容。
+     *
+     * 为什么：同步仓库可能比同步内容大几个数量级（报告者现场 1.8 GB 仓库 / 6 MB 内容）。此前 `git clone`
+     * 全量落地，之后每次 fetch 还要拉完整对象图 ⇒ 一次「检查远端变更」就下几百 MB。
+     * `--filter=blob:none` 只取 commit+tree，`--no-checkout` 先不落地任何文件，
+     * `sparse-checkout set --cone <三个目录>` 之后 checkout 只 materialize 这三个目录的 blob。
+     *
+     * 老 git 不认这些选项（unknown option）时回落全量 clone —— 行为与修复前完全一致，绝不因优化失败。
+     */
+    async cloneIntoWorkDir() {
+        const cwd = this.o.workDir;
+        this.partialClone = null; // reclone 后重新判定（配置可能变）
+        const filteredArgs = ['clone', '--filter=blob:none', '--no-checkout', '--', this.o.repoUrl, '.'];
+        const filtered = await this.runGit(filteredArgs, { cwd, withCredential: true, allowNonZero: true });
+        if (filtered.code !== 0) {
+            if (!UNSUPPORTED_GIT_OPTION_RE.test(filtered.stderr + ' ' + filtered.stdout)) {
+                // 真实失败（网络 / 鉴权 / 超时）：沿用既有分类与文案（含 issue #120 的凭据通道判定）
+                this.raiseGitFailure(filteredArgs, filtered, await this.readTokenOnce(), false);
+            }
+            // 老 git：回落全量 clone（全量 clone 自带 checkout）
+            await clearDirContents(cwd);
+            await this.runGit(['clone', '--', this.o.repoUrl, '.'], { cwd, withCredential: true });
+            return;
+        }
+        const branch = await this.currentBranch();
+        const head = await this.runGit(['rev-parse', '--verify', '--quiet', 'HEAD'], { allowNonZero: true });
+        if (head.code !== 0)
+            return; // 空仓库：没有可 checkout 的树，后续 push 会建分支
+        const target = branch === '' ? 'HEAD' : branch;
+        const sparse = await this.runGit(['sparse-checkout', 'set', '--cone', ...SYNC_ROOT_DIRS], { allowNonZero: true });
+        if (sparse.code !== 0) {
+            // 老 git 没有 cone 模式：宁可全量落地（修复前行为），也不留下一个空工作树
+            await this.runGit(['checkout', target], { allowNonZero: true });
+            return;
+        }
+        // checkout 失败必须可见（空工作树会让上层以为「远端没有快照」）
+        await this.runGit(['checkout', target]);
+    }
+    /**
+     * 该工作副本是不是 partial clone（`remote.origin.promisor=true`）。
+     *
+     * 只有 partial clone 才能给 fetch 加 `--filter=blob:none`：对普通全量副本加过滤会让后续 checkout
+     * 拿到缺失的 blob。存量副本（1.8 GB 那种）因此只受益于 ls-remote 短路与 `--no-tags`，不会被改坏。
+     */
+    async isPartialClone() {
+        if (this.partialClone !== null)
+            return this.partialClone;
+        const res = await this.runGit(['config', '--get', 'remote.origin.promisor'], { allowNonZero: true });
+        this.partialClone = res.code === 0 && res.stdout.trim() === 'true';
+        return this.partialClone;
+    }
+    /** 拉取姿态：partial clone 保持 blob 过滤；同步仓库不需要 tag（issue #122） */
+    async fetchOptionFlags() {
+        const flags = [];
+        if (await this.isPartialClone())
+            flags.push('--filter=blob:none');
+        flags.push('--no-tags');
+        return flags;
+    }
+    /** 远端分支当前的 sha（ls-remote 只取一行 refs）；读不到 → null（短路是优化，失败一律回落正常 fetch） */
+    async lsRemoteBranchSha(branch) {
+        const res = await this.runGit(['ls-remote', '--heads', 'origin', `refs/heads/${branch}`], { withCredential: true, allowNonZero: true });
+        if (res.code !== 0)
+            return null;
+        for (const line of res.stdout.split('\n')) {
+            const [sha, ref] = line.trim().split('\t');
+            if (ref === `refs/heads/${branch}` && sha !== undefined && SHA_RE.test(sha))
+                return sha;
+        }
+        return null;
+    }
+    /** 解析引用指向的 sha；读不到 / 不是 sha → null */
+    async revParseSha(ref) {
+        const res = await this.runGit(['rev-parse', '--verify', '--quiet', ref], { allowNonZero: true });
+        if (res.code !== 0)
+            return null;
+        const sha = res.stdout.trim();
+        return SHA_RE.test(sha) ? sha : null;
+    }
     /**
      * 让工作副本的 origin 与配置的 repoUrl 保持一致（issue #79）。
      *
@@ -508,15 +723,16 @@ export class GitTransport {
         const current = await this.runGit(['remote', 'get-url', 'origin'], { allowNonZero: true });
         const origin = current.code === 0 ? current.stdout.trim() : '';
         if (current.code !== 0) {
-            await this.runGit(['remote', 'add', 'origin', this.o.repoUrl]);
+            await this.runGit(['remote', 'add', 'origin', '--', this.o.repoUrl]);
         }
         else if (origin !== '' && origin !== this.o.repoUrl) {
-            await this.runGit(['remote', 'set-url', 'origin', this.o.repoUrl]);
+            await this.runGit(['remote', 'set-url', 'origin', '--', this.o.repoUrl]);
+            this.partialClone = null; // 换了远端 ⇒ promisor 判定失效（issue #122）
         }
         const push = await this.runGit(['remote', 'get-url', '--push', 'origin'], { allowNonZero: true });
         const pushUrl = push.code === 0 ? push.stdout.trim() : '';
         if (pushUrl !== '' && pushUrl !== this.o.repoUrl) {
-            await this.runGit(['remote', 'set-url', '--push', 'origin', this.o.repoUrl]);
+            await this.runGit(['remote', 'set-url', '--push', 'origin', '--', this.o.repoUrl]);
         }
     }
     /**
@@ -615,8 +831,9 @@ export class GitTransport {
         return {
             path: this.o.workDir,
             exists: true,
-            origin: origin === '' ? null : origin,
-            pushUrl: pushRaw === '' ? null : pushRaw,
+            // RV1-F8：这两个字段会进 GET /sync/status 的响应 → 剥掉可能存在的 userinfo token
+            origin: origin === '' ? null : this.bareUrl(origin),
+            pushUrl: pushRaw === '' ? null : this.bareUrl(pushRaw),
             // 读不出 origin（null）→ 不算 match（状态接口据此提示「工作副本地址未知」）
             match: origin === this.o.repoUrl && (pushRaw === '' || pushRaw === this.o.repoUrl),
             ahead,
@@ -701,7 +918,7 @@ export class GitTransport {
         }
         // fetch 是网络操作（幂等读）→ 允许有限指数退避重试
         await withSyncRetry(async () => {
-            await this.runGit(['fetch', 'origin'], { withCredential: true });
+            await this.runGit(['fetch', ...(await this.fetchOptionFlags()), 'origin'], { withCredential: true });
         }, this.o.retry);
         const remoteRef = `refs/remotes/origin/${branch}`;
         const refRes = await this.runGit(['rev-parse', '--verify', '--quiet', remoteRef], { allowNonZero: true });
@@ -758,6 +975,12 @@ export class GitTransport {
             const branch = await this.currentBranch();
             if (branch === '')
                 return; // detached HEAD：没有 upstream 概念（与原「no tracking information」同姿态跳过）
+            // issue #122：稳态（远端没变）时**连 fetch 都不发**。一次 ls-remote 只回一行 refs（~1 KB），
+            // 而 fetch 即使没有新内容也要协商 refs、且远端仓库远大于同步内容时要遍历完整对象图
+            // （报告者现场：1.8 GB 仓库 / 6 MB 内容 ⇒ 一次「检查远端变更」卡死）。
+            // 跳过条件必须两个同时成立：远端 sha == 本地远端跟踪引用（没有新对象可拉）**且** HEAD == 该 sha
+            // （本地已合并）。只比 refs 就跳过 merge 会漏掉「上次 fetch 成功、merge 没跑完」的副本 ——
+            // 那种副本没有新对象可拉，但必须继续本地 merge。
             // **不再用 `git pull --ff-only`**：它是「fetch 写 FETCH_HEAD + 读 FETCH_HEAD 合并」的两步动作，
             // 并发驱动同一个工作副本时 FETCH_HEAD 会留下多行 for-merge 记录，随后每个 pull 都以
             // `fatal: Cannot fast-forward to multiple branches.` 失败（本机 5 并发实测全败），
@@ -765,13 +988,21 @@ export class GitTransport {
             // 显式 refspec fetch + 显式远端跟踪分支 merge 完全不读 FETCH_HEAD（同样 5 并发实测全成功），
             // 语义与 ff-only pull 一致：能快进就快进，不能快进就报「历史分叉」。
             // 参数与判定在 utils/git-fast-forward.ts（market 侧共用同一份实现）。
-            const fetched = await this.runGit(fastForwardFetchArgs(branch), { withCredential: true, allowNonZero: true });
-            if (fetched.code !== 0) {
-                const combined = fetched.stderr + ' ' + fetched.stdout;
-                // 远端还没有这个分支（全新空仓库 / 分支被改名）→ 与「无 upstream」一样静默跳过
-                if (isMissingRemoteRefError(combined))
-                    return;
-                await this.throwPullFailure(combined, fetched.stderr);
+            const remoteSha = await this.lsRemoteBranchSha(branch);
+            const localSha = await this.revParseSha(`refs/remotes/origin/${branch}`);
+            if (remoteSha !== null && remoteSha === localSha) {
+                if (await this.revParseSha('HEAD') === remoteSha)
+                    return; // 已是最新：零 fetch、零 merge
+            }
+            else {
+                const fetched = await this.runGit(fastForwardFetchArgs(branch, await this.fetchOptionFlags()), { withCredential: true, allowNonZero: true });
+                if (fetched.code !== 0) {
+                    const combined = fetched.stderr + ' ' + fetched.stdout;
+                    // 远端还没有这个分支（全新空仓库 / 分支被改名）→ 与「无 upstream」一样静默跳过
+                    if (isMissingRemoteRefError(combined))
+                        return;
+                    await this.throwPullFailure(combined, fetched.stderr);
+                }
             }
             const merged = await this.runGit(fastForwardMergeArgs(branch), { allowNonZero: true });
             if (merged.code === 0)
@@ -812,6 +1043,12 @@ export class GitTransport {
      */
     async runGit(args, opts = {}) {
         const cwd = opts.cwd === undefined ? this.o.workDir : opts.cwd;
+        // 网络子命令一律带低速上限：真卡住在 30 s 内明确失败，而不是耗满 timeoutMs（issue #122）
+        const networkArgs = NETWORK_SUBCOMMANDS.has(args[0] ?? '') ? [...LOW_SPEED_ARGS] : [];
+        // SEC-12：协议护栏恒带（见 PROTOCOL_GUARD_ARGS）；网络仓库再额外禁 file 传输。
+        const guardArgs = this.networkRepo
+            ? [...PROTOCOL_GUARD_ARGS, ...FILE_PROTOCOL_GUARD_ARGS]
+            : [...PROTOCOL_GUARD_ARGS];
         let extra = [];
         let token = null;
         let cleanup = null;
@@ -831,7 +1068,7 @@ export class GitTransport {
         // 而目录里原本就有别的内容时宁可放弃重试，也绝不删用户文件。
         const cloneTargetWasEmpty = args[0] === 'clone' ? await isEmptyDir(cwd) : false;
         try {
-            let result = await this.o.exec(this.o.gitBin, [...extra, ...args], { cwd, timeoutMs: this.o.timeoutMs });
+            let result = await this.o.exec(this.o.gitBin, [...extra, ...guardArgs, ...networkArgs, ...args], { cwd, timeoutMs: this.o.timeoutMs });
             // issue #120：credential helper 必须经 shell 执行（值里不含空格也一样，git 统一拼成
             // `sh -c 'git <helper> ...'`），而 Android 上 git 二进制的 GIT_SHELL_PATH 指向 App 沙箱里
             // 不存在的 Termux sh；`core.askpass` 又要 exec 权限（Android 10+ 对 targetSdk ≥ 29 禁执行应用
@@ -842,33 +1079,11 @@ export class GitTransport {
                 if (Object.keys(headerEnv).length > 0 && (args[0] !== 'clone' || cloneTargetWasEmpty)) {
                     if (args[0] === 'clone')
                         await clearDirContents(cwd);
-                    result = await this.o.exec(this.o.gitBin, args, { cwd, timeoutMs: this.o.timeoutMs, env: headerEnv });
+                    result = await this.o.exec(this.o.gitBin, [...guardArgs, ...networkArgs, ...args], { cwd, timeoutMs: this.o.timeoutMs, env: headerEnv });
                 }
             }
             if (result.code !== 0 && !opts.allowNonZero) {
-                const combined = result.stderr + ' ' + result.stdout;
-                // 统一分类（超时 / 网络 / 鉴权 / 5xx…）：上层可据 kind / retryable 分流，不必解析 message
-                const classified = classifyNetworkErrorText(combined);
-                // issue #79：SSH 主机密钥校验失败 → 换成「怎么信任该主机」的可操作说明（绝不自动信任）
-                if (SSH_HOST_KEY_RE.test(combined)) {
-                    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）
-                // issue #120：helper 根本没能执行时，「请确认令牌有效」是错误指引（令牌可能是好的）——
-                // 这类失败必须点名平台原因，排在 push/clone 的鉴权文案之前。
-                const credentialBlocked = isCredentialExecFailure(combined);
-                const message = credentialBlocked
-                    ? this.msg('sync.git.credentialHelperBlocked', { err: this.mask(result.stderr, token) })
-                    : opts.requirePushToken === true && classified.kind === 'auth'
-                        ? this.msg('sync.git.pushAuthFailed', { 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) });
-                // 归类同样不能交给原文：`cannot exec ...: No such file or directory` 里的 ENOENT 会被判成
-                // notfound（「仓库不存在」），而真实原因是凭据通道不可用 → 钉成 auth（非瞬时、别重试）。
-                throw new GitTransportError(message, credentialBlocked ? { kind: 'auth', retryable: false } : classified);
+                this.raiseGitFailure(args, result, token, opts.requirePushToken === true);
             }
             return result;
         }
@@ -877,13 +1092,44 @@ export class GitTransport {
                 throw err;
             // 注入的 exec 实现可能直接抛错（默认实现只返回非零 code）——同样归一为带分类的传输层错误
             const detail = err instanceof Error ? err.message : String(err);
-            throw new GitTransportError(this.msg('sync.git.cmdFailed', { args: args.join(' '), code: 'exec', err: this.mask(detail, token) }), { ...classifyNetworkErrorText(detail), cause: err });
+            throw new GitTransportError(
+            // argv 里含 repoUrl 原文（clone/ls-remote/remote set-url -- <url>）→ 必须经 mask 才进文案
+            this.msg('sync.git.cmdFailed', { args: this.mask(args.join(' '), token), code: 'exec', err: this.mask(detail, token) }), { ...classifyNetworkErrorText(detail), cause: err });
         }
         finally {
             if (cleanup)
                 await cleanup();
         }
     }
+    /**
+     * 把「git 退出非零」归一成可操作错误（runGit 与 clone 回落共用同一套文案与分类）。
+     * token 只用于脱敏，绝不进 message。
+     */
+    raiseGitFailure(args, result, token, requirePushToken) {
+        const combined = result.stderr + ' ' + result.stdout;
+        // 统一分类（超时 / 网络 / 鉴权 / 5xx…）：上层可据 kind / retryable 分流，不必解析 message
+        const classified = classifyNetworkErrorText(combined);
+        // issue #79：SSH 主机密钥校验失败 → 换成「怎么信任该主机」的可操作说明（绝不自动信任）
+        if (SSH_HOST_KEY_RE.test(combined)) {
+            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）
+        // issue #120：helper 根本没能执行时，「请确认令牌有效」是错误指引（令牌可能是好的）——
+        // 这类失败必须点名平台原因，排在 push/clone 的鉴权文案之前。
+        const credentialBlocked = isCredentialExecFailure(combined);
+        const message = credentialBlocked
+            ? this.msg('sync.git.credentialHelperBlocked', { err: this.mask(result.stderr, token) })
+            : requirePushToken && classified.kind === 'auth'
+                ? this.msg('sync.git.pushAuthFailed', { 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: this.mask(args.join(' '), token), code: String(result.code), err: this.mask(result.stderr, token) });
+        // 归类同样不能交给原文：`cannot exec ...: No such file or directory` 里的 ENOENT 会被判成
+        // notfound（「仓库不存在」），而真实原因是凭据通道不可用 → 钉成 auth（非瞬时、别重试）。
+        throw new GitTransportError(message, credentialBlocked ? { kind: 'auth', retryable: false } : classified);
+    }
     /**
      * 为网络命令构造 credential helper 参数：
      * 仅 http(s) 远端需要 token；本地路径 / ssh 走 git 原生认证（密钥），不调用 provider。
@@ -927,7 +1173,8 @@ export class GitTransport {
             return u.port ? `${u.hostname}:${u.port}` : u.hostname;
         }
         catch {
-            throw new GitTransportError(this.msg('sync.git.repoUrlInvalid', { url: this.o.repoUrl }));
+            // RV1-F8：回显一律占位符 —— repoUrl 可能带 userinfo token，错误消息会进日志/响应/issue 截图
+            throw new GitTransportError(this.msg('sync.git.repoUrlInvalid', { url: REPO_URL_PLACEHOLDER }));
         }
     }
     /** 读取一次 token（错误消息脱敏用）；非 http(s) 场景返回空 */
@@ -941,6 +1188,30 @@ export class GitTransport {
             return null;
         }
     }
+    /**
+     * 回传体里的地址（工作副本自检的 origin / pushUrl）脱敏：只剥「凭据段」，其余原样保留。
+     *
+     * 为什么不整串换占位符：状态面板要显示「工作副本现在指向哪个远端」，用户靠 host/path 判断是否
+     * 已跟随配置。为什么不一律剥 userinfo：`ssh://git@host` 里的 `git` 是 ssh 登录名（标准写法），
+     * 剥掉会让用户认不出自己的远端 —— 与 validateRepoUrl 的口径保持一致（只有 password 位是凭据）。
+     */
+    bareUrl(url) {
+        try {
+            const parsed = new URL(url);
+            const scheme = parsed.protocol.replace(/:$/, '').toLowerCase();
+            const keepSshUser = scheme === 'ssh' && parsed.password === '';
+            const dirty = parsed.password !== '' || (parsed.username !== '' && !keepSshUser);
+            if (!dirty)
+                return url;
+            parsed.username = '';
+            parsed.password = '';
+            return parsed.toString();
+        }
+        catch {
+            // 解析不了（scp 式 `git@host:path` 或本机路径）：`git@` 是登录名不是凭据，原样返回
+            return url;
+        }
+    }
     /** 错误/日志脱敏：token（原文与 URL 编码两种形态）与 repoUrl 一律替换 */
     mask(text, token) {
         let out = text.split(this.o.repoUrl).join('[REPO_URL]');

package/lib/sync/merge-preview-text.d.ts

@@ -0,0 +1,11 @@
+/** 单侧预览文本上限（2 KiB **字符**预算）：超出截断并追加省略号。 */
+export declare const MERGE_PREVIEW_TEXT_LIMIT = 2048;
+/**
+ * 预览文本统一出口：先 redact（敏感值绝不回传浏览器），再截断到 2 KiB。
+ *
+ * 顺序恒为「先 redact 再截断」：反过来会把跨边界的敏感值切成半个形状，让脱敏匹配不到它
+ * （等于把秘密截一半发出去）。redact 之后的剩余文本已不含秘密形状，截断才安全。
+ */
+export declare function finalizePreviewText(text: string): string;
+/** 把任意冲突侧值转成**可读字符串**；二进制只回传形状与字节数，绝不回传原始值对象。 */
+export declare function previewTextOf(value: unknown): string;