task-ledger 1.3.0 → 1.3.1

package/scripts/ledgerkit/shell/merge.py

@@ -0,0 +1,266 @@
+"""合并语义：push 被拒后 rebase 撞上的**台账冲突**怎么解。
+
+只认台账自己的文件：`pool.json` / 分片 / `owners.json` 按**任务号**三路合并，
+`worklog/` 与 `history/` 是追加式正文，两边各加的内容并在一起。业务代码一个字都不碰。
+
+rebase 的 stage 语义与字面直觉相反（实测确认）：`:1` 共同祖先、`:2` 上游（别人的）、
+`:3` 本机正在重放的那个提交。本文档的 `ours` 一律指 `:2`、`theirs` 指 `:3`，与 git
+自己在 rebase 里的叫法一致 —— 标反了会让人照着冲突标记把别人的版本留下来。
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from ..core.paths import (
+    HISTORY_DIR,
+    OWNERS_DIR,
+    OWNERS_REL,
+    POOL_REL,
+    WORKLOG_DIR,
+    to_ledger_rel,
+)
+from ..store.atomic import write_text_atomic
+from ..store.json_store import dump_ledger_json
+
+EXPAND_KEYS = ("tasks", "workers")
+
+
+def _load(text: str) -> dict[str, Any] | None:
+    if not text.strip():
+        return {}
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _coerce(value: str | dict | None) -> dict[str, Any] | None:
+    """三方内容：git 给的是文本（`git show :N:rel`），测试与调用方也可以直接给 dict。"""
+    if value is None:
+        return None
+    if isinstance(value, dict):
+        return value
+    return _load(str(value))
+
+
+def _rows_of(data: dict[str, Any] | None, key: str) -> dict[str, Any]:
+    rows = (data or {}).get(key)
+    return rows if isinstance(rows, dict) else {}
+
+
+def is_ledger_json(rel: str) -> bool:
+    """是不是按条目合并的 JSON 台账（`pool.json` / 分片 / `owners.json`）。"""
+    r = to_ledger_rel(rel)
+    return (
+        r == POOL_REL.as_posix()
+        or r == OWNERS_REL.as_posix()
+        or (r.startswith(OWNERS_DIR.as_posix() + "/") and r.endswith(".json"))
+    )
+
+
+def is_append_only(rel: str) -> bool:
+    """是不是追加式正文（过程文档 / 历史）：只加行，不改写别人的行。"""
+    r = to_ledger_rel(rel)
+    return r.startswith((WORKLOG_DIR.as_posix() + "/", HISTORY_DIR.as_posix() + "/"))
+
+
+def owns(rel: str) -> bool:
+    """这份冲突文件归不归脚本管（业务文件一个字都不碰）。"""
+    return is_ledger_json(rel) or is_append_only(rel)
+
+
+def expand_key_of(rel: str) -> str:
+    """这份 JSON 台账按哪个字段做条目级合并。"""
+    return "workers" if to_ledger_rel(rel) == OWNERS_REL.as_posix() else "tasks"
+
+
+def merge_task_dicts(
+    base: str | dict | None,
+    ours: str | dict | None,
+    theirs: str | dict | None,
+) -> tuple[dict[str, Any], list[str]]:
+    """按任务号做三方合并；返回 (合并结果, 两边都改过的任务号)。
+
+    合并单位是「任务」不是文本行 —— 行级合并只认相邻上下文：不同任务各自新增 /
+    结案挤在文件末尾就会撞，而同一任务两边都改时它也判不出该留谁。按 id 对账后，
+    只有一边动过的直接采纳，两边都动过的列进冲突，一个都不静默丢。
+    """
+    b, o, t = (_coerce(x) for x in (base, ours, theirs))
+    if b is None or o is None or t is None:
+        return {}, ["台账冲突无法自动合并：有一方不是合法 JSON，需要人工处理。"]
+    merged: dict[str, Any] = dict(o)
+    for key, value in t.items():
+        if key not in o:
+            merged[key] = value
+        elif o[key] != value and key not in EXPAND_KEYS:
+            merged[key] = value  # 非任务区（version / identity）以本机那份为准
+    conflicts: list[str] = []
+    for expand in EXPAND_KEYS:
+        if not any(expand in x for x in (b, o, t)):
+            continue  # 这份文件没有这个区（pool.json 没有 workers、分片没有 tasks）
+        base_rows, our_rows, their_rows = (
+            _rows_of(b, expand),
+            _rows_of(o, expand),
+            _rows_of(t, expand),
+        )
+        rows: dict[str, Any] = {}
+        for tid in sorted(set(base_rows) | set(our_rows) | set(their_rows)):
+            was, up, loc = base_rows.get(tid), our_rows.get(tid), their_rows.get(tid)
+            if up == loc:
+                if up is not None:
+                    rows[tid] = up
+            elif up == was:
+                if loc is not None:
+                    rows[tid] = loc
+            elif loc == was:
+                # 只有上游动过：上游删了就真删掉。写成 rows[tid] = up 会在文件里
+                # 留一行 "<tid>": null 永久累积，读侧还会因 null 崩掉或整区降级。
+                if up is not None:
+                    rows[tid] = up
+            else:
+                conflicts.append(tid)
+                rows[tid] = up if up is not None else loc
+        merged[expand] = rows
+    return merged, conflicts
+
+
+def union_merge(base: str, ours: str, theirs: str) -> str:
+    """追加式正文的三路合并：两边各自新增的行都要在，不凭行号猜。
+
+    过程文档 / 历史只追加不改写，所以"合并"= 本机那份 + 上游相对共同祖先新增的行
+    （本机已有同样的行就不再重复）。任一侧为空也照常合。
+    """
+    base_lines = set(base.splitlines())
+    have = set(theirs.splitlines())
+    added = [
+        line
+        for line in ours.splitlines()
+        if line not in base_lines and line not in have
+    ]
+    if not added:
+        return theirs
+    head = theirs if theirs.endswith("\n") or not theirs else theirs + "\n"
+    return head + "\n".join(added) + "\n"
+
+
+def conflict_marked(
+    rel: str, base: str, ours: str, theirs: str
+) -> tuple[str, list[str]] | None:
+    """接管一份 JSON 台账冲突：算出「一条一行 + 冲突标记」的新全文。
+
+    返回 (文件新文本, 两边都改过的任务号)；不是台账 JSON 或有一方解析不了 ⇒ None。
+    """
+    if not is_ledger_json(rel):
+        return None
+    data, conflicts = merge_task_dicts(base, ours, theirs)
+    if not data:
+        return None
+    key = expand_key_of(rel)
+    if not conflicts:
+        return dump_ledger_json(data, expand=key), []
+    return (
+        _marked_text(
+            _load(theirs) or {},
+            key,
+            data,
+            conflicts,
+            _load(ours) or {},
+            _load(theirs) or {},
+        ),
+        conflicts,
+    )
+
+
+def _marked_text(
+    full: dict[str, Any],
+    key: str,
+    merged: dict[str, Any],
+    conflicts: list[str],
+    upstream: dict[str, Any],
+    local: dict[str, Any],
+) -> str:
+    """按「一条一行」渲染整份台账；两边都改过的条目用冲突标记包起来。
+
+    `full` 是本机那一侧的整份结构（version / identity / tasks），除 `key` 之外
+    原样保留 —— 分片里的 identity 丢了就没法自证。
+    """
+    rows: list[str] = []
+    for field in sorted(full):
+        if field != key:
+            rows.append(
+                f"  {json.dumps(field, ensure_ascii=False)}: "
+                f"{json.dumps(full[field], ensure_ascii=False, sort_keys=True)}"
+            )
+            continue
+        inner: list[str] = []
+        merged_rows = merged.get(key) or {}
+        for ident in sorted(merged_rows):
+            label = json.dumps(ident, ensure_ascii=False)
+            if ident not in conflicts:
+                inner.append(
+                    f"    {label}: "
+                    f"{json.dumps(merged_rows[ident], ensure_ascii=False, sort_keys=True)}"
+                )
+                continue
+            left = (
+                "(远端已删除)"
+                if _rows_of(upstream, key).get(ident) is None
+                else json.dumps(
+                    _rows_of(upstream, key)[ident], ensure_ascii=False, sort_keys=True
+                )
+            )
+            right = (
+                "(本地已删除)"
+                if _rows_of(local, key).get(ident) is None
+                else json.dumps(
+                    _rows_of(local, key)[ident], ensure_ascii=False, sort_keys=True
+                )
+            )
+            inner.append(
+                f"<<<<<<< 远端\n    {label}: {left}\n=======\n"
+                f"    {label}: {right}\n>>>>>>> 本地"
+            )
+        rows.append(
+            f'  "{key}": {{\n' + (",\n".join(inner) + "\n" if inner else "") + "  }"
+        )
+    return "{\n" + ",\n".join(rows) + "\n}\n"
+
+
+def resolve_ledger_conflict(path: Path, text: str) -> str | None:
+    """把合并结果写回冲突文件（`track=False`、不进记账本），写完由 `git rebase --continue` 提交。
+
+    返回写回的文本；`text` 为空（说明没算出合并结果）返回 None。
+    """
+    if not text:
+        return None
+    write_text_atomic(Path(path), text, track=False)
+    return text
+
+
+def render_conflict_text(rel: str, base: str, ours: str, theirs: str) -> str:
+    """人话冲突说明：**返回文本，不打印**（打印归 render.py）。"""
+    if not owns(rel):
+        return f"{rel}：不是台账文件，脚本不代劳，请人工处理。"
+    if is_append_only(rel):
+        return f"{rel}：两边都追加过，已并成一份（追加式正文，一行没丢）。"
+    data, conflicts = merge_task_dicts(base, ours, theirs)
+    if not data:
+        return f"{rel}：有一方不是合法 JSON，无法自动合并，请人工处理。"
+    if not conflicts:
+        return f"{rel}：冲突已按任务号自动合并，无需人工处理。"
+    lines = [
+        (
+            f"{rel}：这些任务被两边同时改过，已按任务逐个标出冲突"
+            "（标记里左边是远端、右边是本机），没有替你选任何一个："
+        ),
+    ]
+    lines.extend(f"  - {tid}" for tid in conflicts)
+    lines.append("  处理：编辑该文件保留你要的版本 → git add → git rebase --continue；")
+    lines.append(
+        "  不想合就 git rebase --abort 回到写之前。你的台账改动已提交在本地，不会丢。"
+    )
+    return "\n".join(lines)

package/scripts/ledgerkit/shell/presync.py

@@ -0,0 +1,23 @@
+"""取最新要刷哪些文件：**全仓唯一算锁集的地方**。
+
+返回两份 `Scope`（自举那份、动作那份）。runner 拿它做三件事：
+`sync_down(boot | act)` / `atom(*boot.files)` 包自举 / `atom(*act.files)` 包动作。
+它本来就不碰 git —— `--no-sync` 也照调。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..actions.atom import Scope, lock_scope
+from ..core.identity import Identity
+
+
+def presync_scope(
+    repo: Path, me: Identity, action: str, params: dict[str, Any]
+) -> tuple[Scope, Scope]:
+    """(自举那份, 动作那份)。只读动作由 runner 直接拿空的两份，不进这里。"""
+    boot = lock_scope(repo, me, "bootstrap", params)
+    act = Scope() if action == "bootstrap" else lock_scope(repo, me, action, params)
+    return boot, act

package/scripts/ledgerkit/shell/render.py

@@ -0,0 +1,165 @@
+"""唯一打印处。一个返回类型一个函数，**不做统一分发**；也**不 flush**。
+
+`flush_notices()` 只在 `cli.main` 的 `finally` 里调一次 —— 提交 / 推送阶段冒出来的提示也才打得到。
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+from .. import notices
+from ..actions.query import HistoryQuery, ListQuery
+from ..actions.result import (
+    HistoryResult,
+    ListResult,
+    Result,
+    ShowResult,
+    ValidationReport,
+)
+from ..core.time import fmt_local
+
+
+def _out(text: str = "") -> None:
+    sys.stdout.write(text + "\n")
+
+
+def _err(text: str) -> None:
+    sys.stderr.write(text + "\n")
+
+
+def flush_notices() -> None:
+    """把 `notices` 一次性打到 stderr（退出前调一次，同一句只打一次）。"""
+    for line in notices.warnings():
+        _err(line)
+    notices.clear()
+
+
+def fail_message(exc: BaseException, *, title: str = "错误") -> None:
+    """业务错误 / 未预期错误的 stderr 输出。"""
+    _err(f"{title}：{exc}")
+
+
+def _json(data: Any) -> None:
+    sys.stdout.write(json.dumps(data, ensure_ascii=False, indent=2) + "\n")
+
+
+def result(res: Result, *, as_json: bool) -> None:
+    """写动作：一律人话（`--json` 不挂写动作，传进来也按人话打）。"""
+    del as_json
+    if res.already_done:
+        _out("无需重复：这次没有新的改动。")
+    else:
+        _out(f"已改：{'、'.join(res.changed) if res.changed else '（无字段改动）'}")
+    if res.where:
+        _out(f"落点：{res.where}")
+    for line in res.notices:
+        _err(line)
+    if res.worklog is not None:
+        if res.worklog.path:
+            _out(f"过程文档：{res.worklog.path}")
+        elif res.worklog.error:
+            _err(f"过程文档：{res.worklog.error}")
+
+
+def list_view(res: ListResult, q: ListQuery | None, *, as_json: bool) -> None:
+    if as_json:
+        _json({tid: task for tid, task in res.rows.items()})
+        return
+    if not res.table:
+        _out("没有符合条件的在办任务。")
+        return
+    _out(f"在办 {len(res.table)} 条：")
+    for row in res.table:
+        owner = row.owner or "（未认领）"
+        _out(f"  {row.tid}  {row.status:<6} {owner:<12} {row.title}")
+    for line in res.notices:
+        _err(line)
+
+
+def show_view(res: ShowResult, *, as_json: bool) -> None:
+    if as_json:
+        _json(
+            {
+                "task": res.task,
+                "worklog": {
+                    "path": res.worklog.path if res.worklog else None,
+                    "text": res.worklog.text if res.worklog else None,
+                    "error": res.worklog.error if res.worklog else None,
+                },
+                "others": list(res.others),
+            }
+        )
+        return
+    task = res.task
+    _out(f"{task.get('tid', '')}：{task.get('title', '')}")
+    _out(
+        f"  状态：{task.get('status', '')}　负责人：{task.get('owner') or '（未认领）'}"
+    )
+    _out(
+        f"  创建：{fmt_local(task.get('created'))}　"
+        f"最后更新：{fmt_local(task.get('updated'))}"
+    )
+    if res.others:
+        _out(f"  还出现在：{'、'.join(res.others)}")
+    if res.worklog is None:
+        return
+    if res.worklog.error:
+        _err(f"  过程文档：{res.worklog.error}")
+    elif res.worklog.path:
+        _out(f"  过程文档：{res.worklog.path}")
+
+
+def history_view(res: HistoryResult, q: HistoryQuery | None, *, as_json: bool) -> None:
+    # `--count-only` 是**计数口径**：固定两个键的 JSON（§六 / ledger-data.md 第七节）。
+    # 它与 `--json` 互斥（同给即用法错），所以这里不看 as_json —— 否则那个分支永远是死代码。
+    if q is not None and q.count_only:
+        _json({"count": res.count, "capped": res.capped})
+        return
+    if as_json:
+        _json(
+            {
+                "count": res.count,
+                "filters": res.filters,
+                "records": list(res.records),
+                "warnings": list(res.warnings),
+                "capped": res.capped,
+            }
+        )
+        return
+    for line in res.warnings:
+        _err(f"警告：{line}")
+    if not res.records:
+        _out("没有符合条件的结案记录。")
+        return
+    _out(f"已结案 {res.count} 条：")
+    for row in res.records:
+        _out(
+            f"  {fmt_local(row.get('finished'))}  "
+            f"{row.get('owner') or '（无人）':<12} {row.get('title', '')}"
+        )
+
+
+def validate_view(rep: ValidationReport, *, as_json: bool) -> None:
+    if as_json:
+        _json(
+            {
+                "problems": list(rep.problems),
+                "notices": list(rep.notices),
+                "checked_files": rep.checked_files,
+                "total_tasks": rep.total_tasks,
+                "deep": rep.deep,
+            }
+        )
+        return
+    mode = "深度" if rep.deep else "浅度"
+    _out(f"体检（{mode}）：查了 {rep.checked_files} 个文件、{rep.total_tasks} 条任务。")
+    if rep.problems:
+        _out(f"问题 {len(rep.problems)} 条：")
+        for line in rep.problems:
+            _out(f"  - {line}")
+    else:
+        _out("没有问题。")
+    for line in rep.notices:
+        _err(f"提示：{line}")

package/scripts/ledgerkit/shell/runner.py

@@ -0,0 +1,225 @@
+"""七步的执行顺序：唯一创建记账本、唯一决定退出码、唯一统一回滚的地方。
+
+七步：绑记账本 → 取最新 → 自举 → 调动作 → 打印 → 提交 → 推送。
+（仓库定位在更前面，见 `run` 开头。）
+
+- `already_done` **不**跳过提交与推送（写没写只看记账本）。
+- 记账本为空 ⇒ 提交与推送都跳过（没脏文件就没得提交）。
+- **唯一不回滚的失败分支是 `BrokenPipeError`**：文件已经写完，照常提交推送。
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any
+
+from .. import notices
+from ..actions import registry
+from ..actions.atom import atom
+from ..actions.guard import current_identity
+from ..core.ids import make_id
+from ..core.paths import to_repo_rel
+from ..core.time import now, to_utc
+from ..errors import (
+    BUSINESS,
+    INTERRUPTED,
+    OK,
+    UNEXPECTED,
+    Fail,
+)
+from ..store import dirty
+from ..store.atomic import snapshot
+from . import render
+from .gitops import GitRepo
+from .presync import presync_scope
+
+
+def run(command: str, args: argparse.Namespace) -> int:
+    """跑一条命令，返回退出码。"""
+    log = dirty.WriteLog()
+    try:
+        with dirty.bound(log):
+            return _run(command, args, log)
+    except Fail as exc:
+        if log.commit_started:
+            # 提交阶段才失败：数据已落盘，回滚 = 吃掉刚写的台账（2026-10-24 修）
+            render.fail_message(exc)
+            return BUSINESS
+        log.rollback_presync()
+        log.discard_created()
+        render.fail_message(exc)
+        return BUSINESS
+    except BrokenPipeError:
+        # 唯一不回滚的分支：文件已写，按记账本照常提交推送
+        _finalize(command, args, log, broken=True)
+        return OK
+    except KeyboardInterrupt:
+        if log.commit_started:
+            return INTERRUPTED
+        log.rollback_presync()
+        log.discard_created()
+        return INTERRUPTED
+    except Exception as exc:  # noqa: BLE001 —— 兜底：任何未预期异常都要留下可诊断信息
+        if log.commit_started:
+            render.fail_message(exc, title="未预期错误")
+            return UNEXPECTED
+        log.rollback_presync()
+        log.discard_created()
+        render.fail_message(exc, title="未预期错误")
+        return UNEXPECTED
+
+
+def _run(command: str, args: argparse.Namespace, log: dirty.WriteLog) -> int:
+    spec = registry.spec_of(command)
+    repo = _repo_of(args)
+    me = current_identity(repo)
+    no_sync = bool(getattr(args, "no_sync", False))
+    as_json = bool(getattr(args, "json", False))
+
+    git = GitRepo(repo)
+    syncing = not no_sync
+    if syncing:
+        # 中间态是**全局前提**，必须早于下面任何读台账的动作（`_params` 的 `new` 快照、
+        # `presync_scope` 的锁集都要读台账）：冲突标记下的台账不是合法 JSON，读它就抛
+        # 「未预期错误」（退出码 3），而文档要的是「仓库处于中间态」这句人话。
+        git.check_repo_state()
+
+    params = _params(command, args, repo, me, spec)
+
+    # 只读：不建 GitRepo、不进事务、不提交
+    if spec.readonly:
+        value = spec.func(repo, me, **params)
+        _render(spec, value, args, as_json=as_json)
+        if getattr(value, "problems", ()):
+            return BUSINESS  # validate 有 problems ⇒ 退出码 1（§六）
+        return OK
+
+    boot_scope, act_scope = presync_scope(repo, me, spec.lock_action or command, params)
+
+    if syncing:
+        git.guard_before_write(boot_scope | act_scope)
+        for path, before in git.sync_down(boot_scope | act_scope):
+            log.record_presync(path, before)
+
+    # 自举会登记自己（改 owners.json、缺文件时建池与分片）。它碰过的文件按「命令前的字节」
+    # 记进记账本：成功时照常提交（登记必须进仓），失败时由 rollback_presync 一起还回去 ——
+    # 否则一条失败的命令会把台账留在「已写未提交」，下一条写命令被写前 guard 拦死
+    # （架构文档 §三.5 正是要避免这个）。登记是幂等的，还回去下次再登记，没有损失。
+    for rel in boot_scope.files:
+        log.record_presync(repo / to_repo_rel(rel), snapshot(repo / to_repo_rel(rel)))
+    with atom(repo, *boot_scope.files):
+        me = registry.bootstrap_func()(repo, me)
+
+    with atom(repo, *act_scope.files):
+        value = spec.func(repo, me, **params)
+
+    _render(spec, value, args, as_json=as_json)
+    _finalize(command, args, log, message=getattr(value, "message", None))
+    return OK
+
+
+def _finalize(
+    command: str,
+    args: argparse.Namespace,
+    log: dirty.WriteLog,
+    *,
+    message: str | None = None,
+    broken: bool = False,
+) -> None:
+    """提交 + 推送：要不要做只看记账本（与 `already_done` 无关，只有 `--no-sync` 才整段跳过）。"""
+    if broken:
+        try:
+            sys.stdout.close()
+        except Exception:  # noqa: BLE001, S110  # 关 stdout 本就无信息可记
+            pass
+    if getattr(args, "no_sync", False):
+        if getattr(args, "no_sync", False) and log.has_writes():
+            # 以前这条路径一个字都不打，「已写未提交」就此静默腐烂
+            notices.note(
+                "提示：--no-sync 本次只写了本地文件、未签入 git（也未推送）。\n"
+                "  处理：确认后自行 git add ledger && git commit && git push；"
+                "留着不提交的话，下一条写命令会被「本地有未提交的台账改动」拦住。"
+            )
+        log.clear()
+        return
+    if not log.has_writes():
+        log.clear()
+        return
+    repo = _repo_of(args)
+    git = GitRepo(repo)
+    if not git.is_git_repo():
+        # 没有 git 也能用：台账照写，只不做同步（2026-10-24 用户拍板）。
+        # 以前这里直接 git add，非 git 目录下必失败 ⇒ 整条命令退 1，台账像没写。
+        notices.note(
+            "提示：当前目录不是 git 仓库，台账只写了本地文件（未提交、未推送）。\n"
+            "  处理：想纳入版本管理就 git init；否则继续本地写也行 —— "
+            "多人各写各的，后写覆盖先写。"
+        )
+        log.clear()
+        return
+    log.commit_started = True
+    message = message or f"chore(ledger): {command}"
+    git.commit(log.commit_set(), message)
+    git.push()
+    log.clear()
+
+
+def _render(spec: registry.ActionSpec, value, args, *, as_json: bool) -> None:
+    func = getattr(render, spec.render)
+    if spec.render in ("list_view", "history_view"):
+        func(value, getattr(args, "q", None), as_json=as_json)
+    else:
+        func(value, as_json=as_json)
+
+
+def _params(
+    command: str, args: argparse.Namespace, repo: Path, me, spec: registry.ActionSpec
+) -> dict[str, Any]:
+    """按 `spec.params` 从 args 里挑；**不许把整个 args 透传进业务层**。"""
+    out: dict[str, Any] = {}
+    for key in spec.params:
+        out[key] = getattr(args, key, None)
+    if command == "new":
+        created = out.get("created") or now()
+        if getattr(args, "created", None):
+            created = to_utc(args.created, field="--created")
+        out["created"] = created
+        if not out.get("tid"):
+            out["tid"] = make_id(
+                out.get("title") or "", _task_snapshot(repo, me), created
+            )
+        out["tags"] = tuple(out.get("tags") or ())
+    if command == "close":
+        out["finished"] = (
+            to_utc(args.finished, field="--finished")
+            if getattr(args, "finished", None)
+            else now()
+        )
+        out["tags"] = tuple(out.get("tags") or ())
+    return out
+
+
+def _task_snapshot(repo: Path, me) -> dict[str, Any]:
+    """建任务查重要用的在办任务快照（**锁外**只读，只用于生成不撞的号）。"""
+    from ..core.paths import POOL_REL, shard_rel
+    from ..store.task_store import TaskStore
+
+    tasks: dict[str, Any] = {}
+    tasks.update(TaskStore(repo, POOL_REL).all())
+    tasks.update(TaskStore(repo, shard_rel(me.email)).all())
+    return tasks
+
+
+def _repo_of(args: argparse.Namespace) -> Path:
+    """工作区根：`cli.main` 已经解析好挂在 `args.repo` 上（定位只做一次）。
+
+    直接调 runner（测试 / 内嵌调用）时没挂过 ⇒ 现解一次，规则与 cli 一致。
+    """
+    repo = getattr(args, "repo", None)
+    if repo:
+        return Path(repo)
+    from .cli import resolve_repo  # 延迟导入：cli 在模块层 import runner
+
+    return resolve_repo(None)