Mount sync: local mirror doesn't pull newer remote revisions (+ mount/start CLI footguns)

[khaliqgant]

Summary

While diagnosing "Linear data shows in Nango but not in my local mirror," I found one functional sync bug (the local mirror does not advance to newer remote revisions, even with a forced full reconcile) plus a set of CLI/UX footguns in relayfile mount/start — one of which is dangerous (it can re-home the mirror onto an arbitrary directory and start enqueuing it as writebacks).

Filing them together since they were all surfaced by the same investigation.

Environment: relayfile CLI (poll mode), workspace rw_fc7b534b, macOS. Mirror dir …/relayfile/relayfile-mount.

---

1. (P1, functional) Local mirror does not pull newer remote revisions — even with RELAYFILE_FORCE_FULL_RECONCILE=1

The cloud workspace has records that never reach the local mirror. This is not just lag — a forced full reconcile completes cleanly (mount sync cycle completed, no errors) without pulling them.

Evidence (Linear):

Record	Remote (relayfile tree)	Local mirror
linear/projects/779cbfda-0f49-4a92-97cb-214633bc914b.json	present, rev_46580, readable via relayfile read	missing (dir has only empty _index.json)
linear/issues/AR-28…json	rev_44031	present
linear/issues/AR-30/AR-31/AR-32	rev_46579 / rev_56089 etc.	missing

Remote has 16 Linear issues; local has 13. Everything above ~rev_44031 is not pulled. The cloud side is fine (Nango syncs succeed; relayfile tree/relayfile read return the records). The break is the cloud → local-mirror hop.

Repro:

1. Leave a workspace mirror unsynced for a while (daemon stopped).
2. Confirm cloud has newer records: relayfile tree <ws> linear/issues shows revs newer than what's local.
3. Start the daemon: relayfile mount <ws> <dir> --background.
4. Restart forcing a full reconcile: RELAYFILE_FORCE_FULL_RECONCILE=1 relayfile mount <ws> <dir> --background.
5. Newer records (AR-30/31/32, the project) still never appear locally; relayfile status keeps showing linear … lagging … last event 13h ago.

Why it matters: the local mirror silently diverges from cloud truth. Agents/humans reading the mirror see a stale world with no error surfaced.

Suspected cause: regular cycles do incremental, event-cursor-based pulls; since Linear's last tracked event is ~13h old, newer records (ingested without a newer cursor event) are never pulled. And RELAYFILE_FORCE_FULL_RECONCILE did not rescue it, so the "full reconcile" path also isn't enumerating/pulling these remote files. Possibly related to #2 below (index-driven enumeration).

---

2. (P2, data) _index.json is empty for linear/projects and linear/teams even in the cloud

The record files exist beside it, but the index aggregation is []:

relayfile tree rw_fc7b534b linear/projects
  file /linear/projects/_index.json                       size=3   rev=rev_46181   ← "[]"
  file /linear/projects/779cbfda-…json                    size=1899 rev=rev_46580   ← real record

Contrast linear/issues/_index.json (size=496, populated). Same for linear/teams/_index.json ([]) despite a team record + by-id/by-name aliases existing.

This matters because the activity-summary skill instructs agents to start from indexes/digests before walking provider trees — an empty index hides existing records. May also be the root of #1 if the reconcile enumerates provider dirs via _index.json rather than the actual tree.

---

3. (P1, dangerous UX) relayfile mount with no LOCAL_DIR mirrors the current directory and persists it as localDir

Running relayfile mount (no dir arg) from the repo root:

• mirrored the entire repo (node_modules, .next caches, the 63 MB workflow-runs.jsonl, compiled binaries) → wall of skipping oversized local file … and context deadline exceeded;
• started treating repo files as local changes to enqueue as writebacks to the cloud workspace;
• pulled cloud provider dirs into the repo root (google-mail/, .skills/, digests/this-week.md, .relay/, .relayfile-mount-state.json);
• overwrote the workspace's saved localDir in ~/.relayfile/workspaces.json to point at the repo root.

Only the context deadline exceeded (before any enqueue) prevented pushing repo contents into the workspace.

Expected: with no LOCAL_DIR, fall back to the configured localDir; refuse / loudly warn if CWD is not the known mirror; never silently re-home the mirror.

---

4. (P2, UX) relayfile start is a foreground alias for mount, but help frames it as the daemon partner of stop/restart

Help text: "start — Alias for mount; pairs naturally with stop and restart." This implies start launches a managed background daemon. It does not — it runs in the foreground; you must pass --background. Result: relayfile start leaves a foreground process that relayfile stop cannot find (no running mount found).

---

5. (P2, UX) relayfile status reports daemon: not running while a foreground mount is actively running

A live foreground relayfile mount/start process (confirmed via ps, burning CPU) shows as daemon: not running because status only tracks --background daemons. Misleading during diagnosis.

---

6. (P3, UX) relayfile tree linear/projects → confusing 403 workspace mismatch

relayfile tree [WORKSPACE] [PATH] parsed linear/projects as the workspace positional, yielding error: http 403 forbidden: workspace mismatch instead of treating it as a path or reporting "unknown workspace." A path-looking first arg should be detectable, or the error should name the bad workspace.

---

7. (P3, UX) "skipping oversized local file" log is unbounded and repeats every cycle

When pointed at a tree with large artifacts, the same full list of skipped files is re-emitted every sync cycle with no dedup/summary, burying the actual error (context deadline exceeded). Suggest logging once, or a per-cycle summary count.

---

Suggested priorities

• Make Relayfile completely provider-agnostic #1 / rename #2 — functional correctness of the cloud → local pull (most important; data silently stale).
• feat: Nango bridge + Python SDK + SDK improvements #3 — guardrail against re-homing the mirror / writing back the repo (data-safety footgun).
• Prep for usage: bulk API, export, WebSocket, mount hardening, E2E #4–Competitive learnings from Archil docs review #7 — UX/observability polish.

[khaliqgant]

Root cause found + fix for item #1 (the P1 sync bug)

The "local mirror doesn't pull newer remote revisions" bug is not in the relayfile daemon — it's an event-ordering bug in the cloud /fs/events feed.

The feed's listEvents ordered timestamp DESC, event_id DESC and selected events older than the cursor (a backward feed). The daemon — and the self-host reference store (internal/relayfile/store.go) — treat the cursor as a forward watermark, expecting events newer than it, oldest-first. Consequence:

1. resolveLatestEventCursor paged to the end of the DESC feed and seeded the oldest event (evt_1).
2. Every incremental cycle then asked for "events before evt_1" → 0 results → quiet cycle → mirror frozen at bootstrap.
3. RELAYFILE_FORCE_FULL_RECONCILE was bypassed because it's gated behind EventsCursor == "".

Verified live: GET /fs/events?cursor=evt_1 → 0 events; ?cursor=evt_52032 → evt_52005–52014 (older).

Fix: AgentWorkforce/cloud#862 — flips both listEvents impls to timestamp ASC, event_id ASC with a timestamp > ? predicate (matches the OpenAPI contract and the self-host store). getRecentEvents stays newest-first. No daemon change needed; stuck daemons self-heal after deploy. 290/290 cloud package tests pass + regression tests added.

This also explains item #2 here (empty _index.json for projects/teams was a red herring — those records simply never synced because of the event-ordering freeze; the index files were stale bootstrap artifacts). Items #3–#7 (the relayfile mount/start CLI footguns) remain open in this repo.

[khaliqgant]

Correction to my previous comment re item #2: I overstated that. The empty _index.json for linear/projects/linear/teams is not a red herring — it's served directly by the cloud (relayfile tree rw_fc7b534b linear/projects shows _index.json = [] (size=3, rev_46181) sitting next to a real project record 779cbfda…json). So the index aggregation genuinely isn't being populated for these providers even though the record files exist — a separate cloud-side bug, independent of the event-ordering fix in cloud#862. Item #2 stays open on its own.

[khaliqgant]

Split for focus: the P1 sync bug here is fixed by AgentWorkforce/cloud#862. All remaining items (CLI footguns, daemon recovery robustness, empty _index.json, and the full-tree export stall) are now tracked in #175. This issue can be closed once #862 merges/deploys.

[khaliqgant]

Closing: the P1 sync bug is fixed in AgentWorkforce/cloud#862; all remaining items moved to the focused #175.