Folder sync status

Read whether folders are syncing from the file a running folder watch keeps for other programs on the computer.

While marfa folders watch runs, it keeps the state of its folders in folder-watch.json. A menu bar app, a status script or any other program on the computer can read it without a credential, the network or a folder's store. Keep folders syncing covers the watch itself.

Where it is

The file sits beside the folder registry, folders.json:

SystemDirectory
macOSLibrary/Application Support/Marfa under the home directory
Elsewhere$XDG_DATA_HOME/marfa, or .local/share/marfa under the home directory
Either, with MARFA_FOLDER_REGISTRY setThe directory of the file it names

Parse the whole file on each read. A watch replaces it in one step, so a read never finds half of one. The file holds no credential, no name of a file inside a folder and no item content: a folder's directory and its ID are the only names in it.

The shape

A watch of every folder, with <notes-directory> for the folder's absolute path:

{
  "version": 1,
  "processes": [
    {
      "pid": 72786,
      "build_version": "0.0.80",
      "started_at": "2026-11-19T00:05:50.939Z",
      "heartbeat_at": "2026-11-19T00:06:13.980Z",
      "heartbeat_interval_seconds": 5,
      "ended_at": null,
      "folders": [
        {
          "dir": "<notes-directory>",
          "folder": "01a1f11f-27d4-73fe-9429-dfc839d24eb9",
          "watching": true,
          "reason": null,
          "last_success_at": "2026-11-19T00:05:51.293Z",
          "first_sync_waiting": false,
          "problems": [],
          "pending_uploads": 0,
          "pending_downloads": 0,
          "paused_removals": 0
        }
      ]
    }
  ]
}

processes has one entry for each watch on the computer: one for a watch of every folder, and one for each watch of a single directory. A watch rewrites only its own entry.

FieldTypeDescription
pidnumberThe watch's process ID.
build_versionstringThe version of the CLI that runs the watch, as marfa --version prints it. One that differs from the installed CLI's is a watch still running an earlier build.
started_atstringWhen the watch started.
heartbeat_atstringWhen the watch last wrote its entry.
heartbeat_interval_secondsnumberA running watch writes its entry at least this often: 5.
ended_atstring or nullWhen the watch stopped, on Ctrl-C, SIGTERM, the end of --for-seconds or a failure. null while it runs.
foldersobject[]The folders the watch was asked to hold. A watch of every folder lists every folder the registry lists.

Each folder holds:

FieldTypeDescription
dirstringThe folder's directory.
folderstringThe ID of its system.folder item.
watchingbooleanWhether the watch holds the folder now. A folder tried again after a failure counts once its watch has lasted about 10 seconds.
reasonstring or nullWhy the folder isn't watched. null while it is, and for a folder not yet tried.
last_success_atstring or nullWhen a complete sync last finished with nothing pending and no blocking problem. null until one does.
first_sync_waitingboolean or nullWhether the first sync waits for marfa folders confirm.
problemsobject[] or nullThe current problems, each a code with its count.
pending_uploadsnumber or nullFiles with changes waiting to be scanned or sent.
pending_downloadsnumber or nullFiles the latest pull couldn't write.
paused_removalsnumber or nullRemovals waiting for confirmation, from the disk and from the server.

The last six fields are the folder's latest report to the server, the one marfa folders health reads (how a report is counted). They keep their last values while the folder isn't watched. Until this watch has read a report for the folder, all six are null, so null in problems means unknown and [] means none, except that first_sync_waiting is true while that is the reason.

Reasons

A watch of every folder tries an unwatched folder again, and reason changes with each attempt.

reasonMeaning
first_sync_waitingThe first sync waits for marfa folders confirm.
missingThe folder's directory can't be found, as on a disk that isn't connected. marfa folders remove takes the folder off the list.
handed_overA command such as marfa folders confirm asked for the folder, and the watch has let it go until the command ends.
signed_outThe folder's sign-in has ended. It's watched again once marfa login keeps a new credential.
no_credential, no_keychain, unauthorizedThe watch has no credential it can use for the folder's server.
Another codeThe error that keeps the folder out, such as io.

Problem codes

problems uses a closed set of codes:

codeCounts
conflictConflicted copies not yet resolved.
refusedFiles with a write the server refused.
credential_refused1 when the server refused the credential.
unreadableFiles and directories that can't be read. A file under an unreadable directory isn't counted again.
held_fileFiles held for any other reason, such as a name clash or a paused addition.
unavailable1 when the server can't be reached, or answers the folder's changes with 403, 429 or a 5xx.
root_gone1 when the folder's directory is missing.
settings_invalid1 when the folder's settings file can't be used or written.

While a folder's copy fills, as a new folder's does, it reports no problem for the fill itself. unavailable then means the latest attempt couldn't reach the server, and goes once a retry is filling (folder-sync/health-hydrating).

Decide whether an entry is current

An entry is current when ended_at is null, and heartbeat_at is no later than now and less than three heartbeat_interval_seconds before it. A folder is watched now when a current entry lists it with watching: true.

  • A watch that stops sets ended_at and marks each folder watching: false.
  • A watch that's killed, or whose computer loses power, can't. Its entry keeps watching: true and ended_at: null, and its heartbeat ages past three intervals.
  • A process ID can be reused, so checking that pid still runs is a quick hint; the heartbeat decides.
  • One folder can appear in two entries. A watch of every folder lists a folder that a watch of its directory holds as not watched.

A watch drops the entries of other processes whose heartbeat is an hour old or lies in the future.

When the file can't be written

A watch writes under a lock on folder-watch.lock, beside the file, and never waits for it. When the lock stays held past three intervals, or the file can't be written, the watch says so once and goes on syncing, while its entry ages.

The rules are in the contract's record of folder watches, and the CLI's guide to the file.

On this page