Repository navigation
release: Document Sync Agent on-device validation #63
Description
Summary
The Document Sync Agent (SyncAgent/) is built and tested — 53 passing tests including a read-only live check. The packaging pipeline embeds it at InterlinedList.app/Contents/Library/LoginItems/InterlinedListSync.app and registers it as an SMAppService.agent via Settings ▸ Document Sync.
What remains cannot be run headless: it needs a real Aqua session and a Developer ID signature. That makes it part of the release gate, not the feature backlog.
What the agent is
A bundled LSUIElement menu-bar utility that mirrors documents to a local Markdown folder (the Obsidian use case). It reads the bearer token from the shared Keychain group $(AppIdentifierPrefix)com.interlinedlist.shared, so it syncs with no separate sign-in. Correlation uses xattr plus path.
Validation checklist
- Menu-bar GUI smoke — status item appears, Preferences window opens and behaves.
- Full notarized
.pkginstall path, end to end:- Install the
.pkgon a clean machine -
SMAppService.agentregistration succeeds and is visible in System Settings ▸ Login Items - The running agent reads the bearer token from the shared Keychain group
- It syncs with no separate sign-in
- Confirm the legacy-token → shared-group migration path for a machine that had an older build
- Install the
- Exercise the live write paths once — create, update, delete. They share the request-building and envelope decoder that the read paths already cover, but they have never been run against production.
Two things worth deciding while validating
- Per-machine settings belong on the server now.
/help/app-settingsdescribes per-machine settings as exactly this case — a sync folder path is meaningful on one machine only. The agent's configuration is a natural first tenant for the Applications settings work. Not a blocker for validation, but decide whether it lands before or after the release cut. - Account switching. If multi-account switching is ever built, a running agent mirroring one account's documents to a local folder needs an explicit answer for what a switch means. Flagged in that spike; noted here so the agent's owner sees it.
Acceptance criteria
- Every box above ticked on a real machine with a notarized build.
- Any defect found is filed separately rather than fixed silently inside the validation pass.
Notes
work-consolidation.md §3b. Blocked on the release issue producing a signed .pkg — sequence them together.
Activity
Adron commentedon Sep 16, 2026
Needs you at a keyboard — this one is inherently manual
I cannot do on-device validation. Everything here requires a signed build installed on a real Mac, a real Obsidian vault, and observation over time.
What I can confirm from the code
The Document Sync Agent is implemented and unit-tested:
SyncAgent/, the shared-Keychain token, theSMAppServiceLaunchAgent registration, and the xattr + path correlation.swift test --package-path Packages/InterlinedPersistencecovers the sync engine and the outbox.Two things changed today that touch this issue directly:
enqueuedAtalone — a non-total key — so two changes queued in the same instant could replay in either order, which for document sync means an update replayed before the create it depends on. If you were going to validate the agent on-device, validate it after that merges, or you would be exercising the bug.What I need from you
A validation pass on a real machine, roughly:
SMAppServiceregistration is the part most likely to be wrong in a notarised build versus a debug one.What would help most if something goes wrong
The rotating debug log (shipped in PR #9) and the Console output for the agent's subsystem. If step 2 fails, that is almost certainly an entitlement or a signing difference between the debug and notarised builds, and the notarised build is the only one that can show it — which is why this is blocked behind #62 in practice.