task-ledger 1.3.0 → 1.3.1

package/scripts/ledgerkit/actions/guard.py

@@ -0,0 +1,140 @@
+"""业务校验的共用件：任务号形态、任务存不存在、「这条是不是你的」。
+
+**`owner` / `status` 的读取只走这里的四个谓词**：`store/` 里不许出现 `get("owner")`，
+`actions/` 里除本文件外也不许裸写字段名比较。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from ..core.identity import Identity, is_me, normalize
+from ..core.labels import LEGACY_STATUSES
+from ..core.paths import POOL_REL
+from ..errors import Fail
+from ..store.owners_index import OwnersIndex
+from ..store.task_store import TaskStore
+from .query import ListQuery
+
+
+def current_identity(repo: Path) -> Identity:
+    """env 的本机身份 + `owners.json` 里这个身份的 `aliases`（不写盘、不登记）。"""
+    from .. import env
+    from ..core.identity import with_aliases
+
+    me = env.current(repo)
+    record = OwnersIndex(repo).get(me.email) or {}
+    aliases = tuple(record.get("aliases") or ())
+    return with_aliases(me, aliases) if aliases else me
+
+
+def require_task(tasks: Mapping[str, Any], tid: str, *, where: Path) -> dict[str, Any]:
+    """取一条任务；缺失时给可读原因（带所在文件）。"""
+    task = tasks.get(tid)
+    if task is None:
+        raise Fail(f"任务 {tid} 不在 {_show(where)} 里。")
+    if not isinstance(task, dict):
+        raise Fail(f"任务 {tid} 在 {_show(where)} 里不是一条对象，台账可能坏了。")
+    return dict(task)
+
+
+def require_owner(task: Mapping[str, Any], tid: str, me: Identity) -> None:
+    """只有当前 owner 能改。"""
+    owner = owner_of(task)
+    if not owner:
+        raise Fail(f"任务 {tid} 还没有人认领（在公共池里），先 claim 再改。")
+    if not is_me(me, owner):
+        raise Fail(f"任务 {tid} 的负责人是 {owner}，不是你（{me.label()}）。")
+
+
+def same_task_ignoring_stamp(a: Mapping[str, Any], b: Mapping[str, Any]) -> bool:
+    """两份内容是不是只差 `updated`（交接重跑时以对方那份为准的判据）。"""
+    left = {k: v for k, v in a.items() if k not in ("updated", "updated_by")}
+    right = {k: v for k, v in b.items() if k not in ("updated", "updated_by")}
+    return left == right
+
+
+def owner_of(task: Mapping[str, Any]) -> str | None:
+    """读 `owner` 的唯一入口。"""
+    value = task.get("owner")
+    return normalize(value) if isinstance(value, str) and value.strip() else None
+
+
+def status_of(task: Mapping[str, Any]) -> str:
+    """读 `status` 的唯一入口；老数据 `blocked` 当进行中。"""
+    value = task.get("status")
+    if not isinstance(value, str) or not value.strip():
+        return "open"
+    value = value.strip().lower()
+    return "doing" if value in LEGACY_STATUSES else value
+
+
+def is_mine(task: Mapping[str, Any], me: Identity) -> bool:
+    """这条任务是不是我的（含 aliases）。"""
+    return is_me(me, owner_of(task) or "")
+
+
+def in_scope(task: Mapping[str, Any], q: ListQuery, *, me: Identity) -> bool:
+    """`list` 的过滤谓词：范围、状态、分类、标签、创建时间闭区间。"""
+    if q.scope == "mine" and not is_mine(task, me):
+        return False
+    if q.scope == "pool" and owner_of(task):
+        return False
+    if q.scope == "owner" and q.owner and normalize(q.owner) != owner_of(task):
+        return False
+    if q.statuses:
+        status = status_of(task)
+        wanted = {s for s in q.statuses}
+        if status not in wanted and not (
+            "doing" in wanted and status in LEGACY_STATUSES
+        ):
+            return False
+    if q.category and (task.get("category") or "") != q.category:
+        return False
+    if q.tag and q.tag not in (task.get("tags") or ()):
+        return False
+    created = task.get("created")
+    if q.since and isinstance(created, str) and created[:19] < q.since[:19]:
+        return False
+    return not (q.until and isinstance(created, str) and created[:19] > q.until[:19])
+
+
+def _show(path: Path) -> str:
+    try:
+        return str(Path(path).name)
+    except Exception:  # noqa: BLE001
+        return str(path)
+
+
+def load_task(repo: Path, tid: str) -> tuple[dict[str, Any], list[Path]]:
+    """在池 + 索引登记的全部分片里找这条任务（只读），返回 (任务, 出现过的文件)。"""
+    index = OwnersIndex(repo)
+    index.assert_present()
+    found: dict[str, Any] | None = None
+    where: list[Path] = []
+    pool = TaskStore(repo, POOL_REL)
+    if pool.get(tid):
+        found = pool.get(tid)
+        where.append(pool.path)
+    for rel in _shard_rels(repo, index):
+        store = TaskStore(repo, rel)
+        task = store.get(tid)
+        if task:
+            where.append(store.path)
+            if found is None:
+                found = task
+    if found is None:
+        raise Fail(f"找不到任务 {tid}（池与已登记的分片里都没有）。")
+    return found, where
+
+
+def _shard_rels(repo: Path, index: OwnersIndex) -> list[Path]:
+    out: list[Path] = []
+    for path in index.shards().values():
+        try:
+            out.append(path.relative_to(repo / "ledger"))
+        except ValueError:  # pragma: no cover
+            continue
+    return out

package/scripts/ledgerkit/actions/handoff.py

@@ -0,0 +1,74 @@
+"""交接：先写进对方分片，再删我分片那行，再记一笔。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..core.identity import Identity, normalize
+from ..core.paths import shard_rel
+from ..core.time import now
+from ..core.worklog_md import exec_line
+from ..errors import Fail
+from ..store.owners_index import OwnersIndex
+from ..store.task_store import TaskStore
+from ..store.worklog_store import WorklogStore
+from .guard import same_task_ignoring_stamp
+from .result import Result, rel
+
+
+def handoff(repo: Path, me: Identity, tid: str, *, to: str) -> Result:
+    """写序：对方分片 → 删我分片那行 → 过程文档记一笔。"""
+    index = OwnersIndex(repo)
+    record = index.get(to)
+    if record is None:
+        raise Fail(
+            f"{to} 还没在索引里登记过 ⇒ 不能交接给他（写出一份对别人不存在的分片，他自己也看不到）。"
+        )
+    mine = TaskStore(repo, shard_rel(me.email), identity=me)
+    task = mine.get(tid)  # 锁内重读
+    if task is None:
+        raise Fail(f"任务 {tid} 不在我的分片里，交接不了。")
+
+    to_key = normalize(to)
+    to_store = TaskStore(repo, shard_rel(to_key))
+    moved = dict(task)
+    moved["owner"] = to_key
+    moved["updated"] = now()
+
+    existing = to_store.get(tid)
+    if existing is not None:
+        if not same_task_ignoring_stamp(existing, moved):
+            raise Fail(
+                f"任务 {tid} 在 {to_key} 的分片里已经存在，且内容与本次不一致 ⇒ 拒绝交接。"
+            )
+        # 重跑：以对方那份为准，只补删我这边
+        mine.drop(tid)
+        logs = WorklogStore(repo)
+        path = logs.find(tid, moved.get("worklog"))
+        if path is not None:
+            logs.append_exec(
+                path, exec_line(now(), me.email, "set", f"交接给 {to_key}（补齐）")
+            )
+        return Result(
+            already_done=True,
+            where=rel(repo, to_store.path),
+            message=f"交接 {tid} → {to_key}：补齐上次未完成的清理",
+            notices=(f"任务 {tid} 已在对方分片里（内容一致），本次只补删我分片那行。",),
+        )
+
+    to_store.put(tid, moved)
+    mine.drop(tid)
+
+    logs = WorklogStore(repo)
+    path = logs.find(tid, moved.get("worklog"))
+    note = None
+    if path is None:
+        note = f"任务 {tid} 已交给 {to_key}，但过程文档没找到，跳过执行记录。"
+    else:
+        logs.append_exec(path, exec_line(now(), me.email, "set", f"交接给 {to_key}"))
+    return Result(
+        changed=("owner", "updated"),
+        where=rel(repo, to_store.path),
+        message=f"交接 {tid} → {to_key}",
+        notices=(note,) if note else (),
+    )

package/scripts/ledgerkit/actions/list_tasks.py

@@ -0,0 +1,53 @@
+"""只读：查在办任务（池 + 分片，后读到的为准）。不拿锁、不跑自举、不做取最新。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..core.identity import Identity
+from ..core.paths import POOL_REL
+from ..store.owners_index import OwnersIndex
+from ..store.task_store import TaskStore
+from .guard import in_scope, owner_of, status_of
+from .query import ListQuery
+from .result import ListResult, TaskRow, rel
+
+
+def list_tasks(repo: Path, me: Identity, q: ListQuery) -> ListResult:
+    """合并顺序定死：先池、再按索引键排序的各分片，同一任务号由分片那份胜出。"""
+    rows: dict[str, dict[str, Any]] = {}
+    where: dict[str, Path] = {}
+
+    pool = TaskStore(repo, POOL_REL)
+    for tid, task in pool.all().items():
+        rows[tid] = task
+        where[tid] = pool.path
+
+    index = OwnersIndex(repo)
+    index.assert_present()
+    for key in sorted(index.shards()):
+        path = index.shards()[key]
+        store = TaskStore(repo, Path(path).relative_to(repo / "ledger"))
+        for tid, task in store.all().items():
+            rows[tid] = task
+            where[tid] = store.path
+
+    kept = {tid: t for tid, t in rows.items() if in_scope(t, q, me=me)}
+    table = tuple(
+        TaskRow(
+            tid=tid,
+            title=str(task.get("title") or ""),
+            status=status_of(task),
+            owner=owner_of(task),
+            created=task.get("created"),
+            started=task.get("started"),
+            category=task.get("category"),
+            tags=tuple(task.get("tags") or ()),
+            where=rel(repo, where[tid]),
+        )
+        for tid, task in sorted(
+            kept.items(), key=lambda kv: str(kv[1].get("created") or "")
+        )
+    )
+    return ListResult(rows=kept, table=table)

package/scripts/ledgerkit/actions/log_progress.py

@@ -0,0 +1,60 @@
+"""记进展：刷分片的「最后更新」，再往过程文档追加一行。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..core.identity import Identity
+from ..core.paths import shard_rel
+from ..core.time import now
+from ..core.worklog_md import exec_line
+from ..errors import Fail
+from ..store.task_store import TaskStore
+from ..store.worklog_store import WorklogStore
+from .result import Result, rel
+
+
+def log_progress(repo: Path, me: Identity, tid: str, note: str) -> Result:
+    """写序：刷 `updated` → 过程文档追加一行。
+
+    文档写不进（`append_exec` 回 False）⇒ **不算失败**：分片已经刷了就照常提交，
+    只留一条警告 —— 抛错让外壳回滚会变成「改了又不提交」，下一条命令被写前 guard 拦死。
+    """
+    text = " ".join((note or "").split())
+    if not text:
+        raise Fail("--note 不能为空。")
+    mine = TaskStore(repo, shard_rel(me.email), identity=me)
+    task = mine.get(tid)  # 锁内重读
+    if task is None:
+        raise Fail(f"任务 {tid} 不在我的分片里（只能给自己的任务记进展）。")
+
+    updated = dict(task)
+    updated["updated"] = now()
+    mine.put(tid, updated)
+
+    logs = WorklogStore(repo)
+    path = logs.find(tid, updated.get("worklog"))
+    if path is None:
+        return Result(
+            changed=("updated",),
+            where=rel(repo, mine.path),
+            message=f"{tid}：记进展",
+            notices=(
+                "提示：这条任务没有过程文档，已跳过执行记录（分片的最后更新已刷）。",
+            ),
+        )
+    ok = logs.append_exec(path, exec_line(now(), me.email, "log", text))
+    if not ok:
+        return Result(
+            changed=("updated",),
+            where=rel(repo, mine.path),
+            message=f"{tid}：记进展",
+            notices=(
+                "警告：分片的最后更新已刷，过程文档补不上（文件不可写）；已写的分片照常提交，文档那行要手动补。",
+            ),
+        )
+    return Result(
+        changed=("updated",),
+        where=rel(repo, mine.path),
+        message=f"{tid}：记进展",
+    )

package/scripts/ledgerkit/actions/new_task.py

@@ -0,0 +1,120 @@
+"""建任务：拿外壳算好的任务号写过程文档、写进池（或直接写进自己的分片）。
+
+`tid` / `created` 由外壳算好传进来（锁层要靠它们算出那篇文档的路径），
+业务层不许现算现用；缺了就是外壳的 bug，直接 Fail。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..core.identity import Identity
+from ..core.ids import require_task_id
+from ..core.labels import normalize_label, parse_tags
+from ..core.paths import (
+    POOL_REL,
+    shard_rel,
+    to_repo_rel,
+    worklog_rel,
+)
+from ..core.worklog_md import exec_line
+from ..errors import Fail
+from ..store.atomic import ensure_dir, restore, snapshot
+from ..store.task_store import TaskStore
+from ..store.worklog_store import WorklogStore
+from .result import Result, WorklogView, rel
+
+FIELDS = ("created", "title", "status", "owner", "creator", "worklog")
+
+
+def new_task(
+    repo: Path,
+    me: Identity,
+    *,
+    title: str,
+    tid: str,
+    created: str,
+    category: str | None = None,
+    tags: tuple[str, ...] = (),
+    mine: bool = False,
+) -> Result:
+    """写序：`ensure_dir(当月文档目录)` → 过程文档（含首条记录）→ 台账。"""
+    if not (title or "").strip():
+        raise Fail("标题不能为空。")
+    if not tid:
+        raise Fail("建任务必须由外壳先算好任务号（内部错误：tid 为空）。")
+    if not created:
+        raise Fail("建任务必须由外壳先算好创建时间（内部错误：created 为空）。")
+    tid = require_task_id(tid)
+    clean_title = " ".join(title.strip().split())
+    category = normalize_label(category, field="分类") if category else None
+    tag_list = parse_tags(tags)
+
+    mine_store = TaskStore(repo, shard_rel(me.email), identity=me)
+    pool = TaskStore(repo, POOL_REL)
+    target = mine_store if mine else pool
+
+    # 查重：池 + 我自己的分片，**并且在锁内重读**（锁外的快照只配决定锁多宽）
+    if target.get(tid) is not None:
+        raise Fail(f"任务号 {tid} 已经存在了（这不是重跑，是重号）。")
+    other = pool if mine else mine_store
+    if other.get(tid) is not None:
+        raise Fail(f"任务号 {tid} 已经存在了（这不是重跑，是重号）。")
+    # 已结案的号也不能复用，且跨月同号互不干扰：直接看过程文档路径在不在。
+    # 在办任务的文档在磁盘上、已结案任务的文档也留在磁盘上 ⇒ 文档存在即这个号被占过
+    # （撞的是同一篇 worklog 文件，会覆盖 / 日后让 close 误判 already_done 变僵尸）。
+    # O(1)，不必扫历史文件。上面分片 / 池是并发安全闸门，这里补文件级的精确判重。
+    if (repo / to_repo_rel(worklog_rel(tid, created))).exists():
+        raise Fail(
+            f"任务号 {tid} 的过程文档已经存在（同名号的在办 / 已结案任务占着同一篇文档）"
+            "⇒ 换一个 --id，别复用历史号。"
+        )
+
+    doc_rel = worklog_rel(tid, created)  # 别叫 rel：那是 result.rel 的函数名
+    path = repo / to_repo_rel(doc_rel)
+    logs = WorklogStore(repo)
+    before_doc = snapshot(path)
+
+    task = {
+        "title": clean_title,
+        "created": created,
+        # --self = 建并认领：直接归自己名下就必须是在做，不留 open 半成品
+        "status": "doing" if mine else "open",
+        "owner": me.email if mine else None,
+        "creator": me.email,
+        "category": category,
+        "tags": list(tag_list),
+        "worklog": doc_rel,
+        "started": created if mine else None,
+        "updated": created,
+        "finished": None,
+    }
+    try:
+        ensure_dir(path.parent)
+        _ = logs.create(
+            tid=tid,
+            title=clean_title,
+            created=created,
+            creator=me.email,
+            category=category,
+            tags=tag_list,
+            first_exec=exec_line(
+                created, me.email, "new", "创建任务并认领" if mine else "创建任务"
+            ),
+        )
+        target.put(tid, task)
+    except Exception:
+        # 同一个 atom 内收尾：台账那条 drop 掉，文档原本不存在 ⇒ restore(None) 删掉
+        target.drop(tid)
+        restore(path, before_doc)
+        raise
+
+    text = logs.read(path)
+    return Result(
+        changed=FIELDS,
+        where=rel(repo, target.path),
+        message=f"新建任务 {tid}：{clean_title}",
+        worklog=WorklogView(path=rel(repo, path), text=text, error=None),
+        payload={"tid": tid},
+        notices=(f"新建过程文档：{rel(repo, path)}",),
+    )

package/scripts/ledgerkit/actions/query.py

@@ -0,0 +1,33 @@
+"""查询条件长什么样。外壳把命令行装成它，界面直接构造它 —— **动作层不认识 argparse**。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ListQuery:
+    scope: str = "all"  # "all" / "pool" / "mine" / "owner"
+    owner: str | None = None  # scope="owner" 时生效
+    statuses: tuple[str, ...] = ()
+    category: str | None = None
+    tag: str | None = None
+    since: str | None = None  # UTC 串，闭区间
+    until: str | None = None  # 同上
+    # `since` / `until` **一律比 `created`**（含边界，只给其一也行），不比 started / updated。
+
+
+@dataclass(frozen=True)
+class HistoryQuery:
+    owner: str | None = None
+    mine: bool = False
+    category: str | None = None
+    tag: str | None = None
+    since: str | None = None  # UTC 串，闭区间；比 finished（结案时间），不比 created
+    until: str | None = None  # 同上
+    limit: int | None = None
+    months: int | None = None  # 最近 N 个自然月；与 since/until 互斥
+    count_only: bool = False  # 只要计数，不要 records
+
+
+COUNT_CAP = 10_000  # --count-only 的封顶：超过就 capped=True

package/scripts/ledgerkit/actions/query_history.py

@@ -0,0 +1,173 @@
+"""只读：查已结案（按结案时间过滤，倒序取最近）。不写任何字节、不依赖格式升级。
+
+时间区间一律落在**结案时间** `finished` 上 —— 历史文件本来就按结案月归档
+（`history/<结案年月>.md`），按创建时间过滤会漏掉「上月建、本月结」的记录。
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from ..core import history_md
+from ..core.identity import Identity, normalize
+from ..core.paths import HISTORY_DIR, LEGACY_HISTORY_REL, month_of, to_repo_rel
+from ..core.time import now, time_key
+from ..errors import Fail
+from ..store.history_store import HistoryStore
+from .query import COUNT_CAP, HistoryQuery
+from .result import HistoryResult, rel
+
+#: 一次最多读多少个历史文件（按月分文件；不区分连续 / 分散，只数总数）。
+MAX_HISTORY_FILES = 13
+#: 没给任何时间参数时，默认只看最近几个自然月。
+DEFAULT_HISTORY_MONTHS = 3
+
+
+def _recent_month_keys(count: int) -> list[str]:
+    """最近 count 个自然月的月份键（含当月），按当前 UTC 推，从新到旧。"""
+    stamp = now()
+    year, month = int(stamp[0:4]), int(stamp[5:7])
+    keys: list[str] = []
+    for _ in range(max(count, 0)):
+        keys.append(f"{year:04d}{month:02d}")
+        month -= 1
+        if month == 0:
+            year, month = year - 1, 12
+    return keys
+
+
+def _shift_month(ym: str, delta: int) -> str:
+    """`YYYYMM` 偏移 delta 个月；越过年份边界自动进位 / 借位。"""
+    idx = int(ym[0:4]) * 12 + (int(ym[4:6]) - 1) + delta
+    return f"{idx // 12:04d}{idx % 12 + 1:02d}"
+
+
+def _month_keys_between(lo_ym: str, hi_ym: str) -> list[str]:
+    """`[lo_ym, hi_ym]` 闭区间内的月份键（升序）；两端给反了也能兜住。"""
+    if lo_ym > hi_ym:
+        lo_ym, hi_ym = hi_ym, lo_ym
+    keys: list[str] = []
+    cur = lo_ym
+    while cur <= hi_ym:
+        keys.append(cur)
+        cur = _shift_month(cur, 1)
+    return keys
+
+
+def _month_end(ym: str) -> str:
+    """`YYYYMM` 所在月的最后一秒（`YYYY-MM-DD HH:MM:SS`），用于把老平铺文件也框进区间。"""
+    year, month = int(ym[0:4]), int(ym[4:6])
+    nxt = datetime(year + (1 if month == 12 else 0), (month % 12) + 1, 1)
+    return (nxt - timedelta(seconds=1)).strftime("%Y-%m-%d %H:%M:%S")
+
+
+def _target_month_keys(q: HistoryQuery) -> list[str]:
+    """由时间参数算出「要读的月份键」；超过上限直接 Fail（不碰磁盘）。
+
+    - 无任何时间参数 ⇒ 最近 `DEFAULT_HISTORY_MONTHS` 个自然月；
+    - `--months N` ⇒ 最近 N 个自然月（与 `--since/--until` 互斥）；
+    - `--since/--until` ⇒ 结案月区间（只给一端时，另一端按默认口径补齐）。
+    """
+    if q.months is not None and (q.since or q.until):
+        raise Fail("--months 与 --since/--until 不能同时用（时间口径二选一）。")
+    if q.months is not None:
+        if q.months < 1:
+            raise Fail("--months 至少为 1。")
+        keys = _recent_month_keys(q.months)
+    elif q.since or q.until:
+        if q.since:
+            lo = month_of(q.since)
+        elif q.until:
+            # 只给 --until：往前补到默认窗口（与「默认近 3 月」一致）
+            lo = _shift_month(month_of(q.until), -(DEFAULT_HISTORY_MONTHS - 1))
+        else:  # pragma: no cover - 上面已保证至少给了一个
+            raise Fail("--since/--until 至少要给一个。")
+        hi = month_of(q.until) if q.until else month_of(now())
+        if not lo or not hi:
+            raise Fail("--since/--until 时间格式不对，算不出月份。")
+        keys = _month_keys_between(lo, hi)
+    else:
+        keys = _recent_month_keys(DEFAULT_HISTORY_MONTHS)
+    # 上限卡的是「要读的文件总数」，不是月跨度：按月分文件，一个键一个文件；
+    # 连不连续、将来把多段时间拼在一起也都只数总数。
+    files = sorted(set(keys))
+    if len(files) > MAX_HISTORY_FILES:
+        raise Fail(
+            f"历史查询一次最多读 {MAX_HISTORY_FILES} 个历史文件（按月分文件，不区分连续/分散），"
+            f"本次要读 {len(files)} 个 ⇒ 缩小 --since/--until 或 --months。"
+        )
+    return files
+
+
+def _candidate_paths(repo: Path, keys: list[str]) -> list[Path]:
+    """按月键【直接拼】`history/<年月>.md`（不扫磁盘）；存量平铺文件按固定路径顺带一看。"""
+    paths = [repo / to_repo_rel(HISTORY_DIR / f"{ym}.md") for ym in keys]
+    paths.append(repo / to_repo_rel(LEGACY_HISTORY_REL))
+    return paths
+
+
+def query_history(repo: Path, me: Identity, q: HistoryQuery) -> HistoryResult:
+    """`--owner` / `--mine` 一律**精确相等**（不做前缀 / 子串）；`--since` / `--until` 比 `finished`（结案时间）。"""
+    keys = _target_month_keys(q)
+    store = HistoryStore(repo)
+    records: list[dict[str, Any]] = []
+    warnings: list[str] = []
+    for path in _candidate_paths(repo, keys):
+        if not path.is_file():
+            continue  # 该月无记录 / 老平铺文件不存在 ⇒ 跳过，不报错
+        rows, warns = history_md.parse_history(store.read(path))
+        warnings.extend(f"{rel(repo, path)}：{w}" for w in warns)
+        for row in rows:
+            row = dict(row)
+            row["src"] = rel(repo, path)
+            row["created"] = time_key(row.get("created") or "") or row.get("created")
+            row["finished"] = time_key(row.get("finished") or "") or row.get("finished")
+            records.append(row)
+
+    if q.mine:
+        wanted = {k for k in (me.email, *me.aliases) if k}
+        wanted = {normalize(k) for k in wanted}
+        records = [r for r in records if normalize(r.get("owner") or "") in wanted]
+    elif q.owner:
+        key = normalize(q.owner)
+        records = [r for r in records if normalize(r.get("owner") or "") == key]
+    if q.category:
+        records = [r for r in records if (r.get("category") or "") == q.category]
+    if q.tag:
+        records = [r for r in records if q.tag in (r.get("tags") or ())]
+
+    # 有效结案区间：显式 --since/--until 优先（精确到秒），缺的一端用月份窗口补，
+    # 这样老平铺文件里的行也会被同一条规则框住，不会在月份查询里「漏网」。
+    lo_key, hi_key = min(keys), max(keys)
+    eff_since = q.since or f"{lo_key[0:4]}-{lo_key[4:6]}-01 00:00:00"
+    eff_until = q.until or _month_end(hi_key)
+    records = [r for r in records if (r.get("finished") or "") >= eff_since]
+    records = [r for r in records if (r.get("finished") or "") <= eff_until]
+
+    records.sort(key=lambda r: str(r.get("finished") or ""), reverse=True)
+    capped = False
+    if q.count_only and len(records) > COUNT_CAP:
+        capped = True
+        records = records[:COUNT_CAP]
+    elif q.limit:
+        records = records[: int(q.limit)]
+
+    filters = {
+        "owner": q.owner,
+        "mine": q.mine,
+        "category": q.category,
+        "tag": q.tag,
+        "since": q.since,
+        "until": q.until,
+        "limit": q.limit,
+        "months": q.months,
+    }
+    return HistoryResult(
+        count=len(records),
+        filters=filters,
+        records=tuple(records),
+        warnings=tuple(warnings),
+        capped=capped,
+    )