claude-code-session-sync 0.1.0__py3-none-any.whl

claude_code_session_sync-0.1.0.dist-info/METADATA

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: claude-code-session-sync
+Version: 0.1.0
+Summary: Offline cross-machine sync for Claude Code sessions (JSONL) and memory (.md).
+Author: weilung
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/weilung/claude-session-sync
+Project-URL: Repository, https://github.com/weilung/claude-session-sync
+Project-URL: Issues, https://github.com/weilung/claude-session-sync/issues
+Project-URL: Changelog, https://github.com/weilung/claude-session-sync/blob/main/CHANGELOG.md
+Keywords: claude,claude-code,sync,sessions,memory,jsonl,offline
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# claude-session-sync
+
+讓 Claude Code 的**對話 session（JSONL）與 memory（.md）**透過**外接 / 網路硬碟**在多台機器間離線同步的 CLI 工具。
+
+- 同群組多台共用一個 hub 目錄**雙向同步**；跨群組**明確、可挑選**地引入/送回特定 session。
+- 核心原則：**機械的事交給 Python，語意的事交給 AI；永不靜默丟資料。**
+- 與現成工具的差異：離線（不強制上雲/git）＋可挑選＋AI 輔助 memory 合併＋多寫入者安全。
+
+## 現況
+
+**核心功能已實作並收斂**（跨模型 code review + 逐塊 fresh-gate；跨平台，Windows 綠）。
+
+- 已完成：唯讀掃描/分類 → `sync` 雙向同步（安全寫入：read-verify-write + lock + tombstone + keep-both）、
+  跨群 `pull`/`push`、`bootstrap` 基線、`doctor` 診斷/rebuild-state/break-lock/ack、
+  memory union + tombstone + `MEMORY.md` 索引重建、`memory-merge`（含跨群 `--from` 與模糊近似 `--fuzzy`）、SessionEnd `nudge` hook。
+- memory「同事實不同檔名」的**模糊近似比對**（P2 最後一項、最高風險）已完成——刻意只做**唯讀建議**（`memory-merge --fuzzy` 列候選、由你逐對放行才保留兩版，**絕不自動合併**）。
+- 首個公開版 **0.1.0（beta）**；尚未到 1.0 穩定版，介面/行為仍可能調整。
+
+## 安裝
+
+```bash
+# 從 PyPI（推薦）— 套件名 claude-code-session-sync，安裝後指令仍是 claude-session-sync
+pipx install claude-code-session-sync   # 或： pip install claude-code-session-sync
+
+# 或從原始碼安裝最新版
+pipx install "git+https://github.com/weilung/claude-session-sync.git"
+```
+
+需 Python ≥ 3.11、零第三方相依（標準庫）。安裝後即有 `claude-session-sync` 指令。
+
+## 快速開始
+
+```bash
+# 1) 設定自己群組的 hub（編輯設定檔；Windows 路徑用單引號）
+#    Windows: %APPDATA%\claude-session-sync\config.toml
+#    POSIX:   ~/.config/claude-session-sync/config.toml
+#    own_hub = 'D:\SyncDrive\HomeJSONL'
+
+# 2) 第一次先建基線
+claude-session-sync bootstrap --map "本機專案夾=hub專案夾" --yes
+
+# 3) 日常同步（先預覽，再 --apply 落地）
+claude-session-sync status          # 看差異（純唯讀）
+claude-session-sync sync            # 預覽
+claude-session-sync sync --apply    # 落地
+```
+
+（開發環境未安裝時，等價寫法為 `python -m claude_session_sync.cli <子指令>`。）
+
+## 文件
+
+- **[`docs/`](docs/README.md) — 使用者指南（白話版）**：不需要懂程式，講清楚「做什麼、怎麼安全、怎麼用」。
+  - [概念與運作](docs/01-概念與運作.md) ｜ [安全機制白話](docs/02-安全機制白話.md) ｜ [指令手冊](docs/03-指令手冊.md)
+  - [情境劇本](docs/04-情境劇本.md) ｜ [Windows 與已知限制](docs/05-windows-與已知限制.md) ｜ [名詞對照](docs/06-名詞對照.md)
+
+## 開發
+
+```bash
+python -m unittest discover -t . -s tests
+```
+
+純 Python、零第三方相依（標準庫）。跨 OS CI 於 Ubuntu + Windows 跑 py3.11/3.13。

claude_code_session_sync-0.1.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+claude_code_session_sync-0.1.0.dist-info/licenses/LICENSE,sha256=nkzV9VJScNHPuadWPypvUFVzNTMXGqsMrfDUHZ-QGVw,1064
+claude_session_sync/__init__.py,sha256=5OGFH_TrJq-If5oS_s-0W8yb34SOQfoTBr3gLZtxKws,489
+claude_session_sync/acks.py,sha256=UcVC9m6QB8joxX8iVY9loKHoDZx2it7EM9X1UGJWl7o,17610
+claude_session_sync/anomaly.py,sha256=C_QoR_kVirvHz01RVz6JLJK_QFrGxq9vE0N6db7W9sM,9510
+claude_session_sync/apply.py,sha256=dVDckRvpIRSvkouyjZCOPhlOrge8M5XYbCM4hDuH_Gc,63096
+claude_session_sync/atomicio.py,sha256=3lRrMgjYjFvpMF6hUhAtbe0CMMnNKmq1HTeF8YRRlyE,30323
+claude_session_sync/bootstrap.py,sha256=1cEcI7xfVhi9TXgjKYGWcmn3gIq_A2wXagSEGTISUSY,22304
+claude_session_sync/canonical.py,sha256=sRZs1I1RBZRuy_TamdDCurD_CGvJmq_k7a_9expCfRQ,6497
+claude_session_sync/classify.py,sha256=M5HJRuOk9myn5zbU0_X7KJerg0i76qVf0U-5Fcz_Szs,6756
+claude_session_sync/cli.py,sha256=QrFCCwl0CvYmpgr9QGi63h0eQ2YOQ2vIsoMFmK6ggGs,62446
+claude_session_sync/config.py,sha256=0XSkBIuXr9i3k1ptWkb_IO-B_X-c9gMi0ND9XCxnJ8A,4960
+claude_session_sync/doctor.py,sha256=FbX9lU8QnR9shhNKXyijiPnda08frW3miEEO0OBJJio,19526
+claude_session_sync/fuzzy.py,sha256=P2nxuVmQHg8wDCliOg56M21bFLh05fuDOGlzoDMi4Ug,7258
+claude_session_sync/lineset.py,sha256=XChbVTiZwjoqH3bWKLUnn4CN590iQq07PZAlWxQ_B3w,5890
+claude_session_sync/memory.py,sha256=t0MAkbvIWae1J1w-iqR4R4hT322gzwTd2oIK4gLHhuE,68323
+claude_session_sync/merge.py,sha256=4ID7DoHmFZyIeXXm180t3w9B5hWmRT3qBgX2WJSn0aI,55886
+claude_session_sync/pathsafe.py,sha256=KUCxhU-qTVzfPgibbAlS6Drp9E5rr6mxpas4nBStkkk,5291
+claude_session_sync/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+claude_session_sync/resolve.py,sha256=ES5YwNDNJzrYQEg-lNoH7FORZop_adNdhaRNNyIeUMM,11936
+claude_session_sync/scan.py,sha256=xivMpXUizbvIy8sx7k3gMhBRyYiGQvhY1guKzoPeHHI,29492
+claude_session_sync/session_merge.py,sha256=5Q5GiyvvW3_xVnkdEpTJdYawovCE7tm5X6fP0zsxepY,10304
+claude_session_sync/sidecar.py,sha256=FKqHw-nxIGyBcQp4isrpk2oR4Cg5nODA4o2kCOpeLms,9360
+claude_session_sync/snapshot.py,sha256=6OcyeSlF-Wjeafd6aEz16mmgVxXlQLaEkBdo6zBVnTM,7026
+claude_session_sync/state.py,sha256=PNoDm8xN4dRHkvCiE7B5xWTbed7MC8ZElrrTBco9L6M,12109
+claude_session_sync/tombstone.py,sha256=higglM06WfClIfWt_JDbYkXeG-6sTIA4CcizPMDQKQU,18003
+claude_session_sync/transfer.py,sha256=d0Udb8XXJJ0b_Anwjy2u1Dwr8Ub_2FSeOjS9tQCMI-w,26668
+claude_code_session_sync-0.1.0.dist-info/METADATA,sha256=maj1R7CukDlQjKXSSRoMr93lfSOMyU3eZw-ukvRziGw,4159
+claude_code_session_sync-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+claude_code_session_sync-0.1.0.dist-info/entry_points.txt,sha256=uRISCzJtnCBJO9qM9xus_kyXmRJ0m5Lsew9Cm8buw4o,69
+claude_code_session_sync-0.1.0.dist-info/top_level.txt,sha256=Cr8U4xm_8iwtkaCRNXeG8-rU2KmET9GyHhM5Zo0g6NU,20
+claude_code_session_sync-0.1.0.dist-info/RECORD,,

claude_code_session_sync-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

claude_code_session_sync-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+claude-session-sync = claude_session_sync.cli:main

claude_code_session_sync-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 weilung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claude_code_session_sync-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+claude_session_sync

claude_session_sync/__init__.py

@@ -0,0 +1,11 @@
+"""claude-session-sync — 跨機同步 Claude Code 的 session(JSONL) 與 memory(.md)。
+
+P1a 唯讀核心（已實作）：
+  - canonical：編碼吸收 + canonical hash + 行解析（三態：ok / zero-byte / blank / decode-error）
+  - lineset：行身分、root-set、genuine leaf、active-tip
+  - classify：§4.1 分類表 + 安全閘 + main-root 相容性 + active-tip 交叉驗
+
+依據 DESIGN.md v0.4 附錄 B（P0 spike 定案）與 PLAN-P1.md v0.3。
+"""
+
+__version__ = "0.1.0"

claude_session_sync/acks.py

@@ -0,0 +1,279 @@
+"""ack 帳本：對「工具永遠無法自動解決」的 blocked 項（damaged / casefold-collision / identity-collision）
+記錄「已審閱」，讓 doctor/sync 不再反覆回報（DESIGN 附錄 A15「blocked 收斂出口」）。
+
+**安全鐵則**：
+  1. **純呈現層**：ack 只抑制「回報」，**絕不改變分類**——acked 的 damaged 仍永不同步、acked 的 collision 仍永不
+     自動合併。本帳本從不進 `build_plan`/`classify`/`apply`，故結構上不可能把 blocked 變成 auto-apply。呈現層
+     （`format_plan` / `doctor.diagnose`）以 `AckView` 隱藏/降級 acked 項，分類與寫入路徑一律看不到本模組。
+  2. **fingerprint 綁定**：ack 記 `(kind, identity, fingerprint)`。現況 fingerprint 不符（damaged 檔內容改、
+     撞名集合變）→ 視為**未** ack、照常重報——不遮蓋新的/變動過的問題。
+  3. **fail-closed 讀**：帳本缺 → 無 ack（全部照常回報，`ok=True`）；壞/讀不到 → 忽略整本（`ok=False`，呼叫端
+     警告，仍全部照常回報）；壞條目 → 跳過該條、不毒化整本。`.tombstones/` 為 symlink/逃逸 → **不信任、不
+     suppress**（回空、`ok=True`）。任一路徑都**只會少 suppress、不會多 suppress**。
+  4. **A3 不丟**：ack 只寫一個 hub 側 per-project JSON（`<proj>/.tombstones/acks.json`），**絕不動 session/
+     memory 檔**。落點在 `.tombstones/`（已被 scan 排除、不會被當 session/專案）；寫走 atomicio 原子寫 + 專屬鎖。
+
+範圍（v1，session 側）：casefold-collision（A9 檔名撞名，兩份都是真 session）、damaged / blocked-damaged-source
+（壞 JSONL）、identity-collision（同 uuid 異 hash 的內容身分衝突）。memory 側對應項留 follow-on。
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from . import atomicio, pathsafe, scan, tombstone
+
+SCHEMA_VERSION = 1
+ACKS_FILE = "acks.json"
+
+# ackable 的 plan action → ack kind。casefold-collision 以 casefold key 為身分（一項含整組 sid）；
+# damaged / identity-collision 以 sid 為身分（指紋看兩側檔 bytes）。
+_ACTION_KIND: dict[str, str] = {
+    "blocked-casefold-collision": "casefold-collision",
+    "blocked-damaged-source": "damaged",
+    "damaged": "damaged",
+    "identity-collision": "identity-collision",
+}
+_KINDS = frozenset(_ACTION_KIND.values())
+# 可 ack 的 plan action 字串（供 apply.format_report 呈現層過濾）。**單一真相源在 `scan.ACKABLE_ACTIONS`**（scan 被
+# acks 依賴、不可反向 import）；`_ACTION_KIND` 的鍵須與之一致（test_acks 有漂移守衛）。
+ACKABLE_ACTIONS = scan.ACKABLE_ACTIONS
+
+
+class UnsafeAcksDir(OSError):
+    """`<proj>/.tombstones` 是 symlink 或逃逸專案夾（指界外）→ 拒寫 acks（否則寫到信任根外）。"""
+
+
+@dataclass(frozen=True)
+class AckItem:
+    """一個可 ack 的 blocked 項（doctor / format_plan / ack 寫入的**單一真相源**，由 `ackable_from_plan` 產）。"""
+    project: str                    # hub 專案夾名（pk）
+    hub_dir: str                    # hub 專案夾路徑；ledger 落點 = <hub_dir>/.tombstones/acks.json
+    kind: str                       # casefold-collision | damaged | identity-collision
+    identity: str                   # collision: casefold key；damaged/identity: sid
+    fingerprint: str | None         # 現況指紋（見 fingerprint_*）；None＝不可綁定內容（讀不到）→ 不可 ack、不被隱藏（g6）
+    session_ids: tuple[str, ...]    # 此項涵蓋的 sid（collision=整組；其餘=單一）——供呈現層隱藏對應行
+    label: str                      # 顯示用短標籤
+
+
+@dataclass
+class Ledger:
+    """載入後的 acks.json。`by_key` 以 **(kind, identity, fingerprint) 三元組**為鍵（同一 (kind,identity) 可有多個
+    fingerprint 並存，g2）；`ok=False` 表帳本損壞/讀不到（已忽略，呼叫端警告）。"""
+    by_key: dict[tuple[str, str, str], dict] = field(default_factory=dict)
+    ok: bool = True
+    path: Path | None = None
+
+
+# ── fingerprint ─────────────────────────────────────────────────────────────
+
+def fingerprint_collision(names, local_files=None, hub_files=None) -> str | None:
+    """撞名項指紋 = 撞名集（排序拼法）＋**各撞名檔兩側 raw bytes digest**。新拼法加入/移除 → 集變 → 指紋變；
+    某撞名檔內容改（變 damaged／換成別的 session）→ digest 變 → 指紋變 → 重報。**為何也綁內容**（g4）：
+    `classify_session` 的撞名閘**先於** damaged 閘 → 撞名檔之一變壞仍分類為 collision，若 fp 只看名稱，collision ack
+    會遮蓋「撞名檔變 damaged」這個新情況；綁內容使「撞名檔變了」重新提示。**回 `None`** 若某撞名檔 present 但讀不到
+    （不可綁定內容 → 不列為 ackable，fail-closed，g5 Medium）。`*_files` 由 `scan._session_files` 提供（已排除 symlink）；
+    未給（如非比對用的直接呼叫）→ 視為兩側皆無檔。"""
+    lf, hf = local_files or {}, hub_files or {}
+    parts = ["\n".join(sorted(names))]
+    for n in sorted(names):
+        fpf = fingerprint_files(lf.get(n), hf.get(n))
+        if fpf is None:
+            return None                         # 某撞名檔讀不到 → 不可綁定 → 不可 ack（fail-closed）
+        parts.append(fpf)
+    return "cf:" + hashlib.sha256("|".join(parts).encode("utf-8")).hexdigest()
+
+
+def fingerprint_files(*paths: Path | None) -> str | None:
+    """damaged / identity-collision 指紋 = 兩側檔 raw bytes digest 的組合。任一側內容改/消失 → 指紋變 → 重報。
+    **回 `None`** 若某 present 檔讀不到（unreadable，`raw_file_digest`→None）→ 呼叫端（ackable_from_plan）視為
+    **不可綁定內容 → 不列為 ackable、永遠照報**（fail-closed，g5 Medium：不可綁定則 fp 無法反映內容變動，read-denied
+    檔內容變會被舊 ack 遮蓋）。缺檔（None path）→ "-"（可綁定為「該側無此檔」）。path 僅由 `scan._session_files`
+    提供（已排除 symlink），故 `raw_file_digest`（會跟隨 symlink）不會讀到界外檔。"""
+    parts: list[str] = []
+    for p in paths:
+        if p is None:
+            parts.append("-")                       # 該側無此檔（可綁定）
+        else:
+            d = tombstone.raw_file_digest(p)
+            if d is None:
+                return None                         # present 但讀不到 → 不可綁定內容（fail-closed）
+            parts.append(d)
+    return "fs:" + hashlib.sha256("|".join(parts).encode("utf-8")).hexdigest()
+
+
+# ── 從 plan 抽 ackable 項（單一真相源）─────────────────────────────────────────
+
+def ackable_from_plan(plan) -> list[AckItem]:
+    """從 `SyncPlan` 抽出所有可 ack 的 session 側 blocked 項。**只含有 hub_dir 的專案**（ack 帳本 hub 側；
+    local-only 專案尚未上 hub、還不是同步問題，不納入）。撞名依 casefold key 併組（整組一項）。"""
+    out: list[AckItem] = []
+    for pp in plan.projects:
+        if not pp.hub_dir:
+            continue
+        pk = Path(pp.hub_dir).name
+        coll: dict[str, set[str]] = {}
+        filebased: list[tuple[str, str]] = []   # (sid, kind) for damaged / identity-collision
+        for s in pp.sessions:
+            kind = _ACTION_KIND.get(s.action)
+            if kind is None:
+                continue
+            if kind == "casefold-collision":
+                coll.setdefault(s.session_id.casefold(), set()).add(s.session_id)
+            else:
+                filebased.append((s.session_id, kind))
+        if not coll and not filebased:
+            continue
+        # collision 與 damaged/identity 皆需讀撞名/壞檔內容算指紋（g4：collision fp 亦綁內容）→ 有 ackable 項就讀。
+        # 用 `_session_files`（已排除 symlink）取真實檔路徑，確保指紋只看工具本就會處理的實體檔。
+        local_files = scan._session_files(Path(pp.local_dir)) if pp.local_dir else {}
+        hub_files = scan._session_files(Path(pp.hub_dir))
+        # 不可綁定（讀不到內容）→ fp=None：**仍列出**（不 skip）。fingerprint=None → is_acked 恆 False → compute_ack_view
+        # 不會隱藏該 (pk,sid)（fail-closed，g6：若整個 skip 掉，同 hub 另一 view 對同 sid 的 ack 會讓此 sid 看似「所有涵蓋
+        # 項都已 ack」而誤藏這個不可綁定行）。`_doctor_ack` 另會濾掉 fp=None 者（不可 ack、無從綁定內容變動）。
+        for cf, sids in sorted(coll.items()):
+            names = sorted(sids)
+            out.append(AckItem(pk, pp.hub_dir, "casefold-collision", cf,
+                               fingerprint_collision(names, local_files, hub_files), tuple(names),
+                               "/".join(n[:8] for n in names)))
+        for sid, kind in sorted(filebased):
+            out.append(AckItem(pk, pp.hub_dir, kind, sid,
+                               fingerprint_files(local_files.get(sid), hub_files.get(sid)), (sid,), sid[:8]))
+    return out
+
+
+# ── 帳本讀（lock-free、fail-closed）────────────────────────────────────────────
+
+def load_ledger(hub_project_dir) -> Ledger:
+    """讀 `<hub_project_dir>/.tombstones/acks.json`。fail-closed：缺 → 空 `ok=True`；壞/讀不到 → 空 `ok=False`；
+    `.tombstones` 不安全 → 空 `ok=True`（不信任、不 suppress）。**任一情況都只會少 suppress，不會多 suppress**。"""
+    tdir = tombstone.tombstones_dir(hub_project_dir)
+    path = tdir / ACKS_FILE
+    if not tombstone._tombstones_ok(hub_project_dir):
+        return Ledger({}, True, path)          # symlink/逃逸 .tombstones → 不信任其內容、不 suppress
+    if pathsafe.is_reparse(path):
+        # `.tombstones` 是真夾但 `acks.json` **本身**是 symlink/reparse → `read_bytes()` 會跟隨讀界外／被植入的帳本
+        # → 不信任、不 suppress（fail-closed，g1 High；leaf 防線，補 `_tombstones_ok` 只管父夾）。
+        return Ledger({}, True, path)
+    try:
+        raw = path.read_bytes()
+    except FileNotFoundError:
+        return Ledger({}, True, path)          # 尚無帳本 → 無 ack（正常）
+    except OSError:
+        return Ledger({}, False, path)         # 讀不到（權限等）→ fail-closed 忽略
+    try:
+        obj = json.loads(raw.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        return Ledger({}, False, path)         # 壞 JSON → 忽略整本
+    version = obj.get("version") if isinstance(obj, dict) else None
+    # `type(version) is int`：**拒 bool/float**——Python 中 `True == 1`、`1.0 == 1` 皆真，若只寫 `version == 1`
+    # 則 `{"version": true}` / `{"version": 1.0}` 會被當合法版本放行 → 壞帳本可 suppress 真問題（R1 High#1，
+    # 對稱 tombstone `_valid_tombstone` 的型別 fail-closed）。
+    if not (type(version) is int and version == SCHEMA_VERSION and isinstance(obj.get("acks"), list)):
+        return Ledger({}, False, path)         # 版本不符/型別錯/結構壞 → 忽略整本
+    by_key: dict[tuple[str, str, str], dict] = {}
+    for rec in obj["acks"]:
+        if not isinstance(rec, dict):
+            continue                            # 壞條目跳過（不毒化整本）
+        k, i, fp = rec.get("kind"), rec.get("identity"), rec.get("fingerprint")
+        if isinstance(k, str) and isinstance(i, str) and isinstance(fp, str) and k in _KINDS:
+            by_key[(k, i, fp)] = rec            # 以 **(kind,identity,fingerprint) 三元組**為鍵：同一 (kind,identity)
+            #   可有多個 fp 並存（同 hub 專案被多個 local 夾映射時 damaged 的內容 fp 不同，g2）——不互蓋。
+    return Ledger(by_key, True, path)
+
+
+def is_acked(ledger: Ledger, kind: str, identity: str, fingerprint: str | None) -> bool:
+    """該 (kind, identity, fingerprint) 三元組是否在帳本內（**fp-exact**：指紋不符＝內容/撞名集已變 → 未 ack）。
+    `fingerprint=None`（不可綁定內容）→ **恆 False**（fail-closed：讀不到內容者不可能『已 ack』、也不該被隱藏，g6）。"""
+    return fingerprint is not None and (kind, identity, fingerprint) in ledger.by_key
+
+
+# ── ack view（呈現層過濾：format_plan / doctor 共用）────────────────────────────
+
+@dataclass
+class AckView:
+    """呈現層過濾視圖。`hidden[pk]` = 該專案要隱藏的 session_id 集（見 compute_ack_view 的 fail-safe 規則）；
+    `corrupt_projects` = 帳本損壞的專案（呼叫端警告）。隱藏行數由各 renderer 自行計。"""
+    hidden: dict[str, set[str]] = field(default_factory=dict)
+    corrupt_projects: list[str] = field(default_factory=list)
+
+
+def compute_ack_view(plan) -> AckView:
+    """對 plan 的每個 ackable 項查對應專案帳本（每專案讀一次），算出要隱藏的 session_id。純讀、lock-free。
+
+    **fail-safe 隱藏**：某 `(pk, sid)` 只在「**涵蓋它的所有 ackable 項都 fp-exact 已 ack**」時才隱藏——否則不藏。
+    因同一 hub 專案可被多個 local 夾映射（兩 cwd 綁定／兩 clone），同一 sid 的 damaged 內容 fp 可不同 → 兩個
+    AckItem 共用 `(pk, sid)`；若只 ack 其一就用 `(pk,sid)` 藏，會誤藏另一個未 ack 的（遮蓋真問題，g2 High）。
+    寧可多顯示已 ack 項，也不誤藏未 ack 的同 sid 項。（collision 的 fp 只看名稱集、跨 view 相同，本規則對它無副作用。）"""
+    view = AckView()
+    by_dir: dict[str, list[AckItem]] = {}
+    for it in ackable_from_plan(plan):
+        by_dir.setdefault(it.hub_dir, []).append(it)
+    for hub_dir, its in by_dir.items():
+        led = load_ledger(hub_dir)
+        pk = its[0].project
+        if not led.ok:
+            view.corrupt_projects.append(pk)
+        sid_all_acked: dict[str, bool] = {}     # sid → 涵蓋它的**所有**項是否都已 ack（AND）
+        for it in its:
+            acked = is_acked(led, it.kind, it.identity, it.fingerprint)
+            for sid in it.session_ids:
+                sid_all_acked[sid] = sid_all_acked.get(sid, True) and acked
+        hide = {sid for sid, ok in sid_all_acked.items() if ok}
+        if hide:
+            view.hidden.setdefault(pk, set()).update(hide)
+    return view
+
+
+# ── 帳本寫（加鎖 read-modify-write、atomic）─────────────────────────────────────
+
+@dataclass
+class UpdateResult:
+    added: list[str] = field(default_factory=list)      # 新 ack / 更新指紋的 label
+    removed: list[str] = field(default_factory=list)     # 取消 ack 的 label
+    unchanged: list[str] = field(default_factory=list)   # 已 ack 且指紋相符（無變更）
+    replaced_corrupt: bool = False                       # 原帳本損壞、已以新內容取代（呼叫端告知）
+
+
+def update_ledger(hub_project_dir, *, add=(), remove=(), lock_timeout_s: float = 5.0) -> UpdateResult:
+    """加鎖 read-modify-write 一個專案帳本。`add`：`list[AckItem]`（以 (kind,identity,fingerprint) 三元組為鍵——
+    同 (kind,identity) 不同 fp **並存不互蓋**，g2）；`remove`：`list[(kind, identity, fingerprint)]`（load_ledger 暴露
+    的三元組鍵）。鎖內重讀（並發 ack 合併、不互蓋）；原子寫。`.tombstones` 不安全 → raise。"""
+    tdir = tombstone.tombstones_dir(hub_project_dir)
+    if not tombstone._tombstones_ok(hub_project_dir):
+        raise UnsafeAcksDir(f".tombstones 為 symlink 或逃逸專案夾，拒絕寫入 acks：{tdir}")
+    path = tdir / ACKS_FILE
+    res = UpdateResult()
+    lock = atomicio.FileLock(path).acquire_blocking(timeout_s=lock_timeout_s)
+    try:
+        led = load_ledger(hub_project_dir)     # 鎖內重讀
+        res.replaced_corrupt = not led.ok      # 損壞帳本會被本次寫入取代（原本就已被忽略、不 suppress 任何項）
+        by_key = dict(led.by_key)
+        for it in add:
+            key = (it.kind, it.identity, it.fingerprint)
+            if key in by_key:
+                res.unchanged.append(it.label)
+                continue
+            by_key[key] = {
+                "kind": it.kind, "identity": it.identity, "fingerprint": it.fingerprint,
+                "label": it.label, "acked_at": tombstone.now_iso(),
+                "acked_by": tombstone.local_machine_id(),
+            }
+            res.added.append(it.label)
+        for key in remove:
+            rec = by_key.pop(key, None)
+            if rec is not None:
+                res.removed.append(rec.get("label") or key[1])
+        _write_ledger(path, by_key)
+        return res
+    finally:
+        lock.release()
+
+
+def _write_ledger(path: Path, by_key: dict[tuple[str, str, str], dict]) -> None:
+    acks = sorted(by_key.values(),
+                  key=lambda r: (r.get("kind", ""), r.get("identity", ""), r.get("fingerprint", "")))
+    obj = {"version": SCHEMA_VERSION, "acks": acks}
+    atomicio.atomic_write_text(path, json.dumps(obj, ensure_ascii=False, indent=2))

claude_session_sync/anomaly.py

@@ -0,0 +1,161 @@
+"""存在性異常偵測（§8.5）：任何 apply 前阻斷，擋「掛錯碟/空掛載/hub 突變/已知 session 大量消失」。
+
+依據 DESIGN §8.5 + PLAN v0.8 §2.9 + codex r6 必補②（已知 session 大量消失偵測）：
+靠**存在性**而非百分比門檻去抓「整體不對」——掛載點不在 / hub 夾名指紋變 → halt；
+**已知 session 大量從 hub 消失**（夾名沒變但內容被清/部分同步/誤掛）也 halt。
+
+約定（全工具共用）：state.known_sessions 的 key = **hub 專案夾名**（hub_root 底下的編碼夾名），
+bindings 的 value 亦同。anomaly 才能由 project_key 直接定位 hub_root/<project_key>。
+
+P1a 起：mount + hub-fingerprint；P1b 加 known-session 大量消失（coarse 安全網，預設高門檻避免誤殺）。
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from .pathsafe import safe_project_dir   # leaf；逃逸 pk 夾不讀界外（e2e gate2 #4，無循環）
+from .state import State
+
+# 大量消失門檻（coarse 安全網；寧可偶爾要使用者確認，也不靜默吃掉「掛錯/被清空」）。
+DISAPPEAR_MIN_KNOWN = 8       # **全體**已知 session 總數低於此值不觸發全域判定（樣本太小）
+DISAPPEAR_FRAC = 0.6         # 消失比例達此值 → halt（全域或單專案）
+PROJECT_VANISH_MIN = 4       # **單專案**已知數達此值即納入個別判定（避免大專案稀釋掉小專案被整夾清空）
+
+
+@dataclass
+class Anomaly:
+    code: str
+    message: str
+    severity: str  # "halt" | "warn"
+
+
+def hub_fingerprint(hub_root: str | Path) -> str:
+    """hub 的存在性指紋：所有專案夾名（排序）的雜湊。掛錯碟 → 夾名集合大不同 → 指紋變。"""
+    root = Path(hub_root)
+    names = sorted(d.name for d in root.iterdir() if d.is_dir()) if root.exists() else []
+    return hashlib.sha256(json.dumps(names, ensure_ascii=False).encode("utf-8")).hexdigest()
+
+
+def known_session_set_hash(state: State | None) -> str:
+    """所有 project_key→已知 sessionId 集合的穩定雜湊（供 anomaly 快照比對 project 集合突變）。"""
+    if state is None:
+        return hashlib.sha256(b"none").hexdigest()
+    payload = {k: sorted(v) for k, v in sorted(state.known_sessions.items())}
+    return hashlib.sha256(json.dumps(payload, ensure_ascii=False, sort_keys=True).encode("utf-8")).hexdigest()
+
+
+def _hub_session_stems(hub_dir: Path) -> set[str]:
+    if not hub_dir.exists():
+        return set()
+    return {p.stem for p in hub_dir.glob("*.jsonl") if p.is_file() and not p.name.startswith(".")}
+
+
+def detect_disappearance(
+    state: State | None, hub_root: str | Path, *,
+    min_known: int = DISAPPEAR_MIN_KNOWN, frac: float = DISAPPEAR_FRAC,
+    project_min: int = PROJECT_VANISH_MIN,
+) -> Anomaly | None:
+    """已知 session 是否從 hub **大量**消失（夾名指紋沒抓到的「內容被清/部分同步/誤掛」）。
+
+    只看 hub 端（local 消失靠 tombstone 流程處理，最致命的掛錯碟由此處 + fingerprint 涵蓋）。觸發 =
+      - **單專案**：known≥project_min 且該專案消失比例 ≥ frac（避免大專案稀釋掉小專案整夾被清，codex r8）；
+      - **或全域**：全體 known≥min_known 且全體消失比例 ≥ frac。
+    比例用精確分數比較（非 int() floor，否則 50% 會誤觸 60% 門檻，codex r8）。回 None 表無異常。
+    """
+    if state is None or not state.known_sessions:
+        return None
+    root = Path(hub_root)
+    total_known = 0
+    total_missing = 0
+    flagged: list[str] = []
+    for pk, known in state.known_sessions.items():
+        if not known:
+            continue
+        if not safe_project_dir(root, root / pk):
+            continue  # 逃逸 pk 夾（symlink/junction 出 hub_root）→ 不 glob 界外（e2e gate2 #4）；其異常由 build_plan skipped-unsafe surface
+        present = _hub_session_stems(root / pk)
+        missing = len(set(known) - present)
+        total_known += len(known)
+        total_missing += missing
+        if len(known) >= project_min and missing / len(known) >= frac:
+            flagged.append(pk)
+    global_hit = total_known >= min_known and total_known > 0 and total_missing / total_known >= frac
+    if not flagged and not global_hit:
+        return None
+    parts: list[str] = []
+    if flagged:
+        parts.append(f"{len(flagged)} 個專案各自大量消失")
+    if global_hit:
+        parts.append(f"全體 {total_missing}/{total_known} 不在 hub")
+    return Anomaly(
+        "known-sessions-vanished",
+        "已知 session 大量從 hub 消失（" + "；".join(parts) + "）。"
+        "疑似掛錯碟/hub 被清空/部分同步——請確認 hub 正確後 `bootstrap` 重建基線，不自動處理。",
+        "halt",
+    )
+
+
+def check(state: State | None, hub_root: str | Path) -> list[Anomaly]:
+    root = Path(hub_root)
+    if not root.exists() or not root.is_dir():
+        return [Anomaly("mount-missing", f"hub 掛載點不存在或非目錄：{root}", "halt")]
+    out: list[Anomaly] = []
+    cur = hub_fingerprint(root)
+    if state is not None and state.hub_fingerprint and state.hub_fingerprint != cur:
+        out.append(Anomaly("hub-fingerprint-changed", "hub 指紋改變（可能掛錯碟/專案集合突變）", "halt"))
+    disappeared = detect_disappearance(state, root)
+    if disappeared is not None:
+        out.append(disappeared)
+    return out
+
+
+# ── 跨側 presence / identity 安全 predicates（session-scan 與 memory-scan 共用，單一真相源避免漂移）──
+# 這兩個 predicate 不是 halt-anomaly 本身，而是餵給 classify 的安全判據（大量消失 → 不自動傳播刪除；
+# casefold 撞名 → 跨 OS aliasing 風險）。原本在 scan.py，P1d memory 也要用同一套 → 上提到此 leaf 模組，
+# scan 以原名（`is_bulk_local_deletion` / `_collision_casefolds` 別名）re-export 維持既有呼叫端不變。
+
+# present-empty 偵測的最小樣本：曾有 ≥ 此數的 local 項、現一個都不在 → 疑掛錯碟/整夾被清。
+# 單一項刪到空（known==1）仍視為正常刪除（floor=2 才觸發），避免常見小專案誤擋。
+_MOUNT_UNCONFIRMED_MIN = 2
+
+
+def is_bulk_local_deletion(local_known: set | None, local_stems: set[str]) -> bool:
+    """本專案 local 是否「大量消失」——疑掛錯碟/內容被清，而非使用者逐一刪除 → 該專案所有 `local-deleted`
+    改判 `blocked-bulk-local-deletion`（交人、**不自動寫 tombstone**）。session（sid）與 memory（檔名）共用。
+
+    這是刪除偵測最危險處：false-positive 會寫 tombstone 去**抑制對側真實項（session/memory，跨機資料可用性
+    損失）**。觸發條件（任一）：
+      (a) **掛載無法確認**：曾有 ≥2 個 local 項，但**一個都不在**現況（present 空集）。最危險的掛錯碟情境——
+          夾名靠 binding/git 對上、內容卻是別碟（known 集與現況零交集）即被此擋下，連 frac 樣本量不足的小專案
+          也涵蓋（codex r24-2）。單一項刪到空（known==1）仍信任。
+      (b) **大量比例消失**：known ≥ project_min 且消失比例 ≥ frac（仿 anomaly hub 側、精確分數比較）。
+    保守取捨——寧可大量/可疑消失時多問一次，也不在掛錯碟/被清空時靜默寫 tombstone。**仍有殘留**：掛載已被
+    現存項確認（present 非空）的「部分」消失會被當正常刪除而寫 tombstone；此為 feature 本旨（傳播使用者刪除）
+    的刻意取捨，且 harm 受限——A3 保證永不刪 hub/對側 local，tombstone 僅抑制再傳播、可逆（移除即復原）。"""
+    if not local_known:
+        return False
+    known = set(local_known)
+    present = known & set(local_stems)
+    if not present and len(known) >= _MOUNT_UNCONFIRMED_MIN:
+        return True  # (a) 掛載無法確認
+    return len(known) >= PROJECT_VANISH_MIN and (len(known) - len(present)) / len(known) >= DISAPPEAR_FRAC
+
+
+def collision_casefolds(a_stems, b_stems, keyfn=None) -> set[str]:
+    """casefold 撞名集（A9，跨 OS 碰撞風險）。**合併兩側**後看每個折疊鍵是否對到 >1 種拼法——這同時
+    涵蓋同側重複與**跨側** case-only 變體（local `ABC` + hub `abc`，case-sensitive 機器上各自不重複，但落到
+    Windows/exFAT 會 alias，且兩者鎖路徑不同→不互斥）（codex r11-4）。session 傳 sid 集、memory 傳檔名集。
+
+    `keyfn`＝折疊鍵函式，預設 `str.casefold`（session sid＝ASCII UUID，NFC/NFD 不適用 → 維持既有行為、零變動）。
+    **memory 傳 `pathsafe.name_key`（NFC∘casefold∘NFC）**——否則同一檔名的 NFC 與 NFD 兩種拼法（跨平台撰寫 memory
+    常見）不被判撞名，會各自當獨立檔雙向 copy（norm-sensitive FS）或在 norm-insensitive FS 上 aliased 覆蓋（e2e-r1
+    Finding 2；memory 檔名配對按位元組精確、唯此折疊鍵能認出正規化別名）。回傳集合以 `keyfn` 為鍵——**呼叫端的
+    `x in <此集合>` 判定必須用同一 `keyfn(x)`**（memory 端已改 `name_key(name) in collisions`）。"""
+    kf = keyfn or str.casefold
+    by_cf: dict[str, set[str]] = {}
+    for s in set(a_stems) | set(b_stems):
+        by_cf.setdefault(kf(s), set()).add(s)
+    return {cf for cf, spellings in by_cf.items() if len(spellings) > 1}