task-ledger 1.2.9 → 1.3.0

package/README.md

@@ -120,11 +120,13 @@
 - 冲突时**报错要求重跑**，不静默覆盖
 - 写入成功后脚本会**自动同步**：把本次改动的台账文件 `git add <精确文件>` + `commit`（消息 `chore(ledger): <命令> <提交者>`，即 conventional commits 格式，多数仓库装了 commitlint 也认）；当前分支有上游跟踪分支时再 `push`。全程确定性脚本，不依赖大模型
 - 仓库若装了自定义提交检查并拒了这条消息，脚本会**再用 `--no-verify` 提交一次**（台账是数据文件，不过 lint）；仍失败则把 git 的报错打到 stderr 并要求手动提交 —— **同步失败绝不静默**，但退出码保持 0（台账本身已写成功）
-- 写前会**定向取最新**：只刷新 `ledger/progress.json` 与 `ledger/history/`（这两个只由脚本写）；`ledger/worklog/` 里已有的正文一个字都不动，只在本地缺文件时补下远端的新文件（补下的文件随本次提交入库）。本地有未推送的台账提交、未提交改动、或未入库的同名文件时**中止**，不静默覆盖；命令随后失败时，写前刷下来的内容会回滚原样
-- 本地**没有未推送提交**时，写前会先 fast-forward 到上游（只快进、不产生合并提交）；有未推送提交就跳过，退回上面那条的定向刷新
+- 写前会**定向取最新**：只刷新 `ledger/progress.json` 与 `ledger/history/`（这两个只由脚本写）；`ledger/worklog/` 里已有的正文一个字都不动，只在本地缺文件时补下远端的新文件（补下的文件随本次提交入库）。有未提交的台账改动、或未入库的同名文件时**中止**，不静默覆盖；命令随后失败时，写前刷下来的内容会回滚原样
+- 本地有未推送的台账提交时，写前会**先自动补推**（非快进就 `rebase` 一次再推），成功后照常写 —— 离线攒下的那几笔，联网后第一笔写就会自己推上去
+- 本地**没有未推送提交**时，写前先 fast-forward 到上游（只快进、不产生合并提交）
 - 同一个 clone 里的写命令**排队**执行（仓级文件锁，最多等 60 秒），避免两个 agent 同时写时，一个把另一个刚写完还没提交的改动静默覆盖
-- 写后推送被拒时，工作树干净才自动 `rebase` 一次再推（各自改各自的任务时按行自动合并）；冲突立刻 `rebase --abort`，绝不 `--force`、绝不留 rebase 中间态
-- 无 git 仓库 / 无上游跟踪 / 被 `.gitignore` 排除 / 无实际变更 都会静默跳过；`--no-sync` 或环境变量 `TASK_LEDGER_NO_SYNC=1` 可同时关掉写前取最新与写后同步
+- 写后推送被拒时，工作树干净才自动 `rebase` 一次再推（各自改各自的任务时按行自动合并）；冲突立刻 `rebase --abort`，绝不 `--force`、绝不留 rebase 中间态。**本地有用户自己的（非台账）未推送提交时不做 rebase**（那会改写它们的提交号），只提示并让用户自己合并；推送前还会说明「这次会一并推走你本地几个提交」
+- 无 git 仓库 / 无上游跟踪 / 被 `.gitignore` 排除（含「台账先提交过、之后才加忽略规则」）/ 无实际变更 都会静默跳过；`--no-sync`（写在子命令前后都行）或环境变量 `TASK_LEDGER_NO_SYNC=1` 可同时关掉写前取最新与写后同步
+- **环境要求 git ≥ 2.27**（自动合并依赖 `rebase --autostash` 的冲突回滚）。没有 git 的目录自动跳过：台账照写，不提交、不推送
 
 ### 结案是原子操作
 

package/SKILL.md

@@ -116,9 +116,9 @@ python3 <本 SKILL.md 所在目录>/scripts/progress.py <子命令> --repo <当
 
 非 0 退出就停手、原样报告，**不要绕过脚本手改 `progress.json` 或历史层**。
 **退出码 0 不等于没事**：写命令之后的同步（commit / push）失败仍返回 0，原因只写在输出里。写命令跑完必看输出，出现 `提示：` / `错误：` / `警告：` 就先用一句话说清「发生了什么 + 你要做什么」，再附原文关键行，按 `references/troubleshooting.md` 对应条目给步骤；纯告知类（如已用 `--no-verify` 提交）一句话带过。只读命令只有 `错误：` 才需要转述。
-并发冲突（文件被改动）重跑一次即可，不要用 `git pull` / `rebase` 去「解决」。
+并发冲突（文件被改动）重跑一次即可，**台账同步一律交给脚本**，不要自己用 `git pull` / `rebase` 去「解决」；只有提示明确说脚本已回滚、或说它不替你 rebase 时，才让用户手动 `git pull --rebase` / `git merge` 后 `git push`，推完再重跑。
 写前会**定向取最新**：只刷新 `ledger/progress.json` 与 `ledger/history/`，`worklog/` 里已有的正文一个字都不动；
-本地有未推送的台账提交、未提交改动或未入库的同名文件时会中止 —— 按提示先提交 / 推送，或加 `--no-sync` 继续本地写。
+有未推送的台账提交时**先自动补推再写**，不要让用户先去 push。只有补推失败、或本地有用户自己的非台账提交（脚本不替他推业务提交）时才中止；有未提交的台账改动、未入库的同名文件，同样中止 —— 按提示处理，或加 `--no-sync`（写在子命令前后都行）继续本地写。
 同一仓库里写命令**排队**执行（最多等 60 秒），并发时不要重试轰炸，等前一个跑完再重跑。
 
 细节见 `references/troubleshooting.md`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-ledger",
-  "version": "1.2.9",
+  "version": "1.3.0",
   "description": "Task-ledger skill for coding agents: per-workspace progress tracking (ledger/progress.json, history, worklog) driven by a CLI script. Standalone install for CodeBuddy and other agents; also bundled inside the dsh-task-ledger DSH plugin.",
   "keywords": [
     "skill",

package/references/troubleshooting.md

@@ -1,6 +1,6 @@
 # 排错
 
-> TL;DR：非 0 退出就停手、原样报告；**退出码 0 但输出里有 `提示：` / `错误：` 同样要读并转述**（同步失败仍返回 0）。别绕过脚本改 JSON。并发冲突重跑一次，不要用 `git pull` / `rebase` 去「解决」。
+> TL;DR：非 0 退出就停手、原样报告；**退出码 0 但输出里有 `提示：` / `错误：` 同样要读并转述**（同步失败仍返回 0）。别绕过脚本改 JSON。并发冲突重跑一次；台账同步交给脚本，只有提示说脚本已回滚、或说它拒绝 rebase 时，才让用户手动 `git pull --rebase` / `git merge`。
 
 ## 退出码
 
@@ -19,13 +19,16 @@
 - **「状态不一致」**：对已在 `doing` 的任务又跑了 `claim`。直接改正文 + `log` 即可。
 - **`log` 报「没写进过程文档」**：worklog 路径丢失 / 不可读。用 `show --id` 查路径；`progress.json` 的 `updated` 已刷新，不要手写「执行记录」。
 - **「文件在操作期间被改动」**（并发指纹冲突）：重新执行一次即可。
-- **「本地台账有未提交改动，写前取最新会覆盖它」**：写前只取 `progress.json` / `history/` 的最新版，本地这两处脏就先停下。先提交（`git add ledger/ && git commit -m "chore(ledger): ..."`）再重跑；暂时离线可加 `--no-sync` 继续本地写。
+- **「本地台账有未提交改动，写前取最新会覆盖它」**：写前只取 `progress.json` / `history/` 的最新版，本地这两处脏就先停下。先提交（`git add ledger/ && git commit -m "chore(ledger): ..."`）再重跑；暂时离线可加 `--no-sync`（写在子命令前后都行）继续本地写。
 - **「另一个会话正在同步同一份台账（已等 60 秒）」**：同一仓库里另一个 agent 正在写并推送，锁没抢到。等它跑完再重跑即可，不要并行重试（会把排队队列越堆越长）。
-- **「本地有 N 个台账提交还没推到 …」**：上次推送没成功（离线 / 他人先推 / 认证失败）。先 `git push` —— 推台账时脚本自己会 fetch + rebase 重试一次，被拒就按它打出的提示手动合并，**不要自己 `git pull` / `git rebase` 台账目录**（会把写前同步的护栏绕过去）。推完重跑；离线场景用 `--no-sync`，联网后统一提交推送。
+- **「本地有 N 个台账提交还没推到 …」**：写前本来会自动补推，看到这句说明**补推失败**了（多半是本地还有你自己的提交，脚本不替你 rebase）。先 `git push`（非快进就 `git pull --rebase` / `git merge` 后再推），推完重跑；离线场景用 `--no-sync`（写在子命令前后都行），联网后统一提交推送。
+- **「本地有 N 个你自己的提交还没推送 … 脚本不替你 rebase」**：推送被拒，且本地有非台账路径的提交。脚本故意不动它们（rebase 会改写提交号），**不要重跑台账命令**（会二次写入）。让用户自己 `git pull --rebase` / `git merge` 后 `git push`；台账改动已安全留在本地，推完重跑即可。
+- **「没能确认本地有没有你自己的提交（git 数不出来）」**：旧版 git / 浅克隆下 `rev-list` 失败，脚本按「可能有」保守处理，不推也不 rebase。让用户 `git status` / `git log @{u}..HEAD` 自己看，处理完再重跑。
+- **「写前把本地 N 个未推送的提交推上去了」/「本次推送会把本地 N 个你自己的提交一并推上去」**：纯告知（脚本已推或即将推），一句话带过「这次顺带把你本地 N 个提交推上去了」，不要回滚、不要重推。
 - **「本地已提交，但推送被拒」**：改动已安全落盘，只是远端没收，**不要重跑台账命令**（会二次写入）。看提示里 `git：` 那行的原文：`! [rejected] ... (fetch first)` = 他人先推，脚本已自动合并过一次仍失败就手动合并台账文件；`Permission denied (publickey)` / `could not read Username` = 凭据问题，找用户修，不要反复重试。
 - **「自动 rebase 未成功（已回滚到 rebase 前）」**：同一条任务被两边同时改了。脚本已 abort，仓库是干净的；按提示里的冲突原文手动合并后 `git push`。
 - **「自动 rebase 冲突后回滚也失败了」**：仓库停在 rebase 中间态，**先别跑任何台账命令**。在仓库根 `git rebase --abort`；仍失败就 `git status` 看残留，必要时删 `.git/rebase-merge` / `.git/rebase-apply` 再重试。
-- **「暂存了你的未提交改动」+ autostash 冲突**：你的未提交改动在 stash 里，没有丢。`git stash list` 确认后用 `git stash pop` 手动解冲突；只想要内容可 `git stash show -p stash@{0}` 取出。
+- **「暂存了你的未提交改动」+ autostash 冲突**：你的未提交改动在 stash 里，没有丢；提示里点名的那几个文件此刻**带着 `<<<<<<<` 冲突标记**，git 不会拦你提交，别把它们当成品。解冲突后确认内容，再 `git stash drop`；只想要内容可 `git stash show -p stash@{0}` 取出。
 - **「git add 失败」/「自动提交失败」**：台账已写进本地文件，只是没进 git。按错误原话处理后手动 `git add <文件> && git commit -m "chore(ledger): ..."`。
 - **「没有上游跟踪分支」/「当前是 detached HEAD」**：台账照写、照提交到本地，但**不会推送**。让用户建上游（`git push -u origin <分支>`）或切回分支；离线时这样用，联网后统一推一次。
 - **「写前快进 … 没成功」**：通常是工作区里有未提交改动（git 按文件拦，不看行），脚本改走「只刷新本次要写的台账文件」。想快进就先提交或 stash 那些文件。
@@ -35,3 +38,8 @@
 ## 硬约束
 
 不要直接编辑 `ledger/progress.json`、`ledger/history/*.md`；不要另建 worklog；不要手写「执行记录」节。
+
+## 环境要求
+
+- **git ≥ 2.27**：写前/写后的自动合并依赖 `rebase --autostash`，低于这个版本 autostash 冲突回滚不可靠。
+- **没有 git 的目录自动跳过**：台账照常写入，不提交、不推送、不报错。

package/scripts/progress.py

@@ -490,26 +490,57 @@ def _why(raw: str | None, fallback: str) -> str:
     return " / ".join(lines[-3:]) if lines else fallback
 
 
-def _foreign_commits(g: tuple[str, ...], upstream: str) -> tuple[int, list[str]]:
-    """本地领先 upstream、但不在 `ledger/` 里的提交（用户自己的代码）：返回 (数量, 前几条摘要)。
+def _ledger_rel(files: list[Path], root: str) -> str:
+    """台账目录相对 git 根的路径：monorepo 子目录时是 `svc/api/ledger`，不是硬编码的 `ledger`。"""
+    for f in files:
+        for cand in (f.parent, *f.parents):
+            if (cand / PROGRESS_REL.name).is_file():
+                try:
+                    return cand.resolve().relative_to(Path(root).resolve()).as_posix()
+                except ValueError:
+                    break
+    return PROGRESS_REL.parent.as_posix()
+
+
+def _push(
+    g: tuple[str, ...], upstream: str, *, check: bool = False
+) -> subprocess.CompletedProcess:
+    """显式 refspec：本地分支与上游分支不同名（main ↔ master）时，裸 `git push` 直接 fatal。"""
+    remote, _, branch = upstream.partition("/")
+    refspec = f"HEAD:{branch}" if branch else "HEAD"
+    return _git(*g, "push", remote, refspec, timeout=30, check=check)
 
-    git 按路径过滤，不看提交消息 —— 用户把台账提交改写成别的 message 也不会被误判成「业务提交」。
+
+def _foreign_commits(
+    g: tuple[str, ...], upstream: str, ledger_rel: str
+) -> tuple[int, list[str]]:
+    """本地领先 upstream、但不在台账目录里的提交（用户自己的代码）：(数量, 前几条摘要)。
+
+    数量 -1 = 数不出来，调用方必须按「可能有」处理 —— 当成 0 就等于放行推送 / rebase，
+    那正是脚本声称绝不做的事（fail-closed）。
     """
     spec = f"{upstream}..HEAD"
-    raw = _git_bytes(*g, "rev-list", "--count", spec, "--", ".", ":(exclude)ledger")
+    exclude = f":(exclude){ledger_rel}"
+    raw = _git_bytes(*g, "rev-list", "--count", spec, "--", ".", exclude)
     try:
-        count = int((raw or b"-1").decode("ascii", "replace").strip())
+        count = int((raw or b"").decode("ascii", "replace").strip())
     except ValueError:
-        return 0, []  # 数不出来就当作没有：宁可少提示，不阻断台账写入
+        return -1, []
     if count <= 0:
-        return 0, []
+        return count, []
     listed = _git_bytes(
-        *g, "log", "--format=%h %s", spec, "--", ".", ":(exclude)ledger"
+        *g,
+        "log",
+        "--format=%h %s",
+        spec,
+        "--",
+        ".",
+        exclude,
     )
     return count, (listed or b"").decode("utf-8", "replace").strip().splitlines()[:3]
 
 
-def _rebase_retry(g: tuple[str, ...]) -> bool:
+def _rebase_retry(g: tuple[str, ...], ledger_rel: str) -> bool:
     """推送被拒后自动 rebase 一次；只在工作树干净时做，失败立刻 abort。
 
     台账按任务分条存（progress.json 是按任务号 key 的对象、history 一行一条），
@@ -527,12 +558,16 @@ def _rebase_retry(g: tuple[str, ...]) -> bool:
         return False
     # 用户自己 commit 的代码不动：rebase 会重放整支分支，把他们的提交号全改写。
     # 只在自己那几条台账提交上做，才是「只碰台账」这条边界的完整实现。
-    foreign, titles = _foreign_commits(g, "@{upstream}")
-    if foreign > 0:
-        detail = f"：{'；'.join(titles)}" if titles else ""
+    # foreign != 0：-1 表示数不出来，同样按「可能有」处理，宁可不动也不越权。
+    foreign, titles = _foreign_commits(g, "@{upstream}", ledger_rel)
+    if foreign != 0:
+        if foreign > 0:
+            detail = f"：{'；'.join(titles)}" if titles else ""
+            what = f"本地有 {foreign} 个你自己的提交还没推送{detail}"
+        else:
+            what = "没能确认本地有没有你自己的提交（git 数不出来）"
         print(
-            f"提示：本地有 {foreign} 个你自己的提交还没推送{detail}。"
-            "脚本不替你 rebase（那会改写它们的提交号），本次没有自动合并。\n"
+            f"提示：{what}。脚本不替你 rebase（那会改写提交号），本次没有自动合并。\n"
             "  处理：手动 `git pull --rebase` 或 `git merge` 后再 `git push`；"
             "台账改动已安全留在本地。",
             file=sys.stderr,
@@ -544,10 +579,29 @@ def _rebase_retry(g: tuple[str, ...]) -> bool:
     rebase = _git(*g, "rebase", "--autostash", "@{upstream}", timeout=30)
     if rebase.returncode == 0:
         combined = f"{rebase.stdout or ''}{rebase.stderr or ''}"
-        if "autostash" in combined:
+        # 判「改动放回时冲突了」不能认 git 的文案：2.27+ 的措辞是
+        # 「Your local changes are stashed, however applying them resulted in conflicts」，
+        # 跟旧版的「Applying autostash resulted in conflicts」不是一回事 —— 认字符串时
+        # 实测 git 2.55 会漏判，把「工作树里带着冲突标记」说成「已放回」（最坏的一种错）。
+        # rebase 本身成功（returncode 0）就说明冲突不来自 rebase，只可能来自 autostash，
+        # 于是直接看 index 有没有未合并项。
+        conflicted = _split_z(
+            _git_bytes(*g, "diff", "--name-only", "--diff-filter=U", "-z")
+        )
+        if conflicted:
+            # 必须点名文件：此刻这些文件带 `<<<<<<<` 标记，不写清楚就会有人把冲突标记
+            # 当成品提交上去（git 不会替你报错，它只当普通改动）。
+            print(
+                "提示：rebase 成功，但把你的未提交改动放回工作树时冲突了 —— "
+                "这些文件现在带着 `<<<<<<<` 冲突标记，别当成品提交：\n  "
+                + "\n  ".join(conflicted)
+                + "\n  改动同时还在 stash 里（`git stash list`）；解完冲突、确认内容没错"
+                "再 `git stash drop`。",
+                file=sys.stderr,
+            )
+        elif "autostash" in combined:
             print(
-                "提示：自动合并前暂存了你的未提交改动，rebase 后已放回；"
-                "若 git 提示 autostash 冲突，跑 `git stash list` 手动处理。",
+                "提示：自动合并前暂存了你的未提交改动，rebase 后已放回。",
                 file=sys.stderr,
             )
         return True
@@ -597,11 +651,14 @@ def git_sync(action: str) -> None:
             return  # 不是 git 项目 → 跳过（规则1：有才提交）
         root = top.stdout.strip()
         g = ("git", "-C", root)
-        # 只 add 本次真实改动、且未被 ignore 的文件
+        # 只 add 本次真实改动、且未被 ignore 的文件。
+        # --no-index 不能省：忽略规则对已跟踪文件同样生效（先提交过台账、之后才把
+        # ledger/ 写进 .gitignore 就是这种情形），而默认的 check-ignore 只报未跟踪
+        # 文件、漏判后 git add 会撞「paths are ignored」并打一句「请手动提交」的瞎提示。
         to_add = [
             str(f)
             for f in files
-            if _git(*g, "check-ignore", "-q", str(f)).returncode != 0
+            if _git(*g, "check-ignore", "--no-index", "-q", str(f)).returncode != 0
         ]
         if not to_add:
             return  # 全被 ignore → 尊重用户选择，不强行提交
@@ -644,7 +701,9 @@ def git_sync(action: str) -> None:
             return
         # push 是分支级的：本地有用户自己 commit 但没推的代码，会一并送到远端。
         # 脚本不替用户下这个决定，但必须说出来，别让它无声发生。
-        foreign, titles = _foreign_commits(g, upstream.stdout.strip())
+        up = upstream.stdout.strip()
+        ledger_rel = _ledger_rel(files, root)
+        foreign, titles = _foreign_commits(g, up, ledger_rel)
         if foreign > 0:
             detail = f"：{'；'.join(titles)}" if titles else ""
             print(
@@ -652,13 +711,13 @@ def git_sync(action: str) -> None:
                 file=sys.stderr,
             )
         try:
-            _git(*g, "push", timeout=30, check=True)
+            _push(g, up, check=True)
         except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as push_exc:
             # 非快进：只在台账工作树干净时自动 rebase 一次再推，冲突立刻 abort。
             # 各自改各自的任务时 git 按行自动合并；同一条任务冲突就干净失败，绝不 --force。
-            if _rebase_retry(g):
+            if _rebase_retry(g, ledger_rel):
                 try:
-                    _git(*g, "push", timeout=30, check=True)
+                    _push(g, up, check=True)
                     return
                 except (
                     subprocess.CalledProcessError,
@@ -762,43 +821,54 @@ def _git_midstate(git_root: str) -> str | None:
 
 
 def _presync_guard(
-    git_root: str, upstream: str, managed: list[str], remote_files: set[str]
+    git_root: str,
+    upstream: str,
+    managed: list[str],
+    remote_files: set[str],
+    *,
+    check_ahead: bool = True,
 ) -> None:
     """取最新之前确认本地没有会被覆盖掉的东西；命中就中止，绝不静默覆盖。
 
     三种命中：未推送的台账提交（取最新会把它们的内容回退掉）、已跟踪文件的
     未提交改动、本地还没入库但远端已有同名文件。
+
+    check_ahead=False 用在自动补推之前：那时本地还领先，ahead 必然非 0；
+    补推完成后再跑一次完整检查。
     """
-    ahead = _git_bytes(
-        "git",
-        "-C",
-        git_root,
-        "rev-list",
-        "--count",
-        f"{upstream}..HEAD",
-        "--",
-        *managed,
-    )
-    count = (ahead or b"").decode("ascii", "replace").strip()
-    if count and count != "0":
-        listing = _git_bytes(
+    if check_ahead:
+        ahead = _git_bytes(
             "git",
             "-C",
             git_root,
-            "log",
-            "--oneline",
+            "rev-list",
+            "--count",
             f"{upstream}..HEAD",
             "--",
             *managed,
         )
-        recent = (listing or b"").decode("utf-8", "replace").strip().splitlines()[:3]
-        detail = ("\n  未推送：" + "；".join(recent)) if recent else ""
-        raise Fail(
-            f"本地有 {count} 个台账提交还没推到 {upstream}，写前取最新会把它们的内容"
-            f"回退掉，已中止本次操作。{detail}\n"
-            "  处理：有网络时先 `git push`；暂时离线可加 --no-sync 继续在本地写，"
-            "联网后再提交推送。"
-        )
+        count = (ahead or b"").decode("ascii", "replace").strip()
+        if count and count != "0":
+            listing = _git_bytes(
+                "git",
+                "-C",
+                git_root,
+                "log",
+                "--oneline",
+                f"{upstream}..HEAD",
+                "--",
+                *managed,
+            )
+            recent = (
+                (listing or b"").decode("utf-8", "replace").strip().splitlines()[:3]
+            )
+            detail = ("\n  未推送：" + "；".join(recent)) if recent else ""
+            raise Fail(
+                f"本地有 {count} 个台账提交还没推到 {upstream}，写前取最新会把它们的内容"
+                f"回退掉，已中止本次操作。{detail}\n"
+                "  处理：先 `git push` 补齐再重跑；暂时离线可加 --no-sync 继续在本地写，"
+                "联网后再提交推送。"
+            )
     dirty = _split_z(
         _git_bytes(
             "git", "-C", git_root, "diff", "--name-only", "-z", "HEAD", "--", *managed
@@ -982,28 +1052,6 @@ def git_presync(action: str, args: argparse.Namespace) -> None:
                 file=sys.stderr,
             )
 
-    # 离线攒下的台账提交：联网后第一笔写先把它们推上去，别拿「有 N 个没推」挡住写入。
-    # 用户自己的业务提交不碰：push 会把它们一并带走，那个决定归用户（见 _rebase_retry）。
-    if ahead_n > 0:
-        g_tuple = ("git", "-C", str(git_root))
-        foreign_n, _ = _foreign_commits(g_tuple, upstream)
-        if foreign_n == 0:
-            pushed = _git(*g_tuple, "push", timeout=30)
-            if pushed.returncode != 0 and _rebase_retry(g_tuple):
-                pushed = _git(*g_tuple, "push", timeout=30)
-            if pushed.returncode == 0:
-                print(
-                    f"提示：写前把本地 {ahead_n} 个未推送的提交推上去了。",
-                    file=sys.stderr,
-                )
-                ahead_n = 0
-            else:
-                print(
-                    "提示：写前推送失败"
-                    f"（{_why(pushed.stderr or pushed.stdout, f'退出码 {pushed.returncode}')}）。",
-                    file=sys.stderr,
-                )
-
     root = str(git_root)
     progress_rel = f"{ledger_rel}/{PROGRESS_REL.name}"
     worklog_rel = f"{ledger_rel}/{WORKLOG_DIR.name}"
@@ -1030,6 +1078,35 @@ def git_presync(action: str, args: argparse.Namespace) -> None:
 
     remote_files = {rel for rel in managed if _remote_exists(root, upstream, rel)}
 
+    # 先查本地有没有会被覆盖掉的东西（尤其未提交改动），必须排在自动补推之前：
+    # 补推里的 rebase --autostash 会先把改动收进 stash，abort 后工作树看起来「干净」，
+    # 后续覆盖就会把那一版改动弄丢。
+    _presync_guard(root, upstream, managed, remote_files, check_ahead=False)
+
+    # 离线攒下的台账提交：联网后第一笔写先把它们推上去，别拿「有 N 个没推」挡住写入。
+    # 用户自己的提交一并带走（push 是分支级的），但只提示、不 rebase —— 改写提交号才是越权。
+    if ahead_n > 0:
+        g_tuple = ("git", "-C", str(git_root))
+        foreign_n, _ = _foreign_commits(g_tuple, upstream, ledger_rel)
+        pushed = _push(g_tuple, upstream)
+        if pushed.returncode != 0 and _rebase_retry(g_tuple, ledger_rel):
+            pushed = _push(g_tuple, upstream)
+        if pushed.returncode == 0:
+            extra = f"（其中 {foreign_n} 个是你自己的提交）" if foreign_n > 0 else ""
+            print(
+                f"提示：写前把本地 {ahead_n} 个未推送的提交推上去了{extra}。",
+                file=sys.stderr,
+            )
+            ahead_n = 0
+        else:
+            print(
+                "提示：写前推送失败"
+                f"（{_why(pushed.stderr or pushed.stdout, f'退出码 {pushed.returncode}')}）。",
+                file=sys.stderr,
+            )
+
+    # 补推后复查：补推失败（多半是本地有你自己的提交，脚本不替你 rebase）时，
+    # 这里仍会把「台账提交领先」拦下来，避免写进过期数据。
     _presync_guard(root, upstream, managed, remote_files)
 
     for rel in remote_files:
@@ -2958,6 +3035,17 @@ def build_parser() -> argparse.ArgumentParser:
     add_repo(p)
     p.set_defaults(func=cmd_validate)
 
+    # 每个子命令也认 --no-sync：人（和 agent）习惯把参数缀在子命令后面，
+    # 只挂在主 parser 上时 `new --no-sync` 会直接 usage 报错、命令根本跑不起来。
+    # default=SUPPRESS 是关键：否则解析子命令时会把主 parser 上已解析的 True 覆盖回 False。
+    for sub_parser in sub.choices.values():
+        sub_parser.add_argument(
+            "--no-sync",
+            action="store_true",
+            default=argparse.SUPPRESS,
+            help="跳过写前取最新与写后自动 git 提交 / 推送（等价于 TASK_LEDGER_NO_SYNC=1；写在子命令前后均可）",
+        )
+
     return parser