merge: P11a, the AppImage restart, the daily staged update, the unsigned macOS bundle in CI (branch P11a, 310fa105)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HS8WZziDnyxunC23MUxrLp

docs/architecture.md

@@ -355,9 +355,21 @@ downgrading is theirs). Anything else (an AppImage, whose file is named by
   without the agent noticing. The format gate stays the server's (3.9):
   `rollback` refuses while a book declares a format or feature the kept
   version does not know;
-- an AppImage is the exception to the restart: the host runs from the old
-  image's mount, whose path does not change, so it keeps running the old
-  version until the books are next closed and opened (docs/packaging.md).
+- an AppImage runs the program from a mount that goes away with the image,
+  so the host learns the image's own path from `APPIMAGE` (the one variable
+  `start.rs` adds to its scrubbed environment, only when it names an
+  absolute file; the host reads it about itself and never tells an agent),
+  runs and restarts from that file, and tells a replaced program by its
+  inode, size and last write, like any other;
+- updates are also **staged** (step 4): while the books are open the host
+  looks at the feed at most once a day (`update_check` knob; the look is
+  noted in `updates/checked`), and only downloads and verifies a newer
+  release into `<root>/updates/staged/`. It never swaps. The staged program
+  is applied by an opener just before it starts a host (no host runs, so no
+  call is cut off), after a second check against the key, or by
+  `wanderbooks update`, the owner's say-so, which reuses the staged copy. A
+  local release is named in `<root>/updates/feed` (a `file://` address, then
+  the key file), the same rule as `--trusted-key`.
 
 `deploy/packaging/` holds the Linux packaging: `packager.toml`
 (cargo-packager: `.deb`, AppImage, the pacman tarball with its PKGBUILD),
@@ -365,7 +377,9 @@ the rpm table in `crates/ledger-cli/Cargo.toml`, `aur/PKGBUILD` (the AUR
 package, which repacks the release's tarball), `build-linux.sh`,
 `repo-indexes.sh` (the apt and dnf indexes), `local-release.sh` (a
 throwaway-keyed feed on this machine) and `test-linux-packages.sh`.
-`.github/workflows/release.yml` builds them on a version tag.
+`.github/workflows/release.yml` builds them on a version tag. The macOS
+bundle is `packager-macos.toml`, `Info.plist` and `build-macos.sh` (an
+unsigned `.dmg` from CI's `macos` job; signing and notarization are step 5).
 
 ## The result envelope and the guards (`ledger-mcp`, P5)
 

docs/packaging.md

@@ -16,8 +16,8 @@ not a tool, so there is nothing for a recipe to call.
 | `.rpm` | `cargo-generate-rpm` (table in `crates/ledger-cli/Cargo.toml`) | same paths, marker `rpm`; 36 MB | dnf repository (`repo-indexes.sh dnf`) | unsigned until step 5 (`--signing-key` takes the PGP key then) |
 | AUR `PKGBUILD` | `cargo packager` makes the tarball (`pacman` format) and a PKGBUILD for it; ours is `deploy/packaging/aur/PKGBUILD`, which repacks the release's tarball (package `wanderbooks-bin`) | same paths, marker `aur`; built with `makepkg` | pacman (the AUR keeps old PKGBUILDs) | n/a (pacman trusts the AUR's checksums) |
 | AppImage | `cargo packager` (`appimage`); 44 MB | one file the owner puts anywhere and runs; needs no admin password | `wanderbooks update` (`$APPIMAGE` is the file replaced) against the manifest; minisign | minisign by the release key (step 5) |
-| `.dmg` | `cargo packager` (`dmg`) | (trial) needs a Mac | `wanderbooks update` | Developer ID and notarization (step 5) |
-| NSIS `.exe` | `cargo packager` (`nsis`) | (trial) needs Windows, and native Windows is unit P11c (D-62) | `wanderbooks update` | the Windows identity (step 5) |
+| `.dmg` | `cargo packager` (`dmg`), `deploy/packaging/build-macos.sh`; **built in CI, unsigned; the trial on a Mac is the owner's** | `Wanderbooks.app` dragged to Applications; no admin password (the trial will say) | `wanderbooks update` (it replaces the program inside the `.app`: see the note below) | **unsigned**; Developer ID and notarization are step 5 |
+| NSIS `.exe` | `cargo packager` (`nsis`) | **not built**: native Windows is unit P11c (D-62) | `wanderbooks update` | the Windows identity (step 5) |
 
 `just package-linux` builds the first four (`deploy/packaging/build-linux.sh`,
 about a minute after the release build, itself 8 to 12 minutes on a
@@ -64,21 +64,18 @@ What the trial found, each of which is built around now:
    manifest's `signature` is that `.sig` as written, and `update` reads the
    public key in either form. Checked end to end by hand (below), and by
    `a_public_key_is_read_in_every_form_minisign_and_the_packager_write_it`.
-7. **The AppImage updates itself but the books it holds do not restart
-   onto the new image.** `update` replaces `$APPIMAGE`, and an AppImage run
-   from a shell (`Wanderbooks.AppImage update`, or the one that was running)
-   proves the swap and the rollback: after `update`, the AppImage on disk
-   is the new file, the old one is kept, and `rollback` restores it. But the
-   host that is open runs from the old image's mount
+7. **The AppImage updates itself, and (since step 4) the books it holds
+   restart onto the new image.** `update` replaces `$APPIMAGE`. The host
+   that is open used to run from the old image's mount
    (`/tmp/.mount_*/usr/bin/wanderbooks`), a path that does not change, so
-   `host.rs` never sees a replaced file and the open books keep the old
-   version until they are closed and opened again (`wanderbooks close`).
-   Fixing it means the host learning the image's path (its environment is
-   scrubbed on purpose; `APPIMAGE` would join the allow-list of `start.rs`,
-   or the path would come from the mount table) and starting its successor
-   from it: a decision about what the host may trust, left to the EM (the
-   unit's report names it). Package installs and a hand-placed executable
-   restart as designed (`bridge_survives_update`).
+   it never saw a replaced file. The host now reads `APPIMAGE` (it is in
+   the allow-list of `start.rs`'s scrubbed environment, only when it names
+   an absolute file; a path the host reads about itself and never tells an
+   agent), runs and restarts from that file, and tells a replaced program
+   by its inode, size and last write. Tested without FUSE by
+   `a_replaced_appimage_restarts_the_books` (the programs run from one
+   copy while `APPIMAGE` names another, as a mount does); not run against
+   a real image mount in this wave.
 8. **Onboarding with no terminal does not exist yet.** The unit's Done-when
    (1) says an AppImage "opens, onboards and posts an entry with no
    terminal". The AppImage opens (a bare launch is the viewer), but the viewer
@@ -118,6 +115,43 @@ package manager. Not tested: Ubuntu, openSUSE, a package-manager
 *downgrade* (the repositories keep every release by construction), and the
 `.rpm` and `.deb` under their real signatures (step 5).
 
+## The macOS bundle (step 6, built in CI, unsigned)
+
+`deploy/packaging/packager-macos.toml` (cargo-packager: the `dmg` format,
+which makes the `.app` first; the icon is the 512 px PNG, made into an
+`.icns` by the packager; `minimum-system-version` 11.0), `Info.plist`
+(merged into the generated one: one viewer at a time, no discrete GPU),
+`build-macos.sh` (the same shape as the Linux script, in portable shell
+because macOS has BSD `sed`) and `just package-macos`. The `macos` job of
+`.github/workflows/release.yml` runs on `macos-latest` (Apple silicon: the
+manifest key is `macos-aarch64`; an Intel build is not made), uploads the
+`.dmg` as a run artifact (named `macos-dmg-unsigned`) and, on a tag,
+attaches it to the release. **It is not signed or notarized** (step 5: the
+owner's Developer ID and Q-4), so Gatekeeper refuses it on a Mac that
+downloaded it; the owner opens it with right-click, Open. What was checked
+here, on Linux: the config parses under cargo-packager 0.11.8's strict
+schema (unknown keys are errors) and the script's `sed` is the portable
+subset. **Not checked: that the `.dmg` builds, mounts or runs**: that needs
+the CI run (Actions, release, Run workflow, this branch) and then a Mac.
+Open items for the trial on a Mac: whether `wanderbooks update` replacing
+the program inside a signed `.app` breaks its signature (it will: step 5
+must decide, probably by updating a whole `.app`); the translocated-app
+check (`translocated_app_refuses_to_connect`) is not built.
+
+## Updates staged by the host (step 4)
+
+The host looks at the feed at most once a day while the books are open
+(`update_check`), and downloads and verifies a newer release into
+`<root>/updates/staged/` with a `meta.json` (version, sha256, signature,
+notes). It never swaps. The next opener that starts a host applies it
+first; `wanderbooks update` applies it too and reuses the staged copy;
+`update --check` says "already downloaded". A local release is named by
+`<root>/updates/feed` (a `file://` address, then the key file). Without a
+compiled-in release key and without that file, the look does nothing but
+log why. Not built: the in-app "restart now to update" choice and the
+viewer's notice, which need an admin-socket intent and a place in the
+viewer (see the unit's As-built block).
+
 ## What `update` and `rollback` need from a release
 
 `manifest.json` at `releases/latest/download/` (D-26):

docs/testing.md

@@ -3711,6 +3711,25 @@ it (the same program with a tail, so its hash differs). All in
   file now on disk (not a deleted one). The host's own restart laws stay
   `open_while_held.rs`'s (`a_restart_is_not_a_close`).
 
+Step 3's gap and step 4 (same file):
+
+- `a_replaced_appimage_restarts_the_books`: the programs run from one copy
+  (a mount's) while `APPIMAGE` names another (the image); `update`
+  replaces only the image; the host restarts onto it (its `/proc/PID/exe`
+  is the image), the mount's copy is untouched, the session writes on.
+- `the_host_stages_a_daily_update_and_the_next_start_applies_it`: with a
+  local feed named in `updates/feed`, the host stages 9.0.0 by itself;
+  the program, the host and the session are unchanged meanwhile; after
+  `close`, the next opener applies it (the old program is kept, the staged
+  folder gone) and the books are as they were.
+- `a_daily_update_that_is_not_ours_is_not_staged`: a signature by another
+  key, then a wrong sha256, each looked at and neither staged.
+- `update_installs_the_copy_the_host_staged_without_downloading_again`: the
+  release's file is deleted; `update` installs from the staged copy.
+- `a_staged_update_that_was_tampered_with_is_dropped_not_applied`: a staged
+  file edited together with its recorded checksum fails the signature; the
+  next start drops it and runs the old program.
+
 Unit tests in `update.rs`: `versions_are_three_numbers_and_order_by_number`,
 `a_package_marker_beside_the_program_makes_it_package_managed`,
 `a_manifest_address_is_resolved_beside_the_manifest`,