#AOCI-CODE-VOLUME: 1

===/Users/interia/tools/agent-mailbox/===
.gitattributes[FV3T]: F:Git line-ending policy: text always checks out LF so AOCI byte-identity baselines stay valid across platforms; binaries untouched. | R:- | A:- | S:-
.gitignore[FV2T]: F:Git ignore list: venvs, caches, dist, .env secrets, and local tool state (.mimosa, .claude-flow, .test-mail*). | R:- | A:- | S:-
Dockerfile[FV4T]: F:Container image build: pip-installs the package from source, defaults AGENT_MAIL_HOME=/data (volume), stdio ENTRYPOINT for MCP clients. | R:code:pyproject.toml | A:- | S:-
pyproject.toml[FV6T]: F:Package manifest for agent-mailbox 0.6.2: hatchling build, sole dependency mcp>=2.1, console scripts, pytest/ruff config. | R:code:src/agent_mailbox/server.py,code:src/agent_mailbox/watch.py | A:console scripts: agent-mailbox (server:main), agent-mailbox-watch (watch:main) | S:jev extra is an intentionally empty forward-compat slot; pytest addopts pin -q --timeout=30.
README.md[SG7M]: F:Canonical English readme: what problem the mailbox solves, quick start, wake daemon, the 13-tool table, security notes, and versioned roadmap. | R:code:src/agent_mailbox/server.py,code:docs/architecture.png | A:- | S:single full source of truth for docs; the five translations follow it per docs/release-checklist.md.
README.zh-CN.md[SG6M]: F:Full Chinese readme: 问题/方案/快速开始/看板/Wake daemon（信必达）/工具表/安全/roadmap，结构与英文版对应。 | R:code:README.md | A:- | S:fuller than the other translations (15 sections incl. Wake daemon); version anchor can lag English between releases.
README.es.md[SG4M]: F:Spanish readme translation: one-line current-version summary plus the core walkthrough; details point to the English README. | R:code:README.md | A:- | S:summary-level: per v0.6.1 policy each minor language keeps a one-line version anchor linking to the English README.
README.fr.md[SG4M]: F:French readme translation: one-line current-version summary plus the core walkthrough; details point to the English README. | R:code:README.md | A:- | S:summary-level: per v0.6.1 policy each minor language keeps a one-line version anchor linking to the English README.
README.pt-BR.md[SG4M]: F:Brazilian-Portuguese readme translation: one-line current-version summary plus the core walkthrough; details point to the English README. | R:code:README.md | A:- | S:summary-level: per v0.6.1 policy each minor language keeps a one-line version anchor linking to the English README.
README.ru.md[SG4M]: F:Russian readme translation: one-line current-version summary plus the core walkthrough; details point to the English README. | R:code:README.md | A:- | S:summary-level: per v0.6.1 policy each minor language keeps a one-line version anchor linking to the English README.
LICENSE[SZ2T]: F:MIT License, copyright 2026 polaris-smart contributors; also declared in pyproject.toml. | R:- | A:- | S:-
SECURITY.md[SS6S]: F:Security policy: private reporting via GitHub Security Advisories, supported versions (0.6.x), and the local-trust security model. | R:- | A:- | S:stated openly: any local process reading the mail root can read every mailbox; web board and webhook are the only constant-time-token surfaces.
CHANGELOG.md[SG5S]: F:Keep-a-Changelog release history 0.3.1 to 0.6.2: wake daemon, threads, dedup, identity binding, and per-version security notes. | R:code:README.md | A:- | S:back-filled 0.3.1-0.6.0 during the v0.6.1 docs-only hotfix; new entries land here before translations update.
AGENTS.md[SG7S]: F:AOCI integration instructions for host agents: cognition receipt rules, maintenance-closing workflow, and tool-state safety boundaries. | R:- | A:- | S:contains a managed aoci:begin/end block; entry semantics must come from machine-issued Plan/Guide, never hand-authored outside it.

===/Users/interia/tools/agent-mailbox/src/agent_mailbox/===
store.py[PB9L]: F:Thread-safe JSON mail store over one mail root (registry.json + per-agent inbox/archive); owns mail lifecycle, semantic-hash dedup, threads, handled_log, tasks. | R:code:src/agent_mailbox/server.py,code:src/agent_mailbox/wake.py,code:src/agent_mailbox/sampling.py,code:src/agent_mailbox/webhook.py,code:src/agent_mailbox/web.py | A:MailStore (register/send/check/claim/reap_stale_acked/set_status/task_*); semantic_hash(); load_window_config(); MailboxError | S:reap_ttl must stay strictly below dedup_ttl (defaults 1h vs 24h); done requires two-phase handled_log intent-then-outcome; TTL overrides validated loudly in load_window_config.
server.py[EB9L]: F:MCP server exposing the mailbox as tools (mailbox_*/task_*) over stdio or HTTP; binds acting identity per connection and routes sampling wake after send. | R:code:src/agent_mailbox/store.py,code:src/agent_mailbox/sampling.py | A:main(); MCP tools mailbox_register/send/check/reply/list/thread/done/broadcast/whoami/wait + task_create/move/list | S:agent_id/from_id default to AGENT_MAIL_ID env and are verified against the registry (foreign identity raises); capability middleware is observe-only and never blocks handshake.
wake.py[AM8L]: F:Wake daemon (信必达): launchd WatchPaths / systemd path unit triggers a drain loop that wakes agents on new mail via adapters; installs the OS service. | R:code:src/agent_mailbox/store.py,code:src/agent_mailbox/webhook.py,code:src/agent_mailbox/reap.py | A:wake_main(argv); CLI wake install/uninstall/status/run; make_adapter(cfg) | S:fail-open iron law: daemon death never blocks mail delivery; failed wake retries 5x60s; wake dedup via handled_log; wakes on pending or acked older than 600s only.
sampling.py[AM8L]: F:v0.7 in-protocol wake: after send, issues sampling/createMessage on connections that declared capabilities.sampling, injecting per-agent wake policy. | R:code:src/agent_mailbox/server.py,code:src/agent_mailbox/store.py | A:SamplingNotifier; SamplingRegistry; stable_connection(); load_wake_policies(); wake_policy_for(); render_wake_prompt() | S:createMessage is a request: timeout (60s default) + per-msg_id dedup are mandatory; host without capabilities.sampling skipped (fail-open); per-agent max_concurrent gate default 1, FIFO by created_at; wake.json corruption is fail-loud.
web.py[EU5M]: F:Zero-dependency web kanban over the task store: one embedded HTML page served by http.server on 127.0.0.1; the token holder acts as agent boss. | R:code:src/agent_mailbox/store.py,code:src/agent_mailbox/server.py | A:run_web(port=8643); board served at /?token=... | S:bearer-token auth, constant-time compare (header or query param); AGENT_MAIL_WEB_TOKEN or per-boot token printed once; board actions use normal task tools so moves auto-message assignees.
webhook.py[IN6M]: F:Optional best-effort webhook notification on new mail: POSTs to a configured local gateway with HMAC signature; no config means no POST. | R:code:src/agent_mailbox/store.py | A:notify_new_messages(); post_message(); signature styles github/generic/slack via AGENT_MAIL_SIGNATURE_STYLE | S:target pinned to http/https loopback/private addresses, redirects refused, system proxy bypassed; failures never raise into the send path.
watch.py[IU4S]: F:Optional human-facing `agent-mailbox watch` companion: prints new messages as JSON lines and fires desktop notifications; agent wake-up does not use it. | R:code:src/agent_mailbox/store.py | A:- | S:poll-based watcher (docstring names FSEvents/kqueue but delivery is a poll loop); notifications best-effort.
cleanup.py[XQ4S]: F:Mail-root residue scanner CLI (default dry-run): lists unregistered inbox/archive dirs, test-named dirs, orphan letters and tmp files. | R:code:src/agent_mailbox/store.py | A:main(); python -m agent_mailbox (cleanup is the -m entry point) | S:deletion requires --yes plus interactive confirmation; registered-but-test-named dirs are review-only, never deleted.
reap.py[XR5T]: F:CLI reclaiming stale acked mail back to pending before wake-loop pending counting, so letters from dead or cancelled handlers reappear; never deletes. | R:code:src/agent_mailbox/store.py,code:src/agent_mailbox/wake.py | A:main(); python -m agent_mailbox.reap --agent <id> --ttl <seconds> | S:status flip only: handled_log records a reclaimed entry; default ttl 3600s must stay below the dedup window.
__init__.py[CG2T]: F:Package marker exposing __version__ (0.6.2). | R:- | A:__version__ | S:-
__main__.py[EZ2T]: F:`python -m agent_mailbox` entry delegating to the cleanup CLI (mail-root maintenance); the server starts via agent-mailbox or -m agent_mailbox.server. | R:code:src/agent_mailbox/cleanup.py | A:- | S:-

===/Users/interia/tools/agent-mailbox/.github/workflows/===
ci.yml[FQ5T]: F:CI matrix: ruff check plus pytest on ubuntu/macos/windows with Python 3.11 and 3.13, fail-fast off, on pushes to main and PRs. | R:code:pyproject.toml | A:- | S:-
publish.yml[FV5T]: F:PyPI release on v*.*.* tags: build sdist and wheel, then publish via Trusted Publisher (GitHub OIDC, no API token). | R:code:pyproject.toml | A:- | S:publish job requires the pypi GitHub environment with id-token: write.

===/Users/interia/tools/agent-mailbox/scripts/===
install-watch-linux.sh[XV4T]: F:Installs the watch daemon as a systemd user unit (Restart=always) running -m agent_mailbox.watch on ~/.agent-mail; extra args pass through. | R:code:src/agent_mailbox/watch.py | A:- | S:requires a systemd user session (loginctl enable-linger); repo venv must exist.
install-watch-macos.sh[XV4T]: F:Installs the watch daemon as a launchd LaunchAgent (KeepAlive) running -m agent_mailbox.watch; extra args pass through. | R:code:src/agent_mailbox/watch.py | A:- | S:bootouts any previous instance before rewriting the plist; logs at ~/.agent-mail/watch.log.
install-watch-windows.ps1[XV4T]: F:Installs the watch daemon as a logon scheduled task via schtasks running -m agent_mailbox.watch; extra args pass through. | R:code:src/agent_mailbox/watch.py | A:- | S:generates a one-line watch.cmd wrapper so schtasks never quotes the argument list.
wake-zc.sh[OW4S]: F:Deployed ZC wake loop (repo copy mirrors ~/.agent-mail/wake-zc.sh): reap-before-count drain with exponential backoff and a circuit breaker. | R:code:src/agent_mailbox/reap.py,code:src/agent_mailbox/store.py | A:- | S:drain exit code untrustworthy: progress = pending drop; breaker latch wake-zc.breaker (6h expiry); REAP_TTL < 24h dedup.

===/Users/interia/tools/agent-mailbox/skills/agent-mailbox/===
SKILL.md[SG6T]: F:Agent-facing operations guide: setup, session discipline, the 13 MCP tools, task board, and wake-daemon/Jev usage for multi-agent coordination. | R:code:src/agent_mailbox/server.py | A:- | S:tool table is 13 (10 mailbox_* + 3 task_*) matching server.py; read-but-never-done letters poison wake heuristics.

===/Users/interia/tools/agent-mailbox/docs/===
release-checklist.md[SV5S]: F:Per-release checklist that stops multilingual docs lagging: pytest/ruff green, two version-bump spots, six READMEs, CHANGELOG, SKILL.md. | R:code:pyproject.toml,code:src/agent_mailbox/__init__.py,code:README.md | A:- | S:version number changes in exactly two places: pyproject.toml and src/agent_mailbox/__init__.py; English README is the only full source.
v0.5.0-实施任务书.md[SG4M]: F:v0.5.0 implementation task book (2026-09-13 review cycle): dedup/handled-log design, iron rules, review receipts, and scheduling decisions. | R:code:src/agent_mailbox/store.py,code:scripts/wake-zc.sh | A:- | S:铁1 reap_ttl<dedup_ttl is enforced in store config loading; periodic mail defeats semantic-hash dedup by design.
index.html[SU4S]: F:Chinese landing page: install command, feature badges, and a board screenshot that toggles between board-light/board-dark with the theme. | R:code:docs/board-light.png,code:docs/board-dark.png | A:- | S:-
architecture-en.json[SV4S]: F:Archify source spec of the architecture diagram: components, labels, and positions describing the send-time webhook wake-up flow. | R:code:docs/architecture-en.html,code:docs/architecture.png | A:- | S:-
architecture-en.html[SV4L]: F:Self-contained rendered architecture page (generated by archify 2.16.0 from architecture-en.json) showing the send-time webhook wake-up flow. | R:code:docs/architecture-en.json | A:- | S:generated artifact: edit architecture-en.json and re-render, not this file.
architecture.png[SG3T]: F:Architecture diagram image (mailbox + send-time webhook wake-up) embedded by the English and Chinese READMEs. | R:code:README.md | A:- | S:-
board-light.png[SG3T]: F:Light-theme screenshot of the web kanban board, swapped in by docs/index.html when the page theme is light. | R:code:docs/index.html | A:- | S:-
board-dark.png[SG3T]: F:Dark-theme screenshot of the web kanban board, swapped in by docs/index.html when the page theme is dark. | R:code:docs/index.html | A:- | S:-

===/Users/interia/tools/agent-mailbox/v02-proposals/git-native-memory/===
PLAN.md[SG4S]: F:v0.2 pre-research plan for Git-Native Memory: benchmark vs okf-agent-memory, the learnings/recall/voting trio design, and the hybrid-route verdict. | R:code:v02-proposals/git-native-memory/learn.py | A:- | S:verdict is evidence-backed: okf rejected on CJK substring misses; self-built bigram+BM25 prototype passed the same probe.
learn.py[XZ4M]: F:Runnable Git-Native Memory prototype CLI: learnings entries, BM25 recall with Chinese bigram tokenization, and per-agent vote flywheel. | R:code:v02-proposals/git-native-memory/PLAN.md | A:- | S:prototype only, not wired into the package (no src/ reference); LEARNINGS_ROOT env overrides ~/.agent-mail/learnings.
