boxglow 0.4.0 → 0.4.1

package/README.md

@@ -100,11 +100,20 @@ The web app opens a local `boxglow.json` directly only in Chrome / Edge (File Sy
 
 ### Save conflicts and recovery
 
-CLI, local server and VS Code writers share a file lock (a `<file>.boxglow-lock` folder that records its owner). Writers wait a few seconds for each other, a lock left behind by a crashed process is recovered automatically, and concurrent CLI commands reload and retry. CLI/server saves compare the read revision and replace the file atomically; a stale writer must reread instead of replacing newer changes. The local API requires `If-Match` from the GET response's ETag, same-origin requests, an allowed loopback Host, JSON content type, valid schema/references and a body of at most 5 MiB.
+CLI, local server and VS Code writers share a file lock (a `<file>.boxglow-lock` folder that records its owner: pid, host, OS, process-ID space and process start). Writers wait a few seconds for each other and concurrent CLI commands reload and retry. A lock is recovered automatically only when its owner is confirmed gone: same host, same OS, same process-ID space, and the pid no longer exists or now belongs to a different process. The process-ID space can be verified on Linux (including WSL); on Windows and macOS a leftover lock is never taken automatically and is removed with `boxglow unlock`. CLI/server saves compare the read revision and replace the file atomically; a stale writer must reread instead of replacing newer changes. The local API requires `If-Match` from the GET response's ETag, same-origin requests, an allowed loopback Host, JSON content type, valid schema/references and a body of at most 5 MiB.
 
 The GUI retains unsaved edits when a save fails or another writer changes the file. Its persistent notice offers retry, JSON export and an explicit three-way merge. Changes to different fields are both kept; for a field changed on both sides, **Compare and choose** shows the two values side by side and you pick one (the choice and both values are recorded in the activity log). Export unsaved JSON for a separate backup. VS Code shows Saved only after `applyEdit`, `document.save()` and disk-content confirmation succeed. A 10-second acknowledgement timeout remains Unsaved and permits retry.
 
-Direct File System Access opening is **read-only**, with live updates. Use `serve` or VS Code for shared editing; browser file handles cannot participate in the Node writer lock. Import JSON still creates a separate browser copy. All editors writing a shared file must use compatible Boxglow versions; unrelated programs and older versions do not honor the cooperative lock. **Versions and connection** at the bottom right of the UI shows the versions of the GUI, the connected CLI server and the VS Code extension; for the CLI alone use `boxglow --version` (`boxglow version --json` for details). If a process crashes leaving `<plan>.boxglow-lock`, first stop the associated Boxglow writers and verify no save is running, then remove that empty lock directory and retry. Never remove an active writer's lock.
+Direct File System Access opening is **read-only**, with live updates. Use `serve` or VS Code for shared editing; browser file handles cannot participate in the Node writer lock. Import JSON still creates a separate browser copy. All editors writing a shared file must use compatible Boxglow versions; unrelated programs and older versions do not honor the cooperative lock. **Versions and connection** at the bottom right of the UI shows the versions of the GUI, the connected CLI server and the VS Code extension; for the CLI alone use `boxglow --version` (`boxglow version --json` for details). A live writer's lock is never taken away just because a save takes a long time, and a lock whose owner cannot be verified is never taken automatically either: another host, another OS on the same machine name (Windows and WSL have separate process IDs), another container, Windows or macOS (no verifiable process-ID space), a lock written by 0.4.0 or older, a missing, unreadable or malformed owner record, or an interrupted recovery. In those cases commands stop with a message that names the owner and the verdict.
+
+```bash
+npx boxglow unlock                                             # show the lock: owner, verdict, token (read-only)
+npx boxglow unlock --remove --lock-token <token> --actor human # a person removes it
+```
+
+Before removing, stop every Boxglow that has the plan open (CLI, `serve`, VS Code; on every OS and machine involved). `unlock --remove` refuses when the owner is confirmed running, when another writer is confirmed to be in the middle of recovering it, or when the lock changed after it was shown. Release, automatic recovery and manual removal all take the same exclusive marker inside the lock before moving it and re-check which lock they hold it on, so a lock that a newer writer has taken in the meantime is not moved. A marker is published together with its owner record (never as an empty placeholder). Markers left by an interrupted recovery can only be taken over by `unlock --remove`, by adding a higher-numbered marker (existing markers are never renamed or deleted), and only when none of the existing markers belongs to a writer confirmed running. When that owner cannot be verified from here (another OS or machine, Windows, macOS), the takeover relies on you having stopped it: do not run two removals of the same lock from different environments at the same time. Agents may run `unlock` to read the status but ask a person to remove the lock.
+
+**Upgrading from 0.4.0**: update the CLI, `serve` and the VS Code extension together and restart any that are still running. 0.4.0 takes over locks by elapsed time and does not read the new owner fields, so mixing 0.4.0 and 0.4.1 writers on one plan is not safe.
 
 ## MCP server