A backup whose lock is lost stops with one line, not a stack trace (closes #184)

proper-lockfile's default onCompromised throws from a timer, so a backup
whose backup.lock was removed or taken over by another backup died with
a stack trace. lockBackupDirectory now returns the lock, its release
function and why it was lost, and passes a handler that only records
the reason. The backup checks it after the refresh and before each
original, thumbnail, file's JSON and album, and before it writes
failures.json, and then fails with "lost the lock on DIR: REASON",
which quak backup prints as one line, exiting 1. lib.backup() takes a
caller's lock as lock, in place of lockHeld: true. Releasing a lost lock
leaves backup.lock alone, since it may be another backup's.

Model: opus-5-5

README.md

@@ -761,9 +761,9 @@ drops it.
 `backup.lock` keeps two backups of the same directory from running at once, such
 as a cron run that starts while the previous one is still going. A backup
 creates `<dir>` if it is missing and takes the lock before its refresh, and
-removes the lock when it ends, whether it succeeds or fails; `quak backup` takes
-it before it opens its library, so a refused run sends no request. The lock is a
-directory that
+removes the lock when it ends, whether it succeeds or fails, unless it lost the
+lock (see below); `quak backup` takes it before it opens its library, so a
+refused run sends no request. The lock is a directory that
 [proper-lockfile](https://github.com/moxystudio/node-proper-lockfile) creates
 and keeps touching while the backup runs. A second backup of the directory, from
 another process or the same one, fails at once: `quak backup` prints
@@ -775,6 +775,16 @@ over, so nobody has to remove it. The lock is outside the date folders and
 `collections/`, so it is never taken for an original, and the removal of old
 album directories never touches it.
 
+A running backup loses its lock when someone removes `backup.lock`, or when
+another backup takes it over because the running one left it untouched for 10
+seconds, as a stopped or stalled process does. The backup finds this out the
+next time it goes to touch the lock, which it does every 5 seconds, and then
+stops before it starts another file. The original it is downloading at that
+moment is still stored. It leaves `failures.json` and `backup.lock` as they are,
+since another backup may be using them. `quak backup` prints
+`quak: lost the lock on <dir>: <reason>` as one line and exits 1, and
+`lib.backup()` rejects with `lost the lock on <dir>: <reason>`.
+
 A collection's directory and JSON are named after the collection, and a symlink
 after the file's title, both with unsafe characters replaced. When two
 collections would get the same name, or two symlinks in one collection the same
@@ -1060,21 +1070,24 @@ photos newest first). `lib.subscribe({ onChange })` delivers a `LibraryChange`
   directory, and fails at once with an error whose `code` is `ELOCKED` while
   another backup of it runs. A caller can instead take the lock itself, before
   it opens its library, as `quak backup` does: `await lockBackupDirectory(dir)`
-  takes it, failing the same way, and returns the function that releases it, and
-  the caller passes `lockHeld: true` to the backup. It waits for a refresh as
-  `fresh()` does, puts every in-scope original not already at its save path
-  there as `photo.download()` does (and, with `includeThumbnails`, fetches
-  thumbnails) through the content cache, waits for an ML data fetch, and
-  rebuilds the on-disk backup tree with a durable failure ledger. Each file's
-  JSON holds its ML data and, for an image (for a live photo, its image), its
-  original's EXIF and XMP, with its dimensions for a JPEG only; a video's JSON
-  holds none of these three. A fetched original is written straight to its save
-  path and not into the cache, which then counts it as present; one the cache
-  already held is copied from there. `BackupOptions`: `downloadDirectory` (falls
-  back to the library's), `includeOriginals` (default `true`),
-  `includeThumbnails` (default `false`), `onlyAlbumNames`, `verify` (default
-  `false`), `onProgress`, and `lockHeld` (default `false`). See Backup layout
-  above for the tree it writes.
+  takes it, failing the same way, and returns a `BackupLock`, whose `release()`
+  removes the lock unless it was lost and whose `lost` holds why it was lost.
+  The caller passes it to the backup as `lock`, and releases it once the backup
+  ends. It waits for a refresh as `fresh()` does, puts every in-scope original
+  not already at its save path there as `photo.download()` does (and, with
+  `includeThumbnails`, fetches thumbnails) through the content cache, waits for
+  an ML data fetch, and rebuilds the on-disk backup tree with a durable failure
+  ledger. Each file's JSON holds its ML data and, for an image (for a live
+  photo, its image), its original's EXIF and XMP, with its dimensions for a JPEG
+  only; a video's JSON holds none of these three. A fetched original is written
+  straight to its save path and not into the cache, which then counts it as
+  present; one the cache already held is copied from there. `BackupOptions`:
+  `downloadDirectory` (falls back to the library's), `includeOriginals` (default
+  `true`), `includeThumbnails` (default `false`), `onlyAlbumNames`, `verify`
+  (default `false`), `onProgress`, and `lock`. See Backup layout above for the
+  tree it writes. Whether the backup took the lock or its caller did, once the
+  lock is lost the backup rejects with `lost the lock on <dir>: <reason>` before
+  it starts another file.
 
 ### Request pools
 
@@ -1134,7 +1147,7 @@ from a very old client, is stored unchecked.
 - `src/library/mlsearch.ts`: `MLDataAPI`, `SimilarResult`
 - `src/exif.ts`: `ExifTags`, `PhotoExif`
 - `src/library/pools.ts`: `RequestPools`, `RequestPoolsOptions`, `BoundedPool`
-- `src/backup.ts`: `BackupOptions`, `BackupResult`, `BackupError`
+- `src/backup.ts`: `BackupLock`, `BackupOptions`, `BackupResult`, `BackupError`
 - `src/client.ts`: `Client`, `LoginOptions`, `ClientSnapshot`
 - `src/api/client.ts`: `ApiClient`, `ApiClientOptions`, `StreamOptions`
 - `src/errors.ts`: `ApiError`, `TruncatedStreamError`