Skip to content

fix: enforce documented repository safety contracts - #95

Merged
codeasier merged 2 commits into
mainfrom
docs/deep-sync-agents-docs
Aug 9, 2026
Merged

codeasier merged 2 commits into
mainfrom
docs/deep-sync-agents-docs

Conversation

@codeasier

Copy link
Copy Markdown
Owner

Description

  • align repository and scoped AGENTS guidance with actual runtime, test, CI, and security behavior
  • make focus persistence and snapshot import publication failure-safe, and align CLI/API/MCP device and query error semantics
  • gate releases and snapshot provenance checks on the relevant committed content
  • add executable fixture provenance/checksum enforcement and correct GitHub template paths
  • update focused regression coverage and bilingual user documentation

Related Issue

Fixes #94

Testing

  • Full test suite: PYTHONPATH=src pytest
  • MCP suite without third-party pytest plugins
  • ruff check .
  • black --check .
  • actionlint
  • basedPyright (0 errors; existing warnings only)
  • strict AGENTS hierarchy validation
  • git diff --check

Checklist

  • Code follows project guidelines
  • Documentation updated
  • No new warnings introduced
  • Changes tested locally

Snapshot Runtime Provenance

  • Snapshot provenance evaluation completed when snapshot runtime files change
    Snapshot provenance decision: no-update
    Snapshot provenance no-update reason: Changes under the snapshot runtime scope only update agent guidance; runtime origin and copied-code history are unchanged.

Additional Notes

Committed pickle fixtures are now verified against reviewed provenance, SHA-256 digests, and expected sizes before pytest collection.

@codeasier

Copy link
Copy Markdown
Owner Author

Cross-Review 检视意见(已核实)

并行独立评审(DeepSeek / GLM / Kimi,3/3 quorum)后,我对所有候选意见逐一对照 PR 源码与基准差异进行了验证。以下 3 项为可复现/可证实的发现,按严重度排序。其余候选(LFS CI 内容校验、release tag base 退化、双失败未覆盖、性能权衡、Windows 矩阵缺失、FIXTURE_DIR 相对路径、CRLF 边界等)经核验要么是本 PR 明确定义的契约行为,要么不构成缺陷,未纳入。


1. [medium] 导入回滚 fallback 存在符号链接竞态,可能覆盖任意文件

  • 位置: src/pt_snap_cli/core/snapshot_import_backend.py:52-64
  • 问题: 回滚备份路径先由 tempfile.mkstemp 创建并 os.close,随后 backup_path.unlink(),再用 os.link(db_path, backup_path)(失败时 shutil.copy2(db_path, backup_path))。在攻击者可控写入的 output_dir 中,unlink 后、link/copy2 前的窗口内可将该路径替换为指向任意文件的符号链接,导致以导入者权限覆盖任意文件。
  • 证据: 已复现——将 backup_path 替换为指向 victim.txt 的符号链接后,shutil.copy2 会沿链接写入并覆盖 victim 内容(copy2 symlink victim: database)。os.link 同样会解引用已存在的目标路径。
  • 复现(PYTHONPATH=src python -c 片段):见下文脚本。
  • 建议: 保留 mkstemp 返回的安全文件描述符(os.link/shutil.copy2 直接写入该 fd),或改用独占式 no-follow 的 fallback(os.open + O_CREAT|O_EXCL),并在写入后 fchmod 保持私密权限。

2. [low] 新建 focus/config 文件时短暂清空进程级 umask

  • 位置: src/pt_snap_cli/config.py:70-73
  • 问题: current_umask = os.umask(0); os.umask(current_umask) 读取 umask 时会把进程级 umask 瞬态置为 0。同进程其他线程在同一窗口创建文件(如 MCP 服务)时,权限会退化为 0666 而非遵循 umask。
  • 证据: 已复现——在 umask 0o027 下并发创建得到 666(期望 640)。
  • 建议: 对新文件使用固定保守模式(如 0o600),避免修改进程级 umask。

3. [low] 无参 set_focus() 行为回归(含 MCP)

  • 位置: src/pt_snap_cli/api.py:76-100
  • 问题: 旧实现中 db_path is None 时不校验、set_focus() 无参为纯 no-op;新实现 candidate_db 回退到 self._db_path,并对已失效的数据库/设备重新校验并抛异常。
  • 证据: SnapshotAnalyzer(db_path=/definitely/missing/pr95.db); set_focus() 现在抛 FileNotFoundError;src/pt_snap_cli/mcp/server.py:29-30 的 set_focus 工具参数均为可选,MCP 调用方可能触发同一路径。
  • 建议: 当两个参数均为 None 时提前返回当前 focus(或在构造函数中校验),并补充无参调用测试。

验证状态

  • 聚焦测试:test_config / test_import_service / test_api / test_governance / test_release_workflow / test_fixture_provenance 共 104 passed。
  • ruff check、black --check、actionlint、git diff --check 全部通过;当前 PR checks 全部通过。
  • 上述 3 项为未被现有测试与 CI 覆盖的边界路径。

注:并行评审会增加 token 消耗与成本。

@codeasier

Copy link
Copy Markdown
Owner Author

Thanks for the cross-review — all three findings reproduced and are addressed in the latest push (005991a):

1. Import rollback symlink race (medium) — fixed

Confirmed reproducible. Root cause: mkstemp → unlink → link/copy2 created a window in which output_dir could swap the secure temp file for a symlink, and the original os.replace(backup_path, db_path) then followed that symlink. The fix in src/pt_snap_cli/core/snapshot_import_backend.py keeps the secure mkstemp fd open across publish, writes the backup through the fd (os.write + os.fchmod) without ever touching the path, and restores db_path by lseek+read on the fd if post_publish raises — so an attacker-planted symlink at the name is never dereferenced. New regression test_rollback_backup_writes_through_secure_mkstemp_fd plants a symlink at the secure path and asserts both that the victim file is untouched and that the original database is restored.

2. Umask transient (low) — fixed

Confirmed reproducible in a concurrent thread. Replaced the os.umask(0); os.umask(...) round-trip with a fixed private mode of 0o600 for new files in Config._write_json_atomic (src/pt_snap_cli/config.py). Existing files still mirror the prior mode. New regression test_atomic_write_new_file_uses_private_mode monkeypatches os.umask to raise on any call and asserts the new file mode is 0o600.

3. set_focus() no-arg regression (low) — fixed

Confirmed. Restored the original no-op semantics: when both db_path and device_id are None, SnapshotAnalyzer.set_focus() now returns the current focus without revalidating the underlying database. The MCP set_focus tool inherits this behavior for free. New regression test_set_focus_no_args_returns_current_focus_without_revalidation constructs the analyzer with a now-deleted database and asserts the no-arg call returns the prior focus state instead of raising.

Validation

  • PYTHONPATH=src pytest → 671 passed, 1 xfailed.
  • ruff check ., black --check ., git diff --check all clean.
  • All PR checks green on the new commit.

No rebase or history rewrite; this is a single follow-up commit on the same branch.

@codeasier
codeasier merged commit 9dbd960 into main Aug 9, 2026
6 checks passed
@codeasier
codeasier deleted the docs/deep-sync-agents-docs branch August 9, 2026 08:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[DOCS] 审计并修复 AGENTS.md 指南与实现及安全边界的漂移

1 participant