dsh-config-manager 0.1.78 → 0.1.79

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

@@ -211,6 +211,39 @@ test('token 不泄漏：credential 文件在 git 调用期间存在、用后删
   for (const c of calls) for (const arg of c.args) assert.ok(!arg.includes(TEST_TOKEN), `argv 泄漏 token: ${arg}`);
 });
 
+test('issue #103：credential.username 必须与 store 文件里的用户名一致（全局 .gitconfig 不得顶掉查找键）', async (t) => {
+  // git credential store 以 URL 里的 username 为查找键；只写 store 文件不钉 username 时，
+  // 全局 .gitconfig 的 credential.<url>.username（GCM / gh 写入）会把键换成别的用户名 →
+  // 查不到口令 → 无 tty 环境直接 fatal。这里把「pin 的值 === store 文件里的用户名」钉成不变量。
+  for (const username of [undefined, 'x-access-token']) {
+    const dir = await makeTempDir(t);
+    const seen: { args: string[]; fileRaw: string }[] = [];
+    const exec: GitExecFn = async (_cmd, args) => {
+      const helper = args.find((a) => a.startsWith('credential.helper=') && a.includes('store --file='));
+      if (helper) {
+        const file = helper.slice(helper.indexOf('--file=') + '--file='.length).replace(/^"|"$/g, '');
+        seen.push({ args, fileRaw: await fs.readFile(file, 'utf8') });
+      }
+      return { stdout: '', stderr: '', code: 0 };
+    };
+    const transport = new GitTransport(makeOptions({
+      workDir: dir,
+      exec,
+      ...(username === undefined ? {} : { credentialUsername: username }),
+    }));
+    await transport.list();
+    assert.ok(seen.length >= 1, '必须发生过带凭据的调用');
+    const expected = username ?? 'oauth2';
+    for (const call of seen) {
+      const pin = call.args.find((a) => a.startsWith('credential.username='));
+      assert.equal(pin, `credential.username=${expected}`, '必须把 username 钉进 git 参数（缺省 oauth2，可用 credentialUsername 覆盖）');
+      const idx = call.args.indexOf(pin as string);
+      assert.equal(call.args[idx - 1], '-c', 'git 只认 `-c key=value` 形态，-c 必须紧邻');
+      assert.ok(call.fileRaw.startsWith(`https://${expected}:`), 'store 文件里的用户名必须与 pin 的值同源');
+    }
+  }
+});
+
 test('upload 契约：写快照目录 + add + commit(add) + push，返回 computeSnapshotMeta', async (t) => {
   const dir = await makeGitWorkDir(t);
   const calls: CallRecord[] = [];
@@ -1079,6 +1112,8 @@ test('issue #79 集成：inspectWorkDir + rebuildWorkDir（relink 非破坏 / re
   assert.equal(after.origin, bare);
   assert.equal(after.ahead, 0, 'relink 不丢弃/不产生本地提交');
   assert.equal(after.dirty, false, 'relink 不动工作树');
+  // issue #104 建议 3：detail 自检必须同时数出远端分支上的快照（预警依据）
+  assert.equal(after.remoteSnapshots, 1, 'detail 自检数出远端分支上的 1 个快照');
 
   await transport.rebuildWorkDir('reclone');
   assert.ok((await fs.stat(path.join(workDir, '.git'))).isDirectory(), 'reclone 后重新 clone 出 .git');
@@ -1091,3 +1126,153 @@ test('issue #79 集成：inspectWorkDir + rebuildWorkDir（relink 非破坏 / re
   await assert.rejects(t3.rebuildWorkDir('reclone'), /不是 git 仓库/);
   assert.ok(await fs.stat(path.join(strayDir, 'stray.txt')), '拒绝时文件必须原样保留');
 });
+/* ---------------------------------------------------------------- issue #104 采纳远端历史（adopt） */
+
+/**
+ * 造一个「另一条历史」的同步仓库：同一个插件布局，但初始提交与现有工作副本不相交。
+ * adopt 的判据是「远端顶层只有快照布局」+「合并原始历史」，所以夹具必须是**假远端**（bare 仓）。
+ */
+async function makeSyncRemote(t: test.TestContext, snapshot: SyncSnapshot & { sections: Record<string, unknown> }): Promise<string> {
+  const bare = await makeBareRepo(t);
+  const workDir = await makeTempDir(t);
+  await new GitTransport({ repoUrl: bare, workDir, credentials: { getToken: async () => TEST_TOKEN } }).upload(snapshot);
+  return bare;
+}
+
+test('issue #104 集成：改成另一条历史的同步仓库 → adopt 合并两条历史（本地提交原样保留、之后能继续 push）', async (t) => {
+  const creds = { getToken: async () => TEST_TOKEN };
+  const bareA = await makeBareRepo(t);
+  const workDir = await makeTempDir(t);
+  await new GitTransport({ repoUrl: bareA, workDir, credentials: creds }).upload(sampleSnapshot({ id: 'snap-001' }));
+
+  const bareC = await makeSyncRemote(t, sampleSnapshot({ id: 'snap-other' }));
+  const localHead = (await runRealGit(['rev-parse', 'HEAD'], workDir)).stdout.trim();
+  const transport = new GitTransport({ repoUrl: bareC, workDir, credentials: creds });
+
+  // 先确认这就是 issue #104 的现场：改地址后 pull --ff-only 因两条历史不相交而失败
+  await assert.rejects(transport.list(), (err: unknown) => {
+    assert.ok(err instanceof SyncTransportError);
+    assert.match(err.message, /不是同一条历史/);
+    return true;
+  });
+
+  await transport.rebuildWorkDir('adopt');
+
+  const facts = await transport.inspectWorkDir({ detail: true });
+  assert.equal(facts.match, true, 'adopt 后 origin 跟随当前配置地址');
+  assert.equal(facts.dirty, false, 'adopt 不留下工作树脏改动');
+  // 2 = 本地原提交（此前只推到过旧地址）+ 这次合并提交：两条都还不在当前地址上，merge 之后需要一次 push。
+  // 断言精确值而不是「>0」：若哪天实现偷偷 rebase 或 force-push，这里会先红。
+  assert.equal(facts.ahead, 2, '本地原提交与合并提交都尚未推到当前地址');
+
+  assert.ok(await fs.stat(path.join(workDir, 'snapshots', 'snap-001')), '本地已有快照保留（不是 reclone）');
+  assert.ok(await fs.stat(path.join(workDir, 'snapshots', 'snap-other')), '远端快照被合并进来');
+
+  const merged = await runRealGit(['log', '--merges', '--oneline'], workDir);
+  assert.match(merged.stdout, /Merge/, '走 merge 而不是 rebase ⇒ 历史里能看到合并提交');
+  const kept = await runRealGit(['merge-base', '--is-ancestor', localHead, 'HEAD'], workDir);
+  assert.equal(kept.code, 0, '本地原提交必须原样保留（rebase 会改写 sha，此断言会红）');
+
+  // adopt 之后普通 push 可用：新快照写进当前地址，旧地址收不到
+  await transport.upload(sampleSnapshot({ id: 'snap-003' }));
+  // issue #104 建议 3 的两个数字必须跟着推送一起收敛：领先 0、远端快照 2
+  const pushed = await transport.inspectWorkDir({ detail: true });
+  assert.equal(pushed.ahead, 0, '推送成功后不再领先远端');
+  // 3 = snap-001（本地历史随合并一起推上去）+ snap-other + snap-003：远端快照数是「远端分支上真实有的」
+  assert.equal(pushed.remoteSnapshots, 3, '远端快照数跟着推送更新（snap-001 + snap-other + snap-003）');
+  const logC = await runRealGit(['log', '--oneline', '--all'], bareC);
+  assert.match(logC.stdout, /snap-003/, '合并后下游能继续 push');
+  const logA = await runRealGit(['log', '--oneline', '--all'], bareA);
+  assert.ok(!logA.stdout.includes('snap-003'), '旧地址不得再收到（否则仍在用旧 origin）');
+});
+
+test('issue #104 集成：远端顶层不是同步布局 → 拒绝合并，且一个字节历史都不动', async (t) => {
+  const creds = { getToken: async () => TEST_TOKEN };
+  const bareA = await makeBareRepo(t);
+  const workDir = await makeTempDir(t);
+  await new GitTransport({ repoUrl: bareA, workDir, credentials: creds }).upload(sampleSnapshot({ id: 'snap-001' }));
+  const localHead = (await runRealGit(['rev-parse', 'HEAD'], workDir)).stdout.trim();
+  const branch = (await runRealGit(['rev-parse', '--abbrev-ref', 'HEAD'], workDir)).stdout.trim();
+
+  // 一个普通代码仓库（顶层是 README.md）：把它的历史合进来 = 把别人的仓库搬进工作副本
+  const bareOther = await makeBareRepo(t);
+  const seed = await makeTempDir(t);
+  await runRealGit(['init'], seed);
+  await runRealGit(['config', 'user.name', 'test'], seed);
+  await runRealGit(['config', 'user.email', 'test@local'], seed);
+  await runRealGit(['checkout', '-B', branch], seed);
+  await fs.writeFile(path.join(seed, 'README.md'), '# notes\n');
+  await runRealGit(['add', '.'], seed);
+  await runRealGit(['commit', '-m', 'unrelated'], seed);
+  await runRealGit(['remote', 'add', 'origin', bareOther], seed);
+  const pushed = await runRealGit(['push', '-u', 'origin', branch], seed);
+  assert.equal(pushed.code, 0, `push 失败: ${pushed.stderr}`);
+
+  const transport = new GitTransport({ repoUrl: bareOther, workDir, credentials: creds });
+  await assert.rejects(transport.rebuildWorkDir('adopt'), (err: unknown) => {
+    assert.ok(err instanceof SyncTransportError);
+    assert.match(err.message, /README\.md/, '必须点出到底撞见了什么（可操作）');
+    assert.match(err.message, /不是本插件的同步仓库/);
+    assert.equal(err.retryable, false, '重试不会自愈');
+    return true;
+  });
+
+  const head = (await runRealGit(['rev-parse', 'HEAD'], workDir)).stdout.trim();
+  assert.equal(head, localHead, '拒绝时历史一步都不许动');
+  await assert.rejects(fs.stat(path.join(workDir, '.git', 'MERGE_HEAD')), '不得留下半截合并');
+  const status = await runRealGit(['status', '--porcelain'], workDir);
+  assert.equal(status.stdout.trim(), '', '拒绝后工作树保持干净');
+});
+
+test('issue #104 集成：工作副本有未提交改动 → 拒绝 adopt（不替用户丢改动）', async (t) => {
+  const creds = { getToken: async () => TEST_TOKEN };
+  const bareA = await makeBareRepo(t);
+  const workDir = await makeTempDir(t);
+  await new GitTransport({ repoUrl: bareA, workDir, credentials: creds }).upload(sampleSnapshot({ id: 'snap-001' }));
+  const localHead = (await runRealGit(['rev-parse', 'HEAD'], workDir)).stdout.trim();
+
+  const bareC = await makeSyncRemote(t, sampleSnapshot({ id: 'snap-other' }));
+  await fs.writeFile(path.join(workDir, 'notes.txt'), 'wip\n');
+
+  const transport = new GitTransport({ repoUrl: bareC, workDir, credentials: creds });
+  await assert.rejects(transport.rebuildWorkDir('adopt'), (err: unknown) => {
+    assert.ok(err instanceof SyncTransportError);
+    assert.match(err.message, /未提交的改动/, '说清为什么拒绝');
+    return true;
+  });
+
+  assert.ok(await fs.stat(path.join(workDir, 'notes.txt')), '用户的文件必须原样保留');
+  const head = (await runRealGit(['rev-parse', 'HEAD'], workDir)).stdout.trim();
+  assert.equal(head, localHead, '被拒绝时不得 merge 任何东西');
+});
+
+test('issue #104 集成：两侧同名快照内容不同 → 合并冲突自动撤销，工作副本回到操作前', async (t) => {
+  const creds = { getToken: async () => TEST_TOKEN };
+  const bareA = await makeBareRepo(t);
+  const workDir = await makeTempDir(t);
+  const manifestA = { schemaVersion: 1, dshVersion: '1.0.0', platform: 'win32' as const, sectionIds: ['settings' as SectionId], containsSecrets: false };
+  await new GitTransport({ repoUrl: bareA, workDir, credentials: creds })
+    .upload(sampleSnapshot({ id: 'snap-c', manifest: manifestA }));
+
+  // 同一个快照 id、不同 manifest.json 内容 ⇒ 合并时 add/add 冲突
+  const bareC = await makeSyncRemote(t, sampleSnapshot({
+    id: 'snap-c',
+    manifest: { ...manifestA, dshVersion: '9.9.9' },
+  }));
+  const localHead = (await runRealGit(['rev-parse', 'HEAD'], workDir)).stdout.trim();
+
+  const transport = new GitTransport({ repoUrl: bareC, workDir, credentials: creds });
+  await assert.rejects(transport.rebuildWorkDir('adopt'), (err: unknown) => {
+    assert.ok(err instanceof SyncTransportError);
+    assert.match(err.message, /合并远端 .* 时发生冲突/);
+    assert.match(err.message, /已撤销这次合并/);
+    return true;
+  });
+
+  await assert.rejects(fs.stat(path.join(workDir, '.git', 'MERGE_HEAD')), 'merge --abort 后不得残留 MERGE_HEAD');
+  const status = await runRealGit(['status', '--porcelain'], workDir);
+  assert.equal(status.stdout.trim(), '', '撤销后工作树必须干净（冲突标记不得留在文件里）');
+  const head = (await runRealGit(['rev-parse', 'HEAD'], workDir)).stdout.trim();
+  assert.equal(head, localHead, '撤销后 HEAD 必须回到操作前的提交');
+});
+

package/src/sync/git/git-transport.ts

@@ -35,7 +35,7 @@ import {
   SyncTransportError, withSyncRetry,
 } from '../transport.ts';
 import type {
-  SyncRetryOptions, SyncSnapshot, SyncSnapshotMeta, SyncTransport, SyncTransportErrorOptions,
+  SyncProbeResult, SyncRetryOptions, SyncSnapshot, SyncSnapshotMeta, SyncTransport, SyncTransportErrorOptions,
 } from '../transport.ts';
 import { parseJsonSafe } from '../../utils/json.ts';
 import { atomicWriteFile } from '../../utils/atomic-write.ts';
@@ -77,6 +77,14 @@ export interface GitWorkDirFacts {
   ahead: number | null;
   /** 工作树是否有未提交改动（读不出 → null） */
   dirty: boolean | null;
+  /**
+   * 远端跟踪分支上的快照数（issue #104 建议 3）：`snapshots/` 与 `snapshots-encrypted/`
+   * 下的直接子项数（目录，或加密通道的 <id>.json 文件）。它和 `ahead` 一起回答
+   * 「本地领先 N 个提交、可远端从来没收到过快照吗」—— 那正是 issue #104 里
+   * 远端两周一个字节都没收到、用户却以为在正常备份的现场。
+   * 只有 detail 自检时给出；无远端跟踪分支 / 读不出 → null。
+   */
+  remoteSnapshots: number | null;
 }
 
 /** 凭据提供者：token 只从这里读取，绝不在任何地方持久化 */
@@ -130,6 +138,11 @@ const SNAPSHOTS_ENCRYPTED_REL = 'snapshots-encrypted';
  * 内容没变 = 文件路径已存在 = 一个字都不写、也不进本次 diff。
  */
 const BLOBS_REL = 'blobs';
+/**
+ * 同步仓库（git 通道）顶层**只可能出现**这三个条目。issue #104 的 `adopt` 模式拿它当安全判据：
+ * 远端分支的顶层出现别的名字 = 这不是本插件的同步仓库，合并它等于把别人的仓库内容搬进工作副本。
+ */
+const ADOPT_ROOT_ALLOW = new Set<string>([SNAPSHOTS_REL, SNAPSHOTS_ENCRYPTED_REL, BLOBS_REL]);
 const DEFAULT_AUTHOR: GitAuthor = { name: 'DSH Config Sync', email: 'sync@dsh.local' };
 const DEFAULT_CREDENTIAL_USERNAME = 'oauth2';
 /** 快照 id 安全字符集：字母数字开头，仅 . _ -；防路径穿越与 commit message 注入 */
@@ -410,6 +423,20 @@ export class GitTransport implements SyncTransport {
     throw new GitTransportError(this.msg('sync.git.repoUnreachable', { url: this.mask(this.o.repoUrl, null) }));
   }
 
+  /**
+   * 连通性探针（cloud-sync 借鉴项 ②）：只读自检「远端可达 + 凭据可用」。
+   *
+   * 为什么复用 ls-remote：它不需要工作副本、不写任何本地状态，而且正是 clone/fetch 之前的那一步 ——
+   * 远端不可达 / 令牌失效 / SSH 主机密钥不信任都会在这里显式失败（checkIsPrivate 抛可操作文案），
+   * 因此结论与随后真正同步时的成败**同源**。
+   * 刻意**不**统计远端快照数：那要先 fetch 工作副本（对本地有写入），超出「只读自检」的范围 ——
+   * 宁可不报，也不报一个会误导的 0。
+   */
+  async probe(): Promise<SyncProbeResult> {
+    await this.checkIsPrivate();
+    return { message: this.msg('sync.git.probeOk') };
+  }
+
   /* ---------------- 内部实现 ---------------- */
 
   private async ensureRepo(): Promise<void> {
@@ -501,7 +528,7 @@ export class GitTransport implements SyncTransport {
   async inspectWorkDir(opts: { detail?: boolean } = {}): Promise<GitWorkDirFacts> {
     const fsx = createSnapshotFs();
     if (!(await fsx.exists(path.join(this.o.workDir, '.git')))) {
-      return { path: this.o.workDir, exists: false, origin: null, pushUrl: null, match: false, ahead: null, dirty: null };
+      return { path: this.o.workDir, exists: false, origin: null, pushUrl: null, match: false, ahead: null, dirty: null, remoteSnapshots: null };
     }
     const originRes = await this.runGit(['remote', 'get-url', 'origin'], { allowNonZero: true });
     const origin = originRes.code === 0 ? originRes.stdout.trim() : '';
@@ -509,6 +536,7 @@ export class GitTransport implements SyncTransport {
     const pushRaw = pushRes.code === 0 ? pushRes.stdout.trim() : '';
     let ahead: number | null = null;
     let dirty: boolean | null = null;
+    let remoteSnapshots: number | null = null;
     if (opts.detail === true) {
       // 未上行的本地提交：HEAD 可达、但任何远端跟踪引用都不可达的提交数（无 upstream 也能算）
       const aheadRes = await this.runGit(['rev-list', '--count', 'HEAD', '--not', '--remotes'], { allowNonZero: true });
@@ -516,6 +544,27 @@ export class GitTransport implements SyncTransport {
       ahead = Number.isFinite(parsed) ? parsed : null;
       const statusRes = await this.runGit(['status', '--porcelain'], { allowNonZero: true });
       dirty = statusRes.code === 0 ? statusRes.stdout.trim() !== '' : null;
+      // issue #104 建议 3：远端分支上到底有几个快照。只读 refs/remotes/origin/<branch>
+      // （上次 fetch / push 的结果），不发网络请求 —— 两条本地只读命令。
+      // 注意不能写 `ls-tree origin/<branch> -- snapshots`：带 pathspec 时它只回显目录条目
+      // 本身（`snapshots`），数出来永远是 1。必须用 `<ref>:<dir>` 取该树的直接子项。
+      const branchRes = await this.runGit(['rev-parse', '--abbrev-ref', 'HEAD'], { allowNonZero: true });
+      const branch = branchRes.code === 0 ? branchRes.stdout.trim() : '';
+      if (branch !== '' && branch !== 'HEAD') {
+        const countTree = async (treeish: string): Promise<number | null> => {
+          const treeRes = await this.runGit(['ls-tree', '--name-only', treeish], { allowNonZero: true });
+          if (treeRes.code !== 0) return null;
+          return treeRes.stdout
+            .split('\n')
+            .map((line) => line.trim())
+            // 每个快照是一级子项；`.gitkeep` 只是占位，不是快照
+            .filter((line) => line !== '' && !line.endsWith(SNAPSHOT_KEEP_FILE)).length;
+        };
+        const plain = await countTree(`origin/${branch}:${SNAPSHOTS_REL}`);
+        const encrypted = await countTree(`origin/${branch}:${SNAPSHOTS_ENCRYPTED_REL}`);
+        // 两个目录都不存在 = 远端分支根本没有快照布局（0）；分支/引用读不出 = null（不猜）
+        remoteSnapshots = plain === null && encrypted === null ? 0 : (plain ?? 0) + (encrypted ?? 0);
+      }
     }
     return {
       path: this.o.workDir,
@@ -526,18 +575,21 @@ export class GitTransport implements SyncTransport {
       match: origin === this.o.repoUrl && (pushRaw === '' || pushRaw === this.o.repoUrl),
       ahead,
       dirty,
+      remoteSnapshots,
     };
   }
 
   /**
-   * 重建工作副本（issue #79 的自救入口）：
+   * 重建工作副本（issue #79 / #104 的自救入口）：
    *  - `relink`：只把 origin / push URL 重新指向 repoUrl（**非破坏性**：不碰工作树与本地提交）；
+   *  - `adopt`：把远端分支**合并进**现有工作副本（issue #104：换成另一个仓库、或远端历史被重写后，
+   *    两条历史不相交，`pull --ff-only` 永远失败；这里合并后本地提交一条都不丢，可 revert）；
    *  - `reclone`：删除工作副本目录后重新 clone（**丢弃未上行的本地提交**；调用方必须先让用户确认）。
    *
    * 安全边界：`reclone` 只在目录**确实是 git 工作副本**（有 .git）时才删；目录非空且无 .git
    * 一律拒绝（与 ensureRepo 同一句 workDirNotRepo）—— 绝不删来路不明的目录。
    */
-  async rebuildWorkDir(mode: 'relink' | 'reclone'): Promise<void> {
+  async rebuildWorkDir(mode: 'relink' | 'adopt' | 'reclone'): Promise<void> {
     this.repoReady = false;
     if (mode === 'relink') {
       await this.ensureRepo(); // .git 存在 → reconcileOrigin
@@ -556,10 +608,121 @@ export class GitTransport implements SyncTransport {
       await this.ensureRepo(); // 空目录 → 直接 clone
       return;
     }
+    if (mode === 'adopt') {
+      // 已有工作副本但历史与远端不相交：合并远端历史，不删任何本地提交
+      await this.adoptRemoteHistory();
+      return;
+    }
     await fs.rm(this.o.workDir, { recursive: true, force: true });
     await this.ensureRepo();
   }
 
+  /**
+   * 采纳远端历史（issue #104）：把远端分支合并进现有工作副本，解开「换了仓库 / 远端历史被重写」
+   * 之后 `pull --ff-only` 的死结（真机形态：`+ 8e87c0c...dc69fc7 main (forced update)` 后
+   * `fatal: Not possible to fast-forward, aborting.`）。
+   *
+   * 为什么 merge 而不是 issue 里建议的 `rebase --root --onto`：
+   *  - rebase 会**改写本地提交**（sha 全变），出问题时无法 revert，中途失败还留下 detached HEAD
+   *    与 .git/rebase-merge 目录，状态比失败前更难收拾；
+   *  - merge 只多一个 merge commit，`git revert -m 1` 可原路退回，冲突时 `merge --abort`
+   *    能干净回到起点（真机裸仓验证：冲突 abort 后无 MERGE_HEAD、工作树零改动）。
+   *
+   * 三条安全边界（宁可不做，也不把别人的仓库合进来）：
+   *  ① 工作树必须干净 —— 有未提交改动时合并会把用户改动卡在冲突里；
+   *  ② 远端分支顶层只允许快照布局（snapshots / snapshots-encrypted / blobs）—— 否则这是个
+   *     「另有用途的仓库」，合并等于把它整个搬进工作副本；
+   *  ③ 远端必须存在同名分支 —— 远端是空仓库（没有任何分支）时视为没什么可采纳，正常返回
+   *     （后续 push 会自己建分支）；有分支但名字对不上则拒绝猜，把远端分支名列出来。
+   */
+  private async adoptRemoteHistory(): Promise<void> {
+    // ① 未提交改动：不替用户丢改动
+    const statusRes = await this.runGit(['status', '--porcelain'], { allowNonZero: true });
+    if (statusRes.code !== 0) {
+      throw new GitTransportError(
+        this.msg('sync.git.cmdFailed', {
+          args: 'status --porcelain',
+          code: String(statusRes.code),
+          err: this.mask(statusRes.stderr, await this.readTokenOnce()),
+        }),
+        { kind: 'unknown', retryable: true },
+      );
+    }
+    if (statusRes.stdout.trim() !== '') {
+      throw new GitTransportError(
+        this.msg('sync.git.adoptDirty', { dir: this.o.workDir }),
+        { kind: 'protocol', retryable: false },
+      );
+    }
+    await this.reconcileOrigin();
+    const branchRes = await this.runGit(['rev-parse', '--abbrev-ref', 'HEAD'], { allowNonZero: true });
+    const branch = branchRes.code === 0 ? branchRes.stdout.trim() : '';
+    if (branch === '' || branch === 'HEAD') {
+      // detached HEAD：没有分支可挂比 upstream，合并也不会被 push 走 → 拒绝并说明
+      throw new GitTransportError(
+        this.msg('sync.git.adoptDetached', { dir: this.o.workDir }),
+        { kind: 'protocol', retryable: false },
+      );
+    }
+    // fetch 是网络操作（幂等读）→ 允许有限指数退避重试
+    await withSyncRetry(async () => {
+      await this.runGit(['fetch', 'origin'], { withCredential: true });
+    }, this.o.retry);
+    const remoteRef = `refs/remotes/origin/${branch}`;
+    const refRes = await this.runGit(['rev-parse', '--verify', '--quiet', remoteRef], { allowNonZero: true });
+    if (refRes.code !== 0) {
+      // 远端没有同名分支：用 ls-remote 区分「远端是空仓库」与「分支名不同」
+      const headsRes = await this.runGit(['ls-remote', '--heads', 'origin'], { withCredential: true, allowNonZero: true });
+      const heads = (headsRes.code === 0 ? headsRes.stdout : '')
+        .split('\n')
+        .map((line) => line.trim().split('\t')[1] ?? '')
+        .filter((ref) => ref.startsWith('refs/heads/'))
+        .map((ref) => ref.slice('refs/heads/'.length));
+      if (heads.length === 0) {
+        this.repoReady = true; // 空仓库：没有可采纳的历史，后续 push 会建分支
+        return;
+      }
+      throw new GitTransportError(
+        this.msg('sync.git.adoptNoRemoteBranch', { branch, heads: heads.slice(0, 3).join(', ') }),
+        { kind: 'protocol', retryable: false },
+      );
+    }
+    // ② 远端顶层只能是快照布局
+    const treeRes = await this.runGit(['ls-tree', '--name-only', `origin/${branch}`], { allowNonZero: true });
+    if (treeRes.code !== 0) {
+      throw new GitTransportError(
+        this.msg('sync.git.cmdFailed', {
+          args: `ls-tree --name-only origin/${branch}`,
+          code: String(treeRes.code),
+          err: this.mask(treeRes.stderr, await this.readTokenOnce()),
+        }),
+        { kind: 'unknown', retryable: true },
+      );
+    }
+    const unknownEntries = treeRes.stdout
+      .split('\n')
+      .map((name) => name.trim().replace(/\/$/, ''))
+      .filter((name) => name !== '' && !ADOPT_ROOT_ALLOW.has(name));
+    if (unknownEntries.length > 0) {
+      throw new GitTransportError(
+        this.msg('sync.git.adoptNotSyncRepo', { entries: unknownEntries.slice(0, 3).join(', ') }),
+        { kind: 'protocol', retryable: false },
+      );
+    }
+    // ③ 合并（不改写任何本地提交）；冲突则 abort 回起点再报错
+    const mergeRes = await this.runGit(['merge', '--allow-unrelated-histories', '--no-edit', `origin/${branch}`], { allowNonZero: true });
+    if (mergeRes.code !== 0) {
+      await this.runGit(['merge', '--abort'], { allowNonZero: true });
+      throw new GitTransportError(
+        this.msg('sync.git.adoptMergeConflict', { branch }),
+        { kind: 'conflict', retryable: false },
+      );
+    }
+    // 让后续 pull --ff-only 有 upstream 可用（忽略失败：分支可能已被删/重命名）
+    await this.runGit(['branch', '--set-upstream-to', `origin/${branch}`, branch], { allowNonZero: true });
+    this.repoReady = true;
+  }
+
   /**
    * pull --ff-only 同步远端；无本地提交（全新仓库）或无 upstream 时静默跳过。
    * opts.retryable=true（仅 list / download 等**幂等读**路径传）：瞬时网络故障走有限指数退避重试。
@@ -666,7 +829,17 @@ export class GitTransport implements SyncTransport {
     const fileArg = quoteGitValue(credFile.replace(/\\/g, '/'));
     await atomicWriteFile(credFile, `https://${this.o.credentialUsername}:${token}@${host}\n`, { mode: 0o600, symlink: 'reject' });
     return {
-      extraArgs: ['-c', 'credential.helper=', '-c', `credential.helper=store --file=${fileArg}`],
+      // issue #103：**必须**把用户名也钉进 git 参数。git credential store 用 URL 里的 username
+      // 作为查找键；store 文件写的是本插件自己的用户名（默认 oauth2），但 git 会先读全局
+      // `.gitconfig` 里的 `credential.<url>.username`（Git Credential Manager / gh CLI 都会写这一行），
+      // 用那个用户名去查 store —— 键对不上就查不到口令，无 tty 时退化成
+      // `fatal: could not read Password for 'https://<全局用户名>@host'`。
+      // 钉住 username 后查找键与 store 文件里的值同源（都来自 credentialUsername）。
+      extraArgs: [
+        '-c', 'credential.helper=',
+        '-c', `credential.helper=store --file=${fileArg}`,
+        '-c', `credential.username=${this.o.credentialUsername}`,
+      ],
       token,
       cleanup: async () => { await fs.rm(tmpDir, { recursive: true, force: true }); },
     };