dsh-config-manager 0.2.3 → 0.3.0

package/src/sync/autosync-scheduler.ts

@@ -32,9 +32,11 @@
  *    → engine.applyMergePlan(autoApply) 写入本地
  *  - Phase C: 完整双向 → engine.push() 上传。两处策略：
  *    ① 无冲突且推送被远端推进挡下 → skipped/partial + skipReason='conflict'（等人工）；
- *    ② conflictPolicy='local'（缺省）且本轮有冲突 → **不写本地**，改 engine.push({force:true})
- *       把本机版本推成新的远端最新（被覆盖的远端旧版本仍在远端历史快照里可回滚），
- *       状态记 partial + skipReason='conflict-kept-local'（绝不谎报 success）。
+ *    ② conflictPolicy='local'（**只有用户显式选过才生效**；缺省 ask）且本轮有冲突 → **不写本地**，
+ *       改 engine.push({force:true}) 把本机版本推成新的远端最新（被覆盖的远端旧版本仍在远端历史快照里
+ *       可回滚），状态记 partial + skipReason='conflict-kept-local'（绝不谎报 success）；
+ *       SYN-05：首轮 / 远端有新快照时即使选了 local 也降级 ask 并记 forced=true（见
+ *       resolveConflictPushPolicy）——这两个时刻覆盖远端等于替用户丢数据。
  *  - 收尾：写该通道 autosync-config（lastRunAt, lastRunStatus, consecutiveFailures,
  *    lastRunHistoryId, lastRunMessage/跳过原因 —— 每轮覆盖上一轮，绝不残留旧错误）
  *
@@ -61,10 +63,11 @@ import {
 } from './autosync-config.ts';
 import type { AutosyncConfig, AutosyncInterval } from './autosync-config.ts';
 import { readSyncConfigFor, isGitConfig, isWebDavConfig, isS3Config, isGistConfig, SYNC_CHANNELS } from './sync-config.ts';
-import type { SyncConfig, SyncTransportType } from './sync-config.ts';
+import type { SyncConfig, SyncConfigIssue, SyncTransportType } from './sync-config.ts';
 import { readSyncHistory, appendAutosyncEntry, markAutosyncNotified } from './sync-history.ts';
 import { classifyMergePlan } from './risk.ts';
 import type { AutosyncHistoryEntry } from './sync-history.ts';
+import type { AutosyncConflictPolicy } from './autosync-config.ts';
 import type { MergePlan } from './merge.ts';
 import type { SyncApplyPlan } from './risk.ts';
 import { SyncWatcher } from './sync-watcher.ts';
@@ -111,6 +114,42 @@ export interface AutosyncRunResult {
   error?: string;
   historyId: string;
   consecutiveFailures: number;
+  /**
+   * SYN-05：本轮 ask 是**被强制**的（首轮或远端有新快照），不是用户选的 ask。
+   * 界面据此说清「这次没让你选」，避免用户以为自己的 local 设置失效了。
+   */
+  forced?: boolean;
+  /**
+   * SEC-03：本轮 skipReason='unconfigured' 时，已落盘配置为何被读侧丢弃（地址被白名单拒绝）。
+   * 缺省 undefined = 真的没配。有值就必须让用户看见 —— 否则「保存过却被拒」和
+   * 「从来没配」在界面上长得一模一样，用户会反复重填同一个被拒地址。
+   */
+  configIssue?: string;
+}
+
+/**
+ * SYN-05：本轮冲突（下行冲突）该不该 force push —— 唯一判定点。
+ *
+ * 规则（缺省 ask 之上再加两道高危闸）：
+ *  - 用户没选过策略 → 用缺省（ask）；
+ *  - **首轮**（从未跑过）或**远端有新快照**：即使显式选了 'local' 也强制降级 ask（forcedAsk）——
+ *    这两个时刻正是「远端最新改动只在历史快照里」的事故现场，静默覆盖等于替用户丢数据；
+ *    降级记 forced，界面才能说清「这次没按你的 local 走」；
+ *  - 只有「显式 local + 非高危时刻 + 真有冲突」才 force。
+ *
+ * 纯函数（无状态、无 I/O）：调度层与单测共用同一份判定，避免两处各写一遍阈值。
+ */
+export function resolveConflictPushPolicy(args: {
+  configuredPolicy?: AutosyncConflictPolicy;
+  firstRun: boolean;
+  remoteNew: boolean;
+  conflicted: number;
+}): { policy: AutosyncConflictPolicy; force: boolean; forcedAsk: boolean } {
+  const configured = args.configuredPolicy ?? DEFAULT_AUTOSYNC_CONFLICT_POLICY;
+  // forcedAsk 只描述「用户选了 local，但本轮被降级」——缺省 ask 不算被强制（那不是用户的决定被推翻）。
+  const forcedAsk = configured === 'local' && (args.firstRun || args.remoteNew);
+  const policy: AutosyncConflictPolicy = forcedAsk ? 'ask' : configured;
+  return { policy, force: policy === 'local' && args.conflicted > 0, forcedAsk };
 }
 
 /**
@@ -147,7 +186,11 @@ export interface AutoSyncSchedulerOptions {
   readConfig?: (channel: SyncTransportType) => Promise<AutosyncConfig>;
   writeConfig?: (channel: SyncTransportType, cfg: AutosyncConfig) => Promise<void>;
   /** 注入 sync-config 读取（按通道） */
-  readSyncConfigFn?: (channel: SyncTransportType) => Promise<SyncConfig | null>;
+  /**
+   * SEC-03：可选第二参收集「读侧被丢弃的配置成因」。既有注入实现（单参闭包）依然合法 ——
+   * 少一个参数不是类型错误，缺省接线才负责真正回填。
+   */
+  readSyncConfigFn?: (channel: SyncTransportType, issues?: SyncConfigIssue[]) => Promise<SyncConfig | null>;
   /** 注入 sync-history 读写 */
   readHistoryFn?: () => Promise<Awaited<ReturnType<typeof readSyncHistory>>>;
   appendHistoryFn?: (entry: AutosyncHistoryEntry) => Promise<void>;
@@ -204,7 +247,7 @@ export class AutoSyncScheduler {
   private readonly now: () => Date;
   private readonly readConfig: (channel: SyncTransportType) => Promise<AutosyncConfig>;
   private readonly writeConfig: (channel: SyncTransportType, cfg: AutosyncConfig) => Promise<void>;
-  private readonly readSyncConfigFn: (channel: SyncTransportType) => Promise<SyncConfig | null>;
+  private readonly readSyncConfigFn: (channel: SyncTransportType, issues?: SyncConfigIssue[]) => Promise<SyncConfig | null>;
   private readonly readHistoryFn: () => Promise<Awaited<ReturnType<typeof readSyncHistory>>>;
   private readonly appendHistoryFn: (entry: AutosyncHistoryEntry) => Promise<void>;
   private readonly setTimer: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
@@ -239,6 +282,8 @@ export class AutoSyncScheduler {
   private readonly profile: string | undefined;
   private readonly makeWatcher: ((opts: WatcherFactoryOptions) => SyncWatcher) | undefined;
   private readonly minTriggerGapMs: number;
+  /** SEC-03：已 warn 过的「地址被拒」成因（键 = 通道 + 成因文本），进程内去重。 */
+  private readonly reportedConfigIssues = new Set<string>();
   private stopped = false;
   private running = false;
 
@@ -250,7 +295,7 @@ export class AutoSyncScheduler {
     this.now = opts.now ?? (() => new Date());
     this.readConfig = opts.readConfig ?? ((channel) => readAutosyncConfig(this.syncDir, channel));
     this.writeConfig = opts.writeConfig ?? ((channel, cfg) => writeAutosyncConfig(this.syncDir, channel, cfg));
-    this.readSyncConfigFn = opts.readSyncConfigFn ?? ((channel) => readSyncConfigFor(this.syncDir, channel));
+    this.readSyncConfigFn = opts.readSyncConfigFn ?? ((channel, issues) => readSyncConfigFor(this.syncDir, channel, issues));
     this.readHistoryFn = opts.readHistoryFn ?? (() => readSyncHistory(this.syncDir));
     this.appendHistoryFn = opts.appendHistoryFn ?? ((entry) => appendAutosyncEntry(this.syncDir, entry));
     this.setTimer = opts.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
@@ -266,11 +311,32 @@ export class AutoSyncScheduler {
     this.minTriggerGapMs = opts.minTriggerGapMs ?? 3000;
   }
 
-  /** 追加一条自动同步历史（自动带上触发通道；0x 安全：绝不覆盖调用方显式 transport）。 */
-  private async appendHistory(channel: SyncTransportType, entry: AutosyncHistoryEntry): Promise<void> {
+  /**
+   * 追加一条自动同步历史（自动带上触发通道；0x 安全：绝不覆盖调用方显式 transport）。
+   *
+   * SYN-05：额外允许 forced（本轮 ask 是被强制的）。该字段不在 sync-history.ts 的
+   * AutosyncHistoryEntry 里（那是另一个模块的公开契约，本轮不扩），但读写两侧都按普通对象
+   * 原样透传（readSyncHistory 逐条 cast），所以运行时可稳定往返；界面按「字段有无」渲染。
+   */
+  private async appendHistory(
+    channel: SyncTransportType,
+    entry: AutosyncHistoryEntry & { forced?: boolean; configIssue?: string },
+  ): Promise<void> {
     await this.appendHistoryFn({ ...entry, transport: channel });
   }
 
+  /**
+   * SEC-03：「地址被拒」是持久状态，而自动同步每 interval（缺省 60s）就转一圈 ——
+   * 每轮打一条日志等于把日志刷成噪音。同一 (通道 + 成因) 只 warn 一次。
+   * 用户改了配置后成因文本会变（message 带真实地址/原因），自然再报一次。
+   */
+  private reportConfigIssue(channel: SyncTransportType, detail: string): void {
+    const key = channel + '/' + detail;
+    if (this.reportedConfigIssues.has(key)) return;
+    this.reportedConfigIssues.add(key);
+    this.host.log.warn(`自动同步已跳过（${channel}）：同步通道配置被安全校验拒绝，请重新填写地址（${detail}）`);
+  }
+
   /** 启动：读两个通道配置 → enabled 通道各自排定时器 → 对每个 enabled 通道执行一次启动触发。 */
   start(): void {
     if (this.stopped) return;
@@ -559,11 +625,17 @@ export class AutoSyncScheduler {
 
     try {
       // 读该通道 sync-config：按通道判定「已配置」——git 看 git.repoUrl、webdav 看 webdav.url。
-      const syncCfg = await this.readSyncConfigFn(channel);
+      // SEC-03：「未配置」有两种成因 —— 真的没配，或存过的地址被白名单拒掉（读侧丢弃）。
+      // 必须区分：后者如果说成前者的「尚未配置」，用户会一遍遍重填同一个被拒地址。
+      const configIssues: SyncConfigIssue[] = [];
+      const syncCfg = await this.readSyncConfigFn(channel, configIssues);
       if (!syncIsConfigured(syncCfg)) {
+        const configIssue = describeConfigIssue(configIssues, channel);
+        if (configIssue !== undefined) this.reportConfigIssue(channel, configIssue);
         const result: AutosyncRunResult = {
           status: 'skipped', direction: 'none', skipReason: 'unconfigured', historyId,
           consecutiveFailures: 0,
+          ...(configIssue === undefined ? {} : { configIssue }),
         };
         await this.appendHistory(channel, {
           direction: 'both',
@@ -571,6 +643,7 @@ export class AutoSyncScheduler {
           skipReason: 'unconfigured',
           createdAt: nowIso,
           failureCountAtRun: 0,
+          ...(configIssue === undefined ? {} : { configIssue }),
         });
         await this.writeFinalConfig(cfg, result, nowIso, historyId, channel);
         return result;
@@ -615,6 +688,9 @@ export class AutoSyncScheduler {
       // 列表拿不到（网络失败）时 remoteMetas 为 null → 检测自己再 list 一次，行为与改造前一致
       const remoteNew = await this.detectRemoteNew(engine, remoteMetas ?? undefined);
       const localDirty = await this.detectLocalChange(engine);
+      // SYN-05：首轮（从未跑过）与「远端有新快照」是覆盖风险最高的两个时刻 —— 由
+      // resolveConflictPushPolicy 统一把这两处的 ask 标成 forced。
+      const firstRun = cfg.lastRunAt === undefined || cfg.lastRunAt === '';
 
       // 两端都无变化 → 什么都不做，记为 upToDate（不重复拉取/不空转）。
       if (!remoteNew && !localDirty) {
@@ -722,13 +798,23 @@ export class AutoSyncScheduler {
       if (!opts.startup && localDirty) {
         try {
           /**
-           * 冲突策略（conflictPolicy，缺省 'local'）：
+           * 冲突策略（conflictPolicy，缺省 'ask'）：
            * - 'ask'：不强制，推送会被引擎的「远端已推进」前置检测挡下 → skipped/partial(conflict)；
-           * - 'local'：**不写本地**（下行被冲突挡下），但把本机版本强制推成新的远端最新。
-           *   force 只跳过「基线是否落后」这一道检查，仍走正常快照上传与基线记录；
+           * - 'local'：用户显式选中才生效 —— **不写本地**（下行被冲突挡下），但把本机版本强制推成
+           *   新的远端最新。force 只跳过「基线是否落后」这一道检查，仍走正常快照上传与基线记录；
            *   被覆盖的远端旧版本留在远端历史快照里，可手动回滚。
+           *
+           * SYN-05：首轮 / 远端有新快照时即使显式选了 local 也强制降级 ask（forced=true 进结果与
+           * 历史），绝不在这两个高危时刻替用户覆盖远端最新。
            */
-          const forcePush = conflictedSections.length > 0 && (cfg.conflictPolicy ?? DEFAULT_AUTOSYNC_CONFLICT_POLICY) === 'local';
+          const pushDecision = resolveConflictPushPolicy({
+            ...(cfg.conflictPolicy !== undefined ? { configuredPolicy: cfg.conflictPolicy } : {}),
+            firstRun,
+            remoteNew,
+            conflicted: conflictedSections.length,
+          });
+          const forcePush = pushDecision.force;
+          const forcedMark = pushDecision.forcedAsk ? { forced: true as const } : {};
           // Phase C: 完整双向 → engine.push() 上传。P0-A：外部 push 包 intent journal。
           const rawPush = async () => engine.push(forcePush ? { force: true } : {});
           const pushReport = (this.phase3Recovery !== undefined && this.lockCtxForJournal !== null)
@@ -749,6 +835,7 @@ export class AutoSyncScheduler {
               appliedSections,
               ...(conflictedSections.length > 0 ? { conflictedSections } : {}),
               consecutiveFailures: 0,
+              ...forcedMark,
             };
             await this.appendHistory(channel, {
               direction: appliedSections.length ? 'both' : 'push', status: conflictResult.status,
@@ -756,6 +843,7 @@ export class AutoSyncScheduler {
               appliedSections,
               ...(conflictedSections.length > 0 ? { conflictedSections } : {}),
               createdAt: nowIso, failureCountAtRun: 0,
+              ...forcedMark,
             });
             await this.writeFinalConfig(cfg, conflictResult, nowIso, historyId, channel);
             return conflictResult;
@@ -799,6 +887,7 @@ export class AutoSyncScheduler {
             ...(skipReason !== undefined ? { skipReason } : {}),
             ...(reportedConflicted.length > 0 ? { conflictedSections: reportedConflicted } : {}),
             consecutiveFailures: 0,
+            ...forcedMark,
           };
           await this.appendHistory(channel, {
             direction: appliedSections.length ? 'both' : 'push',
@@ -807,6 +896,7 @@ export class AutoSyncScheduler {
             ...(skipReason !== undefined ? { skipReason } : {}),
             ...(reportedConflicted.length > 0 ? { conflictedSections: reportedConflicted } : {}),
             createdAt: nowIso, failureCountAtRun: 0,
+            ...forcedMark,
           });
           await this.writeFinalConfig(cfg, result, nowIso, historyId, channel);
           return result;
@@ -983,6 +1073,20 @@ export function syncIsConfigured(cfg: SyncConfig | null): boolean {
   return false;
 }
 
+/**
+ * SEC-03：从读侧收集到的 issue 里挑出本通道的成因（`code(channel): message`），
+ * 没有就返回 undefined —— 「真的没配」绝不伪造原因（无幻影告警）。
+ * 多通道并存时只取本通道，git 的拒因不该挂在 webdav 的历史里。
+ */
+export function describeConfigIssue(
+  issues: readonly SyncConfigIssue[],
+  channel: SyncTransportType,
+): string | undefined {
+  const own = issues.filter((issue) => issue.channel === channel);
+  if (own.length === 0) return undefined;
+  return own.map((issue) => `${issue.code} (${issue.channel}): ${issue.message}`).join('; ');
+}
+
 /**
  * 缺省远端新快照检测（§3.2）：engine 实现了 hasNewRemoteSnapshot() → 调用；
  * 否则（测试 mock 未实现）保守返回 true（假设有新生，保持旧行为=每次都尝试拉取）。

package/src/sync/config-issue-reporting.test.ts

@@ -0,0 +1,148 @@
+/**
+ * SEC-03 可见性 + webdav username 回填：下沉模块 `config-issue-reporting.ts` 的行为契约。
+ *
+ * 这里守的两条都是**可见性语义**，不是实现细节：
+ *  1) 「同步配置被拒」的告警按 (通道/码/文案) 去重 —— prepareSync 每个同步请求都跑，
+ *     重复行会把日志刷成噪音；但不同被拒地址的文案不同，必须再报一次。
+ *  2) webdav 请求体没带 username 时从持久化配置回填（留空 = 沿用已保存凭据），
+ *     回填失败（读不到/读坏）保持原值交给下游校验，绝不静默改成别的通道配置。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { createPrepareSync, createSyncConfigIssueReporter } from './config-issue-reporting.ts';
+import { isGitConfig, isWebDavConfig, SYNC_CONFIG_FILE, type SyncConfig, type SyncConfigIssue } from './sync-config.ts';
+
+const issue = (message: string, channel: SyncConfigIssue['channel'] = 'git'): SyncConfigIssue =>
+  ({ code: 'repo-url-invalid', channel, message });
+
+const webdavCfg = (username?: string): SyncConfig => ({
+  schemaVersion: 2,
+  transport: 'webdav',
+  webdav: username === undefined ? { url: 'https://dav.example.com/remote.php/dav' } : { url: 'https://dav.example.com/remote.php/dav', username },
+});
+
+const gitCfg = (repoUrl: string): SyncConfig => ({ schemaVersion: 2, transport: 'git', git: { repoUrl } });
+
+/** 与宿主 `mergePersistedWebDavUsername` 同语义的最小实现（不 import 4400 行的入口模块）。 */
+const mergeStub = (cfg: SyncConfig, persisted: SyncConfig | null): SyncConfig => {
+  if (persisted === null || persisted.transport !== 'webdav' || persisted.schemaVersion !== 2) return cfg;
+  if (cfg.transport !== 'webdav' || cfg.schemaVersion !== 2) return cfg;
+  const saved = persisted.webdav.username;
+  if (saved === undefined || saved === '') return cfg;
+  return { ...cfg, webdav: { ...cfg.webdav, username: saved } };
+};
+
+async function tmpSyncDir(): Promise<string> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dcm-issue-report-'));
+  return dir;
+}
+
+test('SEC-03 报告器：同一 (通道/码/文案) 只输出一次，跨调用累计', () => {
+  const lines: string[] = [];
+  const report = createSyncConfigIssueReporter((line) => lines.push(line));
+  report([issue('private address')]);
+  report([issue('private address')]);
+  report([issue('private address'), issue('private address')]);
+  assert.deepEqual(lines, ['sync config rejected (git/repo-url-invalid): private address']);
+});
+
+test('SEC-03 报告器：不同文案或不同通道各自成一条（新信息不吞）', () => {
+  const lines: string[] = [];
+  const report = createSyncConfigIssueReporter((line) => lines.push(line));
+  report([issue('private address 192.168.1.10'), issue('private address 10.0.0.5')]);
+  report([issue('private address 192.168.1.10', 'webdav')]);
+  assert.equal(lines.length, 3);
+  assert.deepEqual(lines, [
+    'sync config rejected (git/repo-url-invalid): private address 192.168.1.10',
+    'sync config rejected (git/repo-url-invalid): private address 10.0.0.5',
+    'sync config rejected (webdav/repo-url-invalid): private address 192.168.1.10',
+  ]);
+});
+
+test('SEC-03 报告器：空 issues 不产生任何输出（无幻影告警）', () => {
+  const lines: string[] = [];
+  createSyncConfigIssueReporter((line) => lines.push(line))([]);
+  assert.deepEqual(lines, []);
+});
+
+test('prepareSync：webdav 未带 username → 从持久化配置回填（留空 = 沿用已保存凭据）', async () => {
+  const dir = await tmpSyncDir();
+  await fs.writeFile(path.join(dir, SYNC_CONFIG_FILE), JSON.stringify({
+    schemaVersion: 3,
+    transport: 'webdav',
+    webdav: { url: 'https://dav.example.com/remote.php/dav', username: 'saved-user' },
+  }), 'utf8');
+  const lines: string[] = [];
+  const prepareSync = createPrepareSync({
+    syncDir: dir,
+    parseBody: async () => webdavCfg(),
+    mergeWebDavUsername: mergeStub,
+    log: (line) => lines.push(line),
+  });
+  const cfg = await prepareSync({});
+  assert.ok(isWebDavConfig(cfg));
+  assert.equal(cfg.webdav.username, 'saved-user');
+  assert.deepEqual(lines, []);
+});
+
+test('prepareSync：已存 repoUrl 被白名单拒绝 → 日志报成因，且按通道/文案去重（两次调用只一行）', async () => {
+  const dir = await tmpSyncDir();
+  await fs.writeFile(path.join(dir, SYNC_CONFIG_FILE), JSON.stringify({
+    schemaVersion: 3,
+    transport: 'git',
+    git: { repoUrl: 'https://192.168.1.10/owner/repo.git' },
+  }), 'utf8');
+  const lines: string[] = [];
+  const prepareSync = createPrepareSync({
+    syncDir: dir,
+    parseBody: async () => webdavCfg(),
+    mergeWebDavUsername: mergeStub,
+    log: (line) => lines.push(line),
+  });
+  await prepareSync({});
+  await prepareSync({});
+  assert.equal(lines.length, 1, '同一成因重复请求也只能报一次');
+  assert.match(lines[0]!, /^sync config rejected \(git\/repo-url-invalid\): /);
+  assert.match(lines[0]!, /192\.168\.1\.10/);
+});
+
+test('prepareSync：请求体已带 username → 不读盘、不改值（git 通道同样原样返回）', async () => {
+  const dir = await tmpSyncDir();
+  let merged = 0;
+  const prepareSync = createPrepareSync({
+    syncDir: dir,
+    parseBody: async () => webdavCfg('explicit-user'),
+    mergeWebDavUsername: (cfg, persisted) => { merged += 1; return mergeStub(cfg, persisted); },
+    log: () => {},
+  });
+  const cfg = await prepareSync({});
+  assert.ok(isWebDavConfig(cfg));
+  assert.equal(cfg.webdav.username, 'explicit-user');
+  assert.equal(merged, 0);
+
+  const gitPrepare = createPrepareSync({
+    syncDir: dir,
+    parseBody: async () => gitCfg('https://github.com/owner/repo.git'),
+    mergeWebDavUsername: () => { throw new Error('git 通道不该走 webdav 回填'); },
+    log: () => {},
+  });
+  const git = await gitPrepare({});
+  assert.ok(isGitConfig(git));
+  assert.equal(git.git.repoUrl, 'https://github.com/owner/repo.git');
+});
+
+test('prepareSync：持久化配置缺失 → 保持请求体原值（不猜、不改通道）', async () => {
+  const dir = await tmpSyncDir();
+  const prepareSync = createPrepareSync({
+    syncDir: dir,
+    parseBody: async () => webdavCfg(),
+    mergeWebDavUsername: mergeStub,
+    log: () => {},
+  });
+  const cfg = await prepareSync({});
+  assert.deepEqual(cfg, webdavCfg());
+});

package/src/sync/config-issue-reporting.ts

@@ -0,0 +1,75 @@
+/**
+ * 同步请求准备期的两个只读旁路（从宿主壳 `src/index.ts` 下沉，行为逐字保持）。
+ *
+ * 为什么独立成模块：
+ *  1) `prepareSync` 每个同步请求都跑一次（含挂载时 snapshotsList 的自动加载），它的副作用
+ *     （回填 webdav username、把「配置被拒」告警一次）需要自己的单测，而宿主壳本身不可实例化；
+ *  2) 去重语义是**可见性契约**的一部分（同一 (通道/码/文案) 只报一次），写在 4400 行的
+ *     assembly 文件里没人守得住。
+ *
+ * 这两件事共享同一个来源：读已落盘的 sync-config。读出来的产物有两种用途 —— 回填缺失字段、
+ * 报告被读侧丢弃的成因，因此放在同一个模块里，但各自独立导出、独立可测。
+ */
+import { isWebDavConfig, readSyncConfig } from './sync-config.ts';
+import type { SyncConfig, SyncConfigIssue } from './sync-config.ts';
+
+/**
+ * 造一个「配置被拒」报告器：返回的函数幂等 —— 同一 (通道/码/文案) 只输出一行。
+ *
+ * 去重理由：调用方每次同步请求都跑一遍，按请求打日志会被零信息量的重复行刷满；而
+ * 「地址被拒」是**持久状态**，报一次即可。键里带 message 而不只带 code：不同被拒地址的
+ * 成因文案不同，那是新的有用信息，用户改了配置再被拒应当再报一次。
+ *
+ * `log` 由调用方注入（宿主传 `host.log.warn`），本模块不碰日志设施与 i18n 字典。
+ */
+export function createSyncConfigIssueReporter(
+  log: (line: string) => void,
+): (issues: readonly SyncConfigIssue[]) => void {
+  const reported = new Set<string>();
+  return (issues) => {
+    for (const issue of issues) {
+      const key = issue.channel + '/' + issue.code + '/' + issue.message;
+      if (reported.has(key)) continue;
+      reported.add(key);
+      log('sync config rejected (' + issue.channel + '/' + issue.code + '): ' + issue.message);
+    }
+  };
+}
+
+/** `createPrepareSync` 的依赖（全部注入，便于单测与避免与 index.ts 形成循环依赖）。 */
+export interface PrepareSyncOptions {
+  /** 同步配置目录（`sync-config.json` 所在处）。 */
+  syncDir: string;
+  /** 解析请求体（宿主传入带 credentials 的 closure）。 */
+  parseBody: (body: Record<string, unknown>) => Promise<SyncConfig>;
+  /** 把已保存的 webdav username 回填进请求体（宿主传入 `mergePersistedWebDavUsername`）。 */
+  mergeWebDavUsername: (cfg: SyncConfig, persisted: SyncConfig | null) => SyncConfig;
+  /** 告警出口（宿主传 `(line) => host.log.warn(line)`）。 */
+  log: (line: string) => void;
+}
+
+/**
+ * 造 `prepareSync`：解析请求体，webdav 请求体未带 username 时从持久化配置回填 ——
+ * 否则 WebDavTransport 构造会因空 username 抛错，导致「保存过配置仍无法列出快照」。
+ * 语义与 password 一致：留空 = 沿用已保存凭据。
+ *
+ * SEC-03：顺带把「已落盘但过不了白名单、被读取侧丢弃」的 repoUrl 成因报一次；界面侧的
+ * 权威出口是 GET /sync/status 的 `configIssues`（字段恒在、按请求实时算），这里只补日志。
+ * 读配置失败时保持原值（空 username 由 WebDavTransport 构造校验兜底报错）。
+ */
+export function createPrepareSync(opts: PrepareSyncOptions): (body: Record<string, unknown>) => Promise<SyncConfig> {
+  const reportIssues = createSyncConfigIssueReporter(opts.log);
+  return async (body) => {
+    const cfg = await opts.parseBody(body);
+    if (!isWebDavConfig(cfg)) return cfg;
+    if (cfg.webdav.username !== undefined && cfg.webdav.username !== '') return cfg;
+    try {
+      const issues: SyncConfigIssue[] = [];
+      const persisted = await readSyncConfig(opts.syncDir, issues);
+      reportIssues(issues);
+      return opts.mergeWebDavUsername(cfg, persisted);
+    } catch {
+      return cfg;
+    }
+  };
+}

package/src/sync/gc-skip.test.ts

@@ -0,0 +1,66 @@
+/**
+ * gc-skip.ts 单测（SYN-04b：通道「本轮 GC 放弃码」的读取判据与冒泡）。
+ *
+ * 行为契约（本文件钉死）：
+ *  - 只有**非空字符串**算「有放弃码」；字段缺失 / null / 数字 / 空串 / getter 抛错 一律当没有；
+ *  - 冒泡进 warnings，且同一轮只报一次；码在文本里必须明文出现（字典未补键时也能 grep）。
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { gcSkipWarning, readGcSkipCode, reportGcSkipOnce } from './gc-skip.ts';
+import type { MsgFunc } from '../core/messages.ts';
+
+/** 造一个「像 transport」的对象：getter 形态与 webdav/s3 通道一致（可配置抛错）。 */
+function withLastGc(spec: { value?: unknown; throw?: boolean }): unknown {
+  const obj = {};
+  Object.defineProperty(obj, 'lastGcSkip', {
+    configurable: true,
+    get() {
+      if (spec.throw === true) throw new Error('getter exploded');
+      return spec.value;
+    },
+  });
+  return obj;
+}
+
+test('gc-skip/①：只有非空字符串算放弃码，其余形态一律当没有', () => {
+  assert.equal(readGcSkipCode(withLastGc({ value: 'gc-skip-reference-missing' })), 'gc-skip-reference-missing');
+  assert.equal(readGcSkipCode(withLastGc({ value: '' })), null);
+  assert.equal(readGcSkipCode(withLastGc({ value: null })), null);
+  assert.equal(readGcSkipCode(withLastGc({ value: 42 })), null);
+  assert.equal(readGcSkipCode(withLastGc({ value: { code: 'x' } })), null);
+});
+
+test('gc-skip/②：字段缺失与 getter 抛错都当没有（诊断能力绝不影响 push）', () => {
+  assert.equal(readGcSkipCode({}), null);
+  assert.equal(readGcSkipCode(null), null);
+  assert.equal(readGcSkipCode(undefined), null);
+  assert.equal(readGcSkipCode(withLastGc({ throw: true })), null);
+});
+
+test('gc-skip/③：字典未补键时码以明文兜底（可 grep），补键后不重复追加', () => {
+  const bare: MsgFunc = (key) => key;
+  const text = gcSkipWarning(bare, 'gc-skip-snapshot-unparsable');
+  assert.equal(text, 'sync.gcSkipped: gc-skip-snapshot-unparsable');
+
+  const filled: MsgFunc = () => '本轮已放弃回收远端孤立文件（gc-skip-reference-missing）';
+  assert.equal(gcSkipWarning(filled, 'gc-skip-reference-missing'), '本轮已放弃回收远端孤立文件（gc-skip-reference-missing）');
+});
+
+test('gc-skip/④：同一轮只报一次；无码 / 非法形态零告警', () => {
+  const msg: MsgFunc = (key, vars) => `${key}(${String((vars as { code?: string } | undefined)?.code ?? '')})`;
+
+  const warnings: string[] = [];
+  const state = { done: false };
+  const transport = withLastGc({ value: 'gc-skip-reference-missing' });
+  reportGcSkipOnce(transport, msg, warnings, state);
+  reportGcSkipOnce(transport, msg, warnings, state);
+  reportGcSkipOnce(transport, msg, warnings, state);
+  assert.equal(warnings.length, 1);
+  assert.equal(state.done, true);
+
+  const quiet: string[] = [];
+  reportGcSkipOnce({}, msg, quiet, { done: false });
+  reportGcSkipOnce(withLastGc({ value: 0 }), msg, quiet, { done: false });
+  assert.deepEqual(quiet, []);
+});

package/src/sync/gc-skip.ts

@@ -0,0 +1,64 @@
+import type { MsgFunc } from '../core/messages.ts'
+
+/**
+ * 本轮 blob GC 的放弃码（SYN-04）。**机器可判定**，文案由上层按码翻译（字典键由 Lead 统一加）：
+ * 通道没有 logger，`delete()` 还会吞掉 GC 抛出的异常，所以「本轮为什么没回收」只能靠这个码如实外露。
+ * 三态同义：拿不到引用者内容 = 无法证明「没人引用」⇒ 本轮整轮放弃，绝不按残集删除。
+ *
+ * 单一来源：webdav / s3 两个通道都从这里导入（此前各写一份同名常量，改一侧不炸另一侧 =
+ * 静默漂移；本模块不 import 任何 transport，所以不存在环）。
+ */
+export const GC_SKIP_REFERENCE_MISSING = 'gc-skip-reference-missing'
+export const GC_SKIP_REFERENCE_UNREADABLE = 'gc-skip-reference-unreadable'
+export const GC_SKIP_SNAPSHOT_UNPARSABLE = 'gc-skip-snapshot-unparsable'
+
+/** blob GC 放弃码（SYN-04）。 */
+export type GcSkipCode =
+  | typeof GC_SKIP_REFERENCE_MISSING
+  | typeof GC_SKIP_REFERENCE_UNREADABLE
+  | typeof GC_SKIP_SNAPSHOT_UNPARSABLE
+
+/**
+ * SYN-04b：通道「本轮 GC 放弃码」的读取与冒泡（从 sync-engine.ts 下沉，行为逐字不变）。
+ *
+ * 为什么放在独立模块：SYN-04 之后 webdav/s3 遇到「引用快照 404 / 读不出」会**放弃本轮 blob GC**
+ * （绝不在「证明不了没人引用」时删 blob），而通道层没有 logger、delete() 又把 GC 异常吃掉
+ * ⇒ 放弃只能靠 transport 的只读字段外露。字段形态是 getter（见 webdav/s3 transport 的
+ * `get lastGcSkip()`），这里按 unknown 读、只接受非空字符串，getter 抛错也不影响 push。
+ *
+ * 判据（缺一不可，全部当「没有放弃码」）：字段缺失 / null / 非字符串 / 空串 / getter 抛错。
+ * 读不到 ≠ 没有放弃：通道没这个能力时本来就不该冒泡告警，所以两者在调用侧合并处理。
+ */
+export function readGcSkipCode(transport: unknown): string | null {
+  try {
+    const raw = (transport as { lastGcSkip?: unknown } | null | undefined)?.lastGcSkip
+    return typeof raw === 'string' && raw !== '' ? raw : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * SYN-04b：放弃码 → 一条 warning 文本。
+ *
+ * 码必须同时以**明文**出现：core 目录的翻译器对未知键回退键名本身（{code} 插值随之丢失），
+ * 而文案键由上层统一补字典 —— 在补键之前，只发出裸键名等于「报了但看不出来」，日志也无法 grep。
+ */
+export function gcSkipWarning(msg: MsgFunc, code: string): string {
+  const text = msg('sync.gcSkipped', { code })
+  return text.includes(code) ? text : text + ': ' + code
+}
+
+/**
+ * SYN-04b：把通道的 GC 放弃码冒泡成一条 warning（`state` 保证同一轮只报一次）。
+ *
+ * 语义边界：放弃 GC **不是** push 失败 —— 快照本身已上传/已删除，只是这一轮的孤儿 blob
+ * 没被回收（磁盘/远端会多留几份文件）。所以它进 warnings、不进 ok，与 prune 既有语义一致。
+ */
+export function reportGcSkipOnce(transport: unknown, msg: MsgFunc, warnings: string[], state: { done: boolean }): void {
+  if (state.done) return
+  const code = readGcSkipCode(transport)
+  if (code === null) return
+  state.done = true
+  warnings.push(gcSkipWarning(msg, code))
+}

package/src/sync/git/git-probe.test.ts

@@ -48,7 +48,12 @@ test('git probe：匿名 ls-remote 成功 → 连接正常，且**只**发这一
   assert.equal(result.snapshotCount, undefined, '不得报快照数（统计它需要 fetch 工作副本）');
   assert.deepEqual(result.createdCollections ?? [], [], 'git 通道不在远端建目录');
   assert.equal(calls.length, 1, '探针只准发一条 ls-remote');
-  assert.deepEqual(calls[0], ['ls-remote', REPO]);
+  // 前置的 `-c <key=value>` 是网络低速上限（issue #122）与协议护栏（SEC-12），不属于命令本体
+  const argv = calls[0]!;
+  let i = 0;
+  while (argv[i] === '-c') i += 2;
+  // `--` 是 SEC-12 的选项终止符：repoUrl 恒定位在 `--` 之后，永不被当成 git 选项解析
+  assert.deepEqual(argv.slice(i), ['ls-remote', '--', REPO]);
 });
 
 test('git probe：匿名被拒、带凭据成功 → 连接正常（私有仓库 + 凭据可用）', async () => {