feat(attachments): outbox watcher — bidirectional hands-off file sync

[kitplummer]

Completes the "watcher on both sides" model you asked for. The receive-side inbox watcher already existed (auto-fetch + write + integrity-verify); this adds the missing send-side outbox watcher, so a file dropped in a node's outbox auto-syncs to every peer's inbox with no SendAttachments gRPC call.

Why

--attachment-root was only an allowlist of readable dirs; distribution required an explicit SendAttachments call (confirmed: no source watcher existed). So the send side was manual while the receive side was automatic. This closes that asymmetry.

What

• PEAT_NODE_ATTACHMENT_OUTBOX_WATCH=true (opt-in; ..._POLL_SECS, default 2s). Polls the configured roots; auto-distributes any stable (unchanged across a poll), not-yet-sent file via the same handlers::send_attachments path (validate → ingest → sha256-verify → distribute → registry), scope AllNodes, default priority. Idempotent.
• Pure stability/dedup decision (Send/Wait/Skip) is unit-tested; recursive walk skips dotfiles; sha256 is stream-hashed. Off by default (explicit RPC stays the safe default).
• Polling (not inotify) — mirrors the inbox watcher and is reliable across container bind mounts (your macOS-container ↔ Jetson case).

Verified

• 5 unit tests; full cargo test --workspace green (the lone parallel-run failure is the known sync_subprocess contention flake — passes isolated).
• Live two-node: drop a 512 KiB file in the sender outbox (no gRPC) → byte-identical in the receiver inbox in ~3s.
• New compose functest test/attachment-outbox-watch-compose.sh (+ CI step): same, in containers — PASS.
• Docs: multi-host example + attachments README document the hands-off synced-folder mode.

Ships in the next release (0.4.5); the example/README note that.

[peat-bot]

Peat QA Review (SHA: 2337716)

Opt-in send-side outbox watcher (PEAT_NODE_ATTACHMENT_OUTBOX_WATCH) that polls --attachment-root and auto-distributes stable new files via the existing handlers::send_attachments path. No proto/wire changes, no new RPCs, no Cargo.toml bump, no chart//zarf.yaml/src/watcher.rs/src/crypto.rs changes — pure Rust + Tokio, only depends on peat-mesh. The new functest (test/attachment-outbox-watch-compose.sh) exercises the end-to-end path with sha256 byte-identity assertion and is wired into the attachment-delivery.yml CI job.

[WARNING] Unbounded growth of watcher state maps when outbox files are deleted

src/attachments/outbox.rs:155-167 — last_seen and last_sent are HashMap<PathBuf, (u64, SystemTime)> accumulated for the lifetime of the watcher. Each poll iteration only ever calls .insert(...) for files currently found on disk; entries for files removed from the outbox root remain forever. In a long-running sidecar with steady outbox churn (the most natural "synced folder" usage pattern: drop, distribute, delete) the maps grow without bound. The rest of the attachments subsystem already bounds similar state via max_known_bundles — this watcher is the lone exception.

Action: at the end of each poll cycle, prune entries whose PathBuf was not observed by walk_files this iteration (e.g., collect the current set, retain only those keys). One-line fix. Not blocking — even at 1000 files/day churn the growth is ~36 MB/year — but worth fixing before this ships in 0.4.5.

Notes (non-findings, for context)

• No new RPCs on PeatSidecar — the watcher drives the existing handlers::send_attachments internally, so the "new RPC ⇒ tests/grpc_test.rs integration test" rule does not trigger. The end-to-end functest covers the new behaviour.
• The Err branch at outbox.rs:188-195 deliberately marks the version as sent so transient failures don't re-attempt every poll; the user must touch the file (bumping mtime) to retry. This is documented in the inline comment and matches the explicit-RPC semantics (a vacuous COMPLETED with zero peers, etc.). Acceptable as designed — flagged here only so reviewers know the trade-off is intentional, not a regression.
• The compose functest mounts the sender outbox :ro and writes from the host, sidestepping any race between watcher polls and partial writes; combined with the Wait-then-Send stability check this is sound.

[peat-bot]

Peat QA Review (SHA: 603abc3)

Incremental review since 2337716.

Delta: a single targeted fix for the prior [WARNING] on unbounded watcher state-map growth (src/attachments/outbox.rs). Adds a prune_to_observed helper, collects a HashSet<PathBuf> of paths seen during each poll cycle, and prunes both last_seen and last_sent to that set at the end of the cycle. New unit test prune_drops_vanished_files covers the helper. No proto changes, no new RPCs, no Cargo.toml/chart/Zarf/crypto/watcher-TLS changes, no language or runtime additions, still Tokio-only, still depends on peat-mesh only.

Prior findings

• Resolved: [WARNING] Unbounded growth of watcher state maps when outbox files are deleted — src/attachments/outbox.rs:168-172, 213-216 now collect an observed: HashSet<PathBuf> during the poll's walk_files traversal and call prune_to_observed on both last_seen and last_sent after the cycle. Implementation uses idiomatic HashMap::retain, matches the bounding pattern used elsewhere in the attachments subsystem, and is covered by the new prune_drops_vanished_files unit test (src/attachments/outbox.rs:270-280).

New findings

No findings.

[peat-bot]

Peat QA Review (SHA: 23bccb4)

Incremental review since 603abc3.

Delta: test-only. tests/attachments_e2e_test.rs widens four await_inbox_file deadlines from 30s to 60s on the iroh two-node serial tests, and the await_inbox_file doc-comment is rewritten to explain the CI-contention rationale (peat-node SKILL gotcha — multiple two-node iroh meshes under CPU contention stall past a tight budget; <3s unloaded, 60s preserves a real-failure signal). No proto changes, no new/changed RPCs, no Cargo.toml/peat-mesh-pin changes, no chart/Zarf changes, no src/crypto.rs changes, no src/watcher.rs TLS changes, no language or runtime additions, still Tokio-only, still depends on peat-mesh only. Production code paths (src/attachments/outbox.rs pruning, the outbox watcher itself) are untouched.

Prior findings

• Resolved (still resolved): [WARNING] Unbounded growth of watcher state maps — fixed in 603abc3 via prune_to_observed in src/attachments/outbox.rs. This delta does not touch that file; the bounding remains in place and covered by prune_drops_vanished_files.

New findings

No findings.