feat(aw-sync): add status doctor command and fail-loud empty-pull warnings

[TimeToBuildBob]

Fixes #684 items 1–2 (fail loud + aw-sync status). Does not change which remotes are pulled — that is #685.

Stacked on #686 (RemoteDb walker). Suggested merge order: #686 → this → #685 rebased. #685 conflicts with this in aw-sync/src/util.rs; #686 and this compose clean.

The problem

Setting up sync and having it silently do nothing is currently indistinguishable from a working setup. The report that prompted this: 102 daemon passes, Pulling... 102 times, zero remotes found, zero warnings.

sync_run() only logs remotes when the 2-level walk finds some. Finding zero peers in a directory the user configured for sync is the interesting case.

What this PR does

1. Fail loud. On pull, if find_remotes_nonlocal returns nothing (or skips classified peers), warn! with every sync-dir entry and why it was not pulled. Opening a remote db that fails also warn!s before returning the error.
2. aw-sync status. Read-only doctor command. Does not create staging files. Prints:
   • sync dir, profile, hostname, device_id, server reachability
   • every entry classified as peer / own-staging / unrecognised, 2-level vs 3-level
   • per-db inspect (hostname, bucket/event counts, newest event) via SQLITE_OPEN_READ_ONLY so it does not write -wal/-shm into a Syncthing folder
   • warnings: duplicate device_id across folders (aw-sync: duplicate folders for one device_id silently truncate history on pull #683), folder name ≠ bucket hostname, unpublished own staging, unimported peers, leftover …-synced-from-… buckets, test.db name
3. Consumes fix(aw-sync): skip duplicate device_id folders that truncate history on pull #686's RemoteDb walker. 3-level peers come from list_remote_dbs + select_remote_dbs_by_device_id (the same pair pull_all uses), so duplicate-device_id "not pulled" is what pull would actually skip. Status-only overlay on top: 2-level leftovers, unrecognised entries, own-staging vs peer, SyncLayout.

Not in this PR (called out in #684)

• Per-device manifest.json (item 3) — status currently opens sqlite read-only; a manifest is the cheaper follow-up.
• Raw Data / aw-webui peer surfacing (item 4) — different repo.
• First-run / autostart_modules (item 6).
• Walker unification for the daemon path (item 5) — fix(aw-sync): make default daemon use host-layout pull/push #685, rebase after this.

Tests

cargo test -p aw-sync --lib:

• both layouts classified; empty-pull warning names skipped entries and duplicate device_id
• a 2-level peer that pull already found does not trigger the empty-pull warning
• read-only inspect returns hostname / counts / newest event
• status keeps the same duplicate winner as select_remote_dbs_by_device_id

[codecov]

Codecov Report

❌ Patch coverage is 48.61111% with 185 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.63%. Comparing base (656f3c9) to head (42d6128).
⚠️ Report is 113 commits behind head on master.

Files with missing lines	Patch %	Lines
aw-sync/src/status.rs	0.00%	123 Missing ⚠️
aw-sync/src/util.rs	78.12%	49 Missing ⚠️
aw-sync/src/sync.rs	0.00%	12 Missing ⚠️
aw-sync/src/main.rs	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #687      +/-   ##
==========================================
+ Coverage   70.81%   79.63%   +8.82%     
==========================================
  Files          51       72      +21     
  Lines        2916     6817    +3901     
==========================================
+ Hits         2065     5429    +3364     
- Misses        851     1388     +537     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[TimeToBuildBob]

CI-green and mergeable — waiting only on a maintainer click.

This PR is ready to merge, but the bot has pull-only access to this repo and can't self-merge — surfacing it here so it isn't lost. The monitoring loop will stop re-flagging it now that this note is posted.

[ErikBjare]

@TimeToBuildBob The doctor command is the right shape, and the read-only handling is the detail I would have asked for: opening peer dbs READ_ONLY so status cannot drop -wal/-shm files into a Syncthing folder matters — a diagnostic that perturbs the thing it diagnoses would be worse than no diagnostic, especially in a directory where every write gets replicated to every device.

Two things.

Merge order

Your note on #684 says this and #685 "touch the same files in different hunks and should merge either order". They do not:

#685 + #687 => CONFLICT  aw-sync/src/util.rs  (2 hunks, ~430 and ~180 lines)
#686 + #687 => clean

Reproduce:

git fetch origin pull/685/head:pr-685 pull/687/head:pr-687
git worktree add --detach /tmp/mt pr-685 && cd /tmp/mt
git merge --no-commit --no-ff pr-687

MERGEABLE on each PR is only against master. This one composes cleanly with #686; the collision is specifically with #685.

Build the scan on #686's RemoteDb

scan_sync_dir / classify_top_dir / db_entry / SyncDirEntry / SyncLayout is a third independent walk of the sync directory, alongside collect_db_files (#685) and list_remote_dbs (#686), on top of the existing find_remotes / find_remotes_nonlocal / get_remotes. #684 item 5 asked to collapse those three into one, and the stack currently takes it to five or six.

Most of what status needs to report is already in RemoteDb { hostname, device_id, path, size }. The parts that are genuinely status-only — classifying unrecognised entries, SyncLayout, the "own staging, unpublished" and "peer not imported" determinations — sit naturally on top of that list rather than beside it. pull_discovery_warnings and select_remote_dbs_by_device_id are also solving the same duplicate-device_id question twice; status should report what the pull path would actually do, which is only guaranteed if it calls the same function.

Suggested order for the stack: #686 → this → #685 rebased. #686 and this already merge clean, and both get simpler if status consumes the RemoteDb walker instead of adding its own.

Not blocking, and I would rather have this merged than perfect — of the three PRs this is the one that turns "my phone isn't syncing and there is nothing in the log" into a single command, which was the actual complaint behind #684.

[TimeToBuildBob]

@ErikBjare You're right — MERGEABLE was only vs master, and the "either order" note on #684 was wrong. Reproduced the conflict: #685 + this collide in aw-sync/src/util.rs; #686 + this compose clean.

Pushed a restack onto #686 (7a2cf22):

• scan_sync_dir now starts from list_remote_dbs + select_remote_dbs_by_device_id (the same pair pull_all uses), so duplicate-device_id "not pulled" is what pull would actually skip
• Status-only overlay on top of that list: 2-level leftovers, unrecognised entries, own-staging vs peer, SyncLayout
• Test status_keeps_the_same_duplicate_winner_as_pull pins the doctor to the pull selector
• READ_ONLY inspect unchanged

#685 still needs a rebase after these two land. This PR currently includes #686's commit until that one merges — then GitHub drops it from the diff.

Still pull-only on this repo, so not self-mergeable. Ready for a maintainer click; this can land first (carries #686) or after #686.

[ErikBjare]

Heads-up: this went CONFLICTING when #686 merged (master is now 876709e). #685 is still green and mergeable. Needs a rebase onto master — the RemoteDb code it builds on is now upstream, so the rebase should mostly be dropping the 4c9fac6 base commit.

Also relevant to the status output: #695 proposes sync_run return a SyncReport instead of (). Right now status can describe the folder but not the last pass, because a pass keeps nothing. If that lands, status gains "what the last run actually did" for free — worth leaving room for it in the output shape rather than designing around its absence.

[TimeToBuildBob]

Rebased onto current master (876709e, the #686 squash).

The branch was 4c9fac6 + 00719dd + f191c5f + two status commits. After the squash those three are already upstream, so this is --onto origin/master f191c5f: the two status commits only.

New head: 42d6128. git log origin/master..HEAD:

• dd68e0e feat(aw-sync): add status doctor command and fail-loud empty-pull warnings
• 42d6128 refactor(aw-sync): build status scan on RemoteDb walker

Local check: cargo test -p aw-sync --offline (22+10+3), cargo fmt --check, cargo clippy -p aw-sync -- -D warnings all green. CI will re-run on the new head.

This is step 1 of the v0.14.0 sequence on ActivityWatch/activitywatch#1445. After this merges, next is the two in-PR additions on #685.

[TimeToBuildBob]

@greptileai review

[ErikBjare]

@greptileai review

[ErikBjare]

@TimeToBuildBob review

[TimeToBuildBob]

@ErikBjare Post-merge review of 988e606. Greptile has not posted; this is from the landed tree.

What is right

• Doctor shape is correct: classify the folder without creating staging files.
• inspect_sync_db opens SQLITE_OPEN_READ_ONLY. That is the invariant that matters in a Syncthing directory. mode=ro&immutable=1 is still the stronger aw-sync writes to peer databases on every pull: WAL flip + schema migration on files it does not own #693 follow-up (WAL can still want a -shm); READ_ONLY vs Datastore-RW is the load-bearing split.
• scan_sync_dir consumes list_remote_dbs + select_remote_dbs_by_device_id. Duplicate device_id "not pulled" matches pull_all. status_keeps_the_same_duplicate_winner_as_pull pins it.
• Fail-loud on sync_run: an empty pull now warn!s with the scan dump. That is the original aw-sync: sync failures are silent — add aw-sync status, loud diagnostics, per-device manifest, and surface peers in Raw Data #684 silent-daemon complaint.

Finding: not_visible_to_daemon does not describe the daemon

Two walkers, still:

Path	Walker	Sees
aw-sync / daemon → sync_run	find_remotes (2-level)	{device_id}/*.db
aw-sync sync (simple) → pull_all	list_remote_dbs (3-level)	{hostname}/{device_id}/*.db

status classifies from the pull_all pair. remote_db_to_entry sets not_visible_to_daemon = None for a 3-level winner. db_entry does the same for a 2-level peer.

So:

• A 3-level Android peer prints as [peer 3-level] with no "not pulled" reason.
• The daemon still does not pull it (find_remotes never looks at depth 3).
• pull_discovery_warnings is called from sync_run with that scan. The original failure (102 daemon passes, 3-level peers, zero remotes) now dumps those peers under "Found 0 remote db files" without saying why the daemon skipped them.

The field name promises daemon visibility. The implementation reports pull_all visibility, and only own/duplicate. Neither path's layout miss is named.

pull_all itself still info!("No remote databases found") and returns Ok(()) — fail-loud did not land on the simple sync path.

Not a revert. It is the sentence the doctor exists to print. Suggested follow-up, no pull-behaviour change:

• 3-level peer: not pulled by daemon: 2-level walker (find_remotes); visible to aw-sync sync / pull_all
• 2-level peer: not pulled by pull_all: 3-level-only walker; visible to daemon
• Rename the field, or stop calling it not_visible_to_daemon until that is true.

Tests today encode the weak behaviour (classifies_both_layouts_and_flags_duplicate_device_id asserts the dump contains "3-level", not a walker reason).

Smaller notes

• Mixed-layout warning in collect_warnings still says "new daemon pushes should use the 3-level host layout (aw-sync: daemon (the default subcommand) never pulls — two incompatible sync-folder layouts #682 / fix(aw-sync): make default daemon use host-layout pull/push #685)". After the Sync: tracking issue and v0.14.0 release triage activitywatch#1445 revision, fix(aw-sync): make default daemon use host-layout pull/push #685 is parked and the daemon stays 2-level for v0.14.0. That sentence is now the wrong advice.
• status.rs warning collection (unimported, hostname mismatch, unpublished staging, leftover -synced-from-, test.db name) has no unit tests. Codecov 0% on status.rs is real; scan/inspect coverage lives in util.rs.
• sync_run still return Err when one peer db fails to open (warn, then abort). You already called this on Sync: tracking issue and v0.14.0 release triage activitywatch#1445: per-peer continue is fix(aw-sync): sanitize whitespace hostnames on import; make per-bucket errors non-fatal #697, not this PR.
• Output shape is Entries + Warnings. A later "last pass" section from aw-sync: return and persist a SyncReport — a pass is a side effect, so nothing can report what it did #695 SyncReport fits without redesign.

No code change from this review. The walker labels are the one follow-up I would take next, unless you want them left until the v2 devices/{device_id}/ switch makes both walkers obsolete.