memoir-cli 3.14.0 → 3.16.0

package/README.md

@@ -8,14 +8,14 @@ The reliability changes are described in [the remediation record](docs/AUDIT-REM
 
 ## Continue between Codex and Cursor on this computer
 
-This branch adds a separate, project-only handoff. It carries answered questions,
+Memoir includes a separate, project-only handoff. It carries answered questions,
 decisions, next actions and receipts from checks actually run through Memoir. It
 does not import personal memory or transcripts.
 
-The project handoff and browser view require version 3.14.0 or later:
+The project handoff, browser view and recovery commands below require version 3.16.0 or later:
 
 ```sh
-npm install -g memoir-cli@3.14.0
+npm install -g memoir-cli@3.16.0
 cd /path/to/your/project
 memoir work setup
 memoir work resume
@@ -51,9 +51,14 @@ sync those files through GitHub or bridge different checkouts. See the
 privacy boundaries and when a check needs to run again. The feature runs locally even when installed from npm; publishing the package
 does not upload your project ledger.
 
+Project handoffs now have automatic local recovery snapshots. Run `memoir work
+doctor` to check them, or `memoir work backup --output /path/to/backup.memoir`
+for an encrypted copy outside the project. Recovery previews changes before
+applying them and preserves the original file. See [backup and recovery](docs/PROJECT-RECOVERY.md).
+
 ## Existing memory and backup workflow
 
-Node.js 18 or later is required.
+Node.js 18 or later can run the CLI. For production use, choose a maintained LTS release (Node 22 or 24); Node 18/20 remain compatibility-test targets. See the [Node release policy](https://nodejs.org/en/about/previous-releases).
 
 ```sh
 npm install -g memoir-cli
@@ -168,6 +173,6 @@ npm audit --omit=dev
 npm pack --ignore-scripts
 ```
 
-Tests use synthetic homes and local Git remotes. CI declares macOS/Linux/Windows with Node 18/20/22; shell suites skip Windows. See [remediation status](docs/AUDIT-REMEDIATION.md) and [release gates](docs/RELIABILITY-ROLLOUT.md) for verification limits.
+Tests use synthetic homes and local Git remotes. CI declares macOS/Linux/Windows with Node 18/20/22/24; shell suites skip Windows. See [remediation status](docs/AUDIT-REMEDIATION.md) and [release gates](docs/RELIABILITY-ROLLOUT.md) for verification limits.
 
 [MIT license](LICENSE)

package/docs/LOCAL-PRODUCTION-VALIDATION.md

@@ -0,0 +1,71 @@
+# Local handoff hardening — September 6, 2026
+
+This change targets the single-user CLI/MCP workflow and its loopback browser
+companion. It does not turn the companion into a public multi-user service.
+Publication is subject to the release workflow; registry availability and CI
+results must be checked against the actual release rather than this document.
+
+## What changed
+
+- Automatic bounded recovery snapshots protect every acknowledged project save.
+  Existing version-1 ledgers are checkpointed on the updated resume path.
+- `work doctor`, `work backup` and `work recover` expose health, encrypted export
+  and preview-bound recovery. Current bytes are preserved before replacement.
+- A recovery generation prevents stale CLI/MCP/browser sessions and in-flight
+  checks from overwriting a restored handoff. Normal revision guards remain.
+- Publication now depends on the entire reusable CI workflow. Node 24 is added
+  to the Node 18/20/22 matrix across Linux, macOS and Windows. Node 22/24 are the
+  maintained LTS targets for production; older versions are compatibility tests.
+
+## Observed local evidence
+
+| Exercise | Result |
+| --- | --- |
+| Full local suite | 25 suites passed on macOS/Node 26.7.0; subsequent focused checks cover the added crash and browser-generation cases |
+| Recovery regression | 15 groups cover acknowledged snapshots, old-ledger upgrade, damaged/missing ledgers, exact preview conflicts, stale writers, concurrent recovery/check execution, all-branch encrypted round trips, malformed/secret-bearing imports, symlinks, failed writes, process crash, retention, CLI errors and Windows delete-pending retries |
+| Browser harness | 31 scenarios pass, including retaining an open draft's old generation until the recovered record is explicitly reviewed |
+| Existing regressions | 17 handoff groups, 21 adversarial scenarios and 14 browser API/security groups pass |
+| Installed tarball | CLI, project MCP, local view, encrypted export, damaged-ledger recovery, unchanged client settings and post-recovery MCP continuation passed in a synthetic home |
+| Dependency advisory audit | No known production-dependency advisories were returned at test time |
+
+The actual Cursor desktop connection was reloaded using its existing **Reload**
+control. Direct `memoir_work_resume` returned the current delivery and privacy
+answers and identified `src/work/store.js` as changed. Cursor saved
+`decision.cursor-production-resume` at revision 119 through MCP and read it back.
+Returning Codex read that record. No fallback, repeated question, check rerun or
+source edit was requested from Cursor in that bounded exercise.
+
+In an actual in-app browser, a synthetic project answer was opened for editing.
+The project was recovered while that draft stayed open. Saving was refused;
+the draft remained intact. **Review latest version → Keep my draft and continue
+→ Save correction** saved the deliberate correction. A separate CLI reader
+recovered that answer at revision 2, and `doctor` reported a valid current copy.
+The temporary project and browser were removed after validation.
+
+A separate local drill restored a snapshot of the real project ledger at
+revision 120 into a temporary folder after deliberately damaging only that
+copy. All 64 record-history entries, 54 check receipts and two retractions
+matched the source. The real ledger remained unchanged. No real project data
+was uploaded, and no encrypted export passphrase was created for the user.
+
+## What these results establish
+
+The new failure handling was exercised in source tests, an installed artifact,
+the actual browser, Cursor MCP and a real-data copy. Local protection is
+enabled for this checkout, and the original app settings remain in place.
+The release pipeline must separately establish cross-platform results and
+validate the published npm artifact.
+
+These tests are not an independent security certification, a power-cut test of
+every filesystem, or proof of productivity gains over multiple days. Receipts
+remain local and unauthenticated; project text is untrusted. Local snapshots
+and quarantine are plaintext, and secret screening is heuristic. Losing the
+entire folder/disk needs a separately stored export. See the
+[recovery guide](PROJECT-RECOVERY.md) for downgrade restrictions, capacity,
+retention, filesystem boundaries and the remaining manual lock-repair case.
+
+The first expanded CI run caught a Windows/Node 18 delete-pending race on
+`work.lock`. Path inspection and exclusive lock acquisition now retry transient
+Windows access failures without skipping validation or entering without a lock.
+A deterministic denial/concurrency regression accompanies the fix. Manual
+publication also requires a version tag matching the package.

package/docs/PROJECT-HANDOFF.md

@@ -18,6 +18,52 @@ This documents the local project handoff in `src/work/` and `bin/memoir-work.js`
 
 ## See and correct what Memoir remembers
 
+Memoir remains a CLI and tool integration. This optional browser companion reads
+the same project record; it is not a separate memory service. You can keep using
+the CLI, Codex or Cursor without opening the page.
+
+The default **Records** view shows open actions, saved answers and check evidence.
+**Records** and **Map** share one workspace, search box and category navigation.
+Switching views keeps the search and category. Records use readable rows with
+short headings and expandable text; source history stays available on each entry.
+
+The **Map** view connects the current branch's project entries. Select a
+node to read its full text, source and history, and inspect connected entries.
+Solid lines show project membership, explicit record references, or a named file
+that a check declares as input. A file link does not prove the entry's claims.
+Suggested links are off by default. Enable **Suggested links** to include possible
+shared topics around a selected entry; dashed lines distinguish these word
+matches from recorded references. Each suggestion explains its words and is not
+saved as a relationship. This prototype does not infer
+causes, automatically determine affected work, or use personal memory.
+
+Search and category filters narrow the map. The overview shows up to six entries
+around the project; selecting an entry centers it and shows up to six direct
+neighbors, with recorded references first. Lines connect only to that center.
+It computes connections within up to 120 entries, prioritizing matches and the
+selected entry. Search covers all active entries, including older ones, but the
+visible map and connection list are not exhaustive. No text leaves the browser
+to generate these connections.
+
+**Records** provides the overview and category lists for editing. The overview
+shows every open action as a short row; **Details** opens its explanation and
+controls. Saved answers and recent decisions start collapsed. Matching checks
+remain available from the summary and Checks category; only checks needing
+review appear in the overview. Long entries in category lists expand with
+**Read full entry**; completed actions remain under **Next actions**. Both views
+use the same correction controls and project record. **Connections** opens a
+record in the map; **Open in Records** returns to that entry's category. Removed
+items use the Records recovery list and do not enter the active map.
+
+Selecting a map entry opens its details beside the map in wide windows and below
+it in narrow windows. Keyboard focus follows the selected context. Saving from
+either view selects the saved entry, clears the old search and opens its category
+so a filter cannot hide a successful save. Both views search covered file paths as
+well as record text and sources. Overview search includes all matching records,
+including completed actions and goals, without the overview's two-per-group limit.
+See [the project map trial](PROJECT-MAP-TRIAL.md) for
+tested behavior and the limits of suggested connections.
+
 Run `memoir work view` in your project (or `node bin/memoir.js work view`
 from a source checkout), or ask the agent
 “Open my Memoir project view.” The browser shows the current branch's answers,
@@ -253,3 +299,7 @@ The saved `check.project-handoff` result (revision 5) still matched its declared
 A later resume carried forward `decision.client-route` (revision 10), whose source reports that Cursor's project connection was enabled, showed four tools, and successfully called `memoir_work_resume` on 2026-09-06. This is saved project evidence from the local client test; the documentation review did not repeat that test or inspect external app settings.
 
 In this Codex session, the configured MCP resume call returned “MCP tool call requires approval, but approval policy is never.” The documented CLI fallback succeeded. No policy or app setting was changed by this review. Successful CLI continuation does not establish successful Codex MCP use. Source labels are claims, not authentication, and saved client observations do not verify current external settings. Those settings and current client acceptance need verification before claiming they still work; such verification was outside this documentation-only continuation.
+
+## Backup and recovery
+
+Saves now include automatic local snapshots. Run `memoir work doctor` to check them. See [the recovery guide](PROJECT-RECOVERY.md) for encrypted exports, recovery previews, and the required post-recovery `expected_recovery` value.

package/docs/PROJECT-MAP-TRIAL.md

@@ -0,0 +1,149 @@
+# Project map trial — 2026-09-06
+
+The map is functional, but this trial does not establish that it is faster than
+the Records view. It is useful for following explicit references to check
+evidence. Direct answers are already easy to find in Records, and keyword
+suggestions still include weak connections.
+
+## Actual browser tasks
+
+Tested against this checkout's real project record in the Codex in-app browser.
+The starting ledger was revision 70, with 27 active entries. Existing answers and
+check evidence were read before starting; no setup questions were repeated.
+
+| Task | Map | Records | Finding |
+| --- | --- | --- | --- |
+| Find the saved privacy boundary | One node selection from the default map | Answer already present in Overview | No advantage for the map on this direct lookup |
+| Read the complete saved publication blocker | One node selection | One **Read full entry** activation from Overview | Both expose the same saved blocker; external account state was not reverified |
+| Find checks covering `docs/PROJECT-HANDOFF.md` | Evidence filter plus file search | Checks category plus file search | Records initially returned no result; fixed to search covered files too |
+| Follow the documentation decision to its check | Search for the document, select the decision, follow **Recorded link** | Category/file search finds the check separately | The map exposes the reference and explains the file relationship |
+| Decide which checks need another look | Linked receipt named changed UI files | The same receipt named the same changes | Changed inputs were visible; unchanged CLI/MCP receipts were reused |
+
+These are observed control activations, excluding scrolling, switching views and
+test resets. They are not timed human measurements or a randomized comparison.
+The tester already knew the project. Repeated questions: zero in this task;
+that observation is not proof of an improvement against an unassisted baseline.
+
+## Problems reproduced and fixed
+
+1. **Detail panel blocked the map and Reset.** At the actual 742px window width,
+   the fixed panel overlapped Reset; a hit test returned the panel. Below 950px,
+   details now follow the map in normal flow. Selecting a node focuses its
+   heading; Back returns focus to the project. Reset was retested successfully.
+2. **Filtering lost keyboard focus.** After a category click, focus was on the
+   document body because the filter had been replaced. Focus now moves to the
+   replacement active filter. Verified in the real browser and regression test.
+3. **File search disagreed between views.** Records omitted check input paths and
+   source text. Both views now use the same searchable fields. The actual
+   documentation-file search returns the same check in both views.
+4. **A newly saved entry disappeared into the overview.** A real browser save
+   succeeded but did not select the new record; focus fell back to the body.
+   A regression test reproduced it. Map saves now select the saved entry and
+   return focus to its visible correction control. A second real creation and
+   correction verified this behavior. Long entries exposed another case: the
+   first button was a hidden expansion control. Focus now targets card actions
+   explicitly; the regression test includes a long entry.
+5. **Confirmation text had poor contrast.** The dark map inherited light text
+   on the old pale notification background. Map success/error notices now have
+   explicit dark backgrounds and contrasting text. The success message's
+   computed text/background contrast was 10.70:1 in the actual browser.
+
+## Persistence and boundaries
+
+Two project-only trial observations were saved through the actual editor. The
+result record was corrected, temporarily removed and restored through Records.
+A separate process read agent resume after removal and confirmed the result was
+absent. After restoration it recovered the corrected version and preserved
+history. The original privacy and delivery answers remained at revisions 3 and
+50. Existing project decisions, settings and private memory were not rewritten
+for this test.
+
+The map was checked at 390px, the normal 742px window, and 1280px. Details no
+longer overlap the map, and no horizontal overflow was observed. Wide windows
+retain a side panel. This is a focused layout/keyboard check, not a full
+accessibility audit.
+
+At this initial trial, the UI regression suite contained 21 scenarios, including map focus, saving,
+consistent search, exact versus suggested links, older-entry search, and literal
+rendering of synthetic hostile markup. The existing 14 API/security groups cover
+authentication, cross-origin access, stale edits, removal/restore, secret/scope
+rejection and unavailable execution routes. These targeted checks and the guide
+check were captured in the local ledger after the relevant files changed.
+Matching CLI/MCP and adversarial handoff receipts were reused. This was not a new
+production penetration test or a fresh Cursor round trip.
+
+## What remains to establish
+
+- Keyword suggestions are noisy. The privacy answer was linked through generic
+  words such as “user”, “evidence” and “handoff”; the labels explain the match but
+  cannot make it useful. Evaluate suggestions against human-labeled relevant
+  pairs before treating the map as an intelligent project model.
+- The graph computes relationships within at most 120 entries.
+  Search covers all active entries, but connections are not exhaustive.
+- There is no saved relationship editor, automatic impact analysis, natural
+  language retrieval, or measured reduction in time/repeated work from the map.
+- Keep both views available. Next, test unfamiliar users on real project
+  questions and count successful answers, mistaken interpretations and time.
+
+The trial used local, uncommitted changes. No publication, server deployment,
+new account setup or personal-memory import was needed to perform it.
+
+## Follow-up: reduce graph clutter
+
+The user found the graph messy after this trial. The observed overview contained
+24 lines and 11 nodes. The revised view shows six entries around the project,
+with six straight membership lines and no lines between the surrounding entries.
+Selecting an entry moves it to the center and shows only its direct neighbors,
+with at most six links. Labels have larger type and a two-line limit; full text
+remains in the inspector. Suggested links are now off by default and explicitly
+enabled with **Suggested links**. The graph and inspector apply the same filter.
+
+The actual browser showed six lines and seven nodes in the new overview. A check
+with eight recorded connections displayed six; selecting an answer with no
+recorded references showed zero links, then six dashed links after enabling
+suggestions. At 390px, the seven node boxes did not overlap and the page had no
+horizontal overflow. Two new regression cases cover the overview limit and
+direct-neighbor filtering with opt-in suggestions, bringing the UI suite to 23
+scenarios. The underlying keyword-matching quality is unchanged by this cleanup.
+# Shared workspace follow-up — 6 September 2026
+
+Further feedback was that even the unified page required too much reading.
+The overview now shows all open actions as short rows with a **Details** button.
+Saved answers and recent decisions start collapsed; matching check receipts are
+available through the summary and Checks category. Only checks needing review
+appear in the overview. Existing action text was shortened and the explanation
+moved into its rationale; previous full text remains in local history. The npm
+action now reflects the observed password-confirmation screen in Chrome.
+
+The user reported that Map and Records still looked incoherent. The browser now
+opens Records first and uses one header, search, category navigation, color
+palette and correction dialog for both views. Records have a single column of
+readable rows. The former separate sidebar, duplicate introductions and light
+card grid are removed.
+
+Switching views preserves search and category. **Connections** opens the same
+record in the map; **Open in Records** returns to its category. A successful save
+reveals the saved entry and clears filters that could hide it. Overview search
+now includes every matching entry, including goals and completed actions.
+
+Observed in the actual local browser:
+
+- Found the existing privacy answer, opened its correction dialog and cancelled
+  without changing the answer, followed Connections and returned to Records.
+- Searched `src/work/ui/style.css` and found the same three check receipts in
+  Records and Map, including specific changed-input warnings.
+- A search with no results stayed empty after switching views.
+- Created the actual workspace-design decision while an empty search was active.
+  Saving cleared the search, opened Decisions and showed the saved entry.
+- Corrected that decision from Map and confirmed keyboard focus returned to
+  the visible Correct button. Returning to Records showed the correction and
+  its earlier version. Focus restoration now scopes itself to the active view.
+- Inspected Records at the normal window width and 390px, Map at 1280px, and the
+  shared dark editor at 1280px. At 390px the seven overview node boxes did not
+  overlap; the document had no horizontal overflow. Narrow category navigation
+  scrolls horizontally, and map details follow the graph in normal flow.
+
+The changed UI requires targeted UI/API and documentation rechecks. Unchanged
+CLI/MCP handoff and adversarial receipts remain reusable. This is local design
+and functional validation; it adds no independent-user or timed utility study.
+The npm publishing step remains separate from this local preview.

package/docs/PROJECT-RECOVERY.md

@@ -0,0 +1,139 @@
+# Project handoff backup and recovery
+
+Memoir protects `.memoir/work.json` automatically. You keep using the same
+project folder and branch in Codex and Cursor; no extra command is needed for
+each save. The optional browser uses the same protection.
+
+## Check that it is protected
+
+```sh
+memoir work doctor
+```
+
+The result reports ledger health, whether its current contents have a verified
+snapshot, damaged copies and the available snapshot IDs. An unhealthy existing
+handoff exits with status 1 so scripts can detect problems. `empty` describes a
+project with no saved records and exits 0. This checks local data, not account
+security, remote services or the accuracy of stored claims.
+
+Existing handoffs are protected on the first updated `resume` or next write.
+You can also create a copy explicitly:
+
+```sh
+memoir work backup
+```
+
+## Keep a copy outside this project
+
+```sh
+memoir work backup --output /path/to/backups/project-handoff.memoir
+```
+
+Choose an existing destination folder and a **new filename**. The interactive
+terminal asks for a passphrase twice. Use a strong passphrase of at least 12
+characters, kept separately in your password manager. Memoir cannot recover it.
+An export never overwrites an existing file.
+
+For automation, a secret manager can inject `MEMOIR_WORK_PASSPHRASE` into the
+environment. There is no command-line password flag. Do not put that value in
+shell history, project files, a handoff record, or a conversation with an agent.
+The older `MEMOIR_PASSPHRASE` setting is separate and is not changed.
+
+The encrypted file includes **all branches and complete history** of this
+project ledger, including retracted records and check receipts. It excludes
+personal memory, transcripts, raw command output, client settings, other files
+inside `.memoir/`, and recovery quarantine. AES-256-GCM with the existing Memoir
+scrypt passphrase derivation protects the export; import authenticates it before
+parsing. Secret screening remains heuristic. Review project records before
+deliberately sharing an export with anyone else.
+
+Store the export on a separate backed-up device or destination you control.
+Copies inside `.memoir/` cannot protect against loss of the entire folder or
+disk. Git commits, GitHub pushes and the older `memoir push` command do **not**
+transport this ledger. To move to another machine, transfer the encrypted file,
+recover it there, open the matching branch and run `memoir work setup` there.
+Changed files and runtime still cause targeted check warnings.
+
+## Recover a damaged, missing or mistaken handoff
+
+Start with a preview. It does not replace the current ledger:
+
+```sh
+memoir work recover
+```
+
+This selects the newest valid local copy. Review its revision, branch list and
+record counts. To choose another copy, pass an ID returned by `doctor`:
+
+```sh
+memoir work recover SNAPSHOT_ID
+```
+
+Apply the exact reviewed source and fingerprint:
+
+```sh
+memoir work recover SNAPSHOT_ID --apply --expect FINGERPRINT_FROM_PREVIEW
+```
+
+For an encrypted export, use its filename in both steps:
+
+```sh
+memoir work recover --from /path/to/backups/project-handoff.memoir
+memoir work recover --from /path/to/backups/project-handoff.memoir --apply --expect FINGERPRINT_FROM_PREVIEW
+memoir work resume
+memoir work doctor
+```
+
+Recovery replaces the **whole project ledger**, across all branches, rather
+than merging selected records. Review an imported backup in an empty recovery
+folder first if you need to inspect its contents. The fingerprint binds the
+preview to the destination folder, exact current file and source file. A
+concurrent save, changed export, or different target requires a fresh preview.
+Wrong keys, tampering, unsupported formats, invalid history, detected secrets
+and unsafe paths are rejected before replacement.
+
+The original bytes are preserved under `.memoir/work-quarantine/`, including a
+damaged original. Quarantine is private local data and is never exported by this
+command. Do not publish it; malformed originals might contain secrets. If local
+quarantine cannot be written, recovery stops. A missing ledger with surviving
+snapshots also stops normal writes instead of silently starting over.
+
+After recovery, **resume in every tool before saving again**. The handoff
+returns a `recovery_id`; record and retract calls must pass it as
+`expected_recovery` in addition to the existing revision guard. The browser
+handles this itself: stale drafts remain available, and reviewing the restored
+version allows a deliberate correction. CLI retraction takes `--recovery ID`.
+Checks that were still running during recovery cannot overwrite restored
+evidence. New checks capture the current generation automatically.
+
+## Storage, failure handling and upgrades
+
+- Before acknowledging a save, Memoir writes verified-content snapshots of the
+  previous and proposed states, flushes file contents and atomically replaces
+  the ledger. An interrupted save can leave a proposed snapshot that was not
+  acknowledged. The recovery preview says so; it is never restored silently.
+- Normal retention keeps the newest 20 snapshots, plus at most two protected
+  boundary copies. Each contains complete history. Pruning happens only after
+  a successful write; a cleanup problem never makes a committed write look
+  like a failed save. `doctor` reports damaged copies or excess retention.
+- Files are created owner-readable/writable and directories owner-only on
+  POSIX. Local ledgers, snapshots and quarantine are plaintext. Directory
+  flushes run on POSIX; Windows uses flushed files and atomic replacement but
+  cannot guarantee directory power-loss persistence through Node. Filesystem,
+  hardware and same-user compromise remain outside this protection.
+- The ledger limit remains 2 MiB. Reaching it refuses additional writes without
+  dropping history. Keep an encrypted export and start a separate project
+  handoff when the working ledger is full; automatic compaction is not provided.
+- Upgrade all connected clients before recovery. Ordinary version-1 ledgers
+  remain readable; a recovered ledger adds a recovery generation. Older Memoir
+  versions reject that field rather than safely participating. Keep a
+  pre-upgrade export if you need a downgrade. Restart existing MCP connections
+  after upgrading so they load the current server; preserve their approvals.
+- A busy lock does not justify deleting it while another process is running.
+  Retry once that operation ends. A leftover `.reaper` lock after a crash needs
+  local inspection with all Memoir writers stopped; this release does not
+  provide a general filesystem lock repair tool.
+
+Recovery preserves local observations; it does not authenticate their authors
+or certify their conclusions. Existing check-input comparisons still apply.
+External settings need fresh verification independently of any backup.

package/docs/RELIABILITY-ROLLOUT.md

@@ -43,7 +43,7 @@ Random vault-key wrapping, enrollment, cross-device rotation, hardware-backed st
 - CI confirms the declared OS/Node matrix; a local macOS run cannot establish Windows readiness.
 - Real Claude Code, Codex, and Cursor installations accept configuration and complete save/recall/restart.
 - Hosted migration and account-isolation tests pass.
-- The package owner configures npm's trusted publisher for `camgitt/memoir`, workflow `publish.yml`. The old publication auth failure is not fixed by this source branch.
+- The npm trusted publisher for `camgitt/memoir`, workflow `publish.yml`, was verified for releases 3.14.0 and 3.15.0. Subsequent publication must pass the full CI matrix and retain provenance.
 - Select and synchronize the release version across package.json, lockfile, and server.json. Publish only the reviewed commit/tag, then repeat the smoke check against the registry artifact.
 
 The release gates above also apply to future deployments. The linked validation report records what was actually observed for this release. No independent security certification is implied.
@@ -55,3 +55,8 @@ Local locks fail when busy. A crash while reaping can leave a `.reaper` file req
 Cloud merges retained states, increasing download cost. It cannot recover versions already removed by retention. Strong concurrent-cloud consistency needs a server-side conditional commit/merge protocol and race-tested retention.
 
 Legacy scope migration, renamed projects, unusual remote aliases, and profile isolation remain work. Concurrent hostile parent-directory replacement requires further filesystem review: current validation/no-follow opens are not an openat-based sandbox.
+
+## Project handoff recovery
+
+The project-only ledger now has automatic local snapshots and encrypted export/recovery.
+These are separate from legacy/cloud backup storage. See [the project recovery guide](PROJECT-RECOVERY.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memoir-cli",
-  "version": "3.14.0",
+  "version": "3.16.0",
   "mcpName": "io.github.camgitt/memoir",
   "description": "Portable, project-scoped memory and session handoffs for coding agents. Readable files, MCP recall, and optional user-passphrase encrypted backups.",
   "main": "src/index.js",

package/src/security/files.js

@@ -7,6 +7,18 @@ export const MAX_FILE_BYTES = 16 * 1024 * 1024;
 export const MAX_SNAPSHOT_BYTES = 256 * 1024 * 1024;
 export const MAX_SNAPSHOT_FILES = 50_000;
 
+// Windows can briefly report access denied while another process deletes a
+// file (notably the project lock). Retry the inspection, never skip it.
+export async function inspectFile(file) {
+  for (let attempt = 0; ; attempt++) {
+    try { return await fs.lstat(file); }
+    catch (error) {
+      if (process.platform !== 'win32' || !['EPERM', 'EACCES'].includes(error.code) || attempt >= 5) throw error;
+      await new Promise(resolve => setTimeout(resolve, 20));
+    }
+  }
+}
+
 // Validate both Windows and POSIX paths regardless of the restoring OS.
 export function relativeFile(value) {
   if (typeof value !== 'string' || !value || /[\x00-\x1f:]/.test(value) || path.posix.isAbsolute(value) || path.win32.isAbsolute(value)) throw new Error('Invalid relative memory path');
@@ -31,12 +43,12 @@ export async function safePath(root, relative, { createParents = false } = {}) {
   for (let i = 0; i < parts.length; i++) {
     current = path.join(current, parts[i]);
     let st;
-    try { st = await fs.lstat(current); }
+    try { st = await inspectFile(current); }
     catch (err) {
       if (err.code !== 'ENOENT') throw err;
       if (createParents && i < parts.length - 1) {
         await fs.mkdir(current, { mode: 0o700 }).catch(err => { if (err.code !== 'EEXIST') throw err; });
-        st = await fs.lstat(current);
+        st = await inspectFile(current);
       }
     }
     if (st?.isSymbolicLink()) throw new Error('Symlinks are not allowed in memory paths');

package/src/session/lock.js

@@ -1,6 +1,9 @@
 import fs from 'fs-extra';
 import path from 'path';
 import crypto from 'crypto';
+import { inspectFile } from '../security/files.js';
+
+const windowsBusy = error => process.platform === 'win32' && ['EPERM', 'EACCES'].includes(error.code);
 
 function alive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
@@ -19,12 +22,12 @@ export async function withSessionLock(lockPath, fn, { maxWaitMs = 5000, staleMs
       fs.writeSync(fd, String(process.pid));
     } catch (err) {
       if (fd !== undefined) { fs.closeSync(fd); await fs.remove(lockPath); throw err; }
-      if (err.code !== 'EEXIST') throw err;
+      if (err.code !== 'EEXIST' && !windowsBusy(err)) throw err;
       let reaper;
       const reaperPath = lockPath + '.reaper';
       try {
         reaper = await fs.open(reaperPath, 'wx', 0o600);
-        const st = await fs.lstat(lockPath);
+        const st = await inspectFile(lockPath);
         if (st.isSymbolicLink()) throw new Error('Session lock must not be a symlink');
         const owner = Number((await fs.readFile(lockPath, 'utf8')).trim());
         if (Date.now() - st.mtimeMs > staleMs && !alive(owner)) {
@@ -32,7 +35,7 @@ export async function withSessionLock(lockPath, fn, { maxWaitMs = 5000, staleMs
           await fs.rename(lockPath, abandoned);
           await fs.remove(abandoned);
         }
-      } catch (err) { if (!['ENOENT', 'EEXIST'].includes(err.code)) throw err; }
+      } catch (err) { if (!['ENOENT', 'EEXIST'].includes(err.code) && !windowsBusy(err)) throw err; }
       finally {
         if (reaper !== undefined) {
           await fs.close(reaper);
@@ -49,9 +52,18 @@ export async function withSessionLock(lockPath, fn, { maxWaitMs = 5000, staleMs
   }
   try { return await fn(); }
   finally {
-    let ours = false;
-    try { const a = fs.fstatSync(fd), b = fs.lstatSync(lockPath); ours = a.ino === b.ino && a.dev === b.dev; } catch {}
+    let ours = false, owned;
+    try { owned = fs.fstatSync(fd); const current = await inspectFile(lockPath); ours = owned.ino === current.ino && owned.dev === current.dev; } catch {}
     fs.closeSync(fd);
-    if (ours) await fs.unlink(lockPath).catch(() => {});
+    if (ours) for (let attempt = 0; ; attempt++) {
+      try {
+        if (attempt) { const current = await inspectFile(lockPath); if (owned.ino !== current.ino || owned.dev !== current.dev) break; }
+        await fs.unlink(lockPath); break;
+      }
+      catch (error) {
+        if (!windowsBusy(error) || attempt >= 5) break;
+        await new Promise(resolve => setTimeout(resolve, 20));
+      }
+    }
   }
 }

package/src/work/cli.js

@@ -1,8 +1,20 @@
 import { Command } from 'commander';
 import { recordWork, runWorkCheck, retractWork, refreshWork, formatWork } from './store.js';
 import { setupWork } from './setup.js';
+import { backupWork, doctorWork, recoverWork } from './recovery.js';
 import { readSafeFile } from '../security/files.js';
 
+async function recoveryPassphrase(confirm = false) {
+  if (process.env.MEMOIR_WORK_PASSPHRASE) return process.env.MEMOIR_WORK_PASSPHRASE;
+  if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error('Set MEMOIR_WORK_PASSPHRASE through your secret manager, or run this command in an interactive terminal. Never put the passphrase in a command argument or project record.');
+  const { default: inquirer } = await import('inquirer');
+  const questions = [{ type: 'password', name: 'passphrase', message: 'Recovery passphrase (at least 12 characters):', mask: '*' }];
+  if (confirm) questions.push({ type: 'password', name: 'confirmation', message: 'Repeat recovery passphrase:', mask: '*' });
+  const answer = await inquirer.prompt(questions);
+  if (confirm && answer.confirmation !== answer.passphrase) throw new Error('Passphrases did not match. Nothing was exported.');
+  return answer.passphrase;
+}
+
 export async function workCli(argv) {
   const program = new Command('memoir work').description('Local project continuity for Codex and Cursor')
     .option('--project <path>', 'Project directory', process.env.MEMOIR_PROJECT_ROOT || process.cwd());
@@ -14,6 +26,25 @@ export async function workCli(argv) {
     const view = await refreshWork(project());
     console.log(options.json ? JSON.stringify(view, null, 2) : formatWork(view));
   });
+  program.command('doctor').description('Check the project handoff and recovery snapshots').action(async () => {
+    const result = await doctorWork(project());
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.healthy && result.state !== 'empty') process.exitCode = 1;
+  });
+  program.command('backup').description('Save a local snapshot, or export an encrypted project handoff')
+    .option('--output <path>', 'New encrypted backup file; never overwrites an existing file').action(async options => {
+      const passphrase = options.output ? await recoveryPassphrase(true) : undefined;
+      console.log(JSON.stringify(await backupWork(project(), { output: options.output, passphrase }), null, 2));
+    });
+  program.command('recover [snapshot]').description('Preview recovery first; apply only the reviewed fingerprint')
+    .option('--from <path>', 'Encrypted project handoff export')
+    .option('--apply', 'Apply the reviewed recovery and preserve the original')
+    .option('--expect <fingerprint>', 'Fingerprint returned by the recovery preview').action(async (snapshot, options) => {
+      const passphrase = options.from ? await recoveryPassphrase() : undefined;
+      const result = await recoverWork(project(), { ...options, snapshot, passphrase });
+      if (result.applied) await refreshWork(project());
+      console.log(JSON.stringify(result, null, 2));
+    });
   program.command('view').description('Review and correct project memory in a local browser')
     .option('--no-open', 'Print the local link without opening a browser').option('--port <number>', 'Local port; 0 chooses an available port', '0').action(async options => {
       const { startWorkView } = await import('./view.js');
@@ -54,8 +85,8 @@ export async function workCli(argv) {
       console.log(JSON.stringify(result, null, 2));
       if (result.exit_code !== 0 || result.timed_out || !result.inputs_stable) process.exitCode = 1;
     });
-  program.command('retract <id>').requiredOption('--revision <number>', 'Current record revision').option('--category <name>', 'record or check', 'record').action(async (id, options) => {
-    const result = await retractWork(project(), { id, expected_revision: Number(options.revision), category: options.category });
+  program.command('retract <id>').requiredOption('--revision <number>', 'Current record revision').option('--category <name>', 'record or check', 'record').option('--recovery <id>', 'Recovery generation returned by resume').action(async (id, options) => {
+    const result = await retractWork(project(), { id, expected_revision: Number(options.revision), category: options.category, expected_recovery: options.recovery });
     await refreshWork(project());
     console.log(JSON.stringify(result));
   });