memoir-cli 3.12.0 → 3.15.0

package/docs/HANDOFF-SECURITY-AUDIT.md

@@ -0,0 +1,106 @@
+# Project handoff adversarial audit — 2026-09-06
+
+**Status: local preview, not a public deployment or a security-certified product.**
+The original functional tests were not a dedicated adversarial audit. This
+follow-up exercised the new project handoff, its MCP interface, CLI, settings
+writer, ledger parser and Git metadata helper using synthetic attack fixtures.
+It found real gaps and changed the implementation. All changes remain local.
+
+## Findings and fixes
+
+| Finding | Impact | Fix |
+|---|---|---|
+| MCP check tool accepted arbitrary host commands | A memory-tool call could read server environment values and write outside the project using server privileges | Disabled command execution over MCP completely. Existing tool name returns a refusal. Checks use the CLI under the coding client's ordinary terminal permissions |
+| Reading Git status executed a configured fsmonitor hook | A resume operation could execute repository-controlled code | Removed dirty-status execution from the shared repository metadata helper. Dirty status is now unknown; per-file freshness still works |
+| JSON serialization hid some secrets from the scanner | Field-leading environment assignments and embedded JSON credentials could be saved | Scan decoded strings, normalize common invisible obfuscation for detection, and reject recognized credentials before storage |
+| Rendered record data could create Markdown structure and image links | A stored answer could imitate a new evidence section or contain active image markup | Escape rendered fields and keep them on one line; explicitly label all stored text untrusted |
+| A file named `__proto__` disappeared from input evidence | Changes to a declared file could fail to invalidate a check | Use dictionaries without an object prototype and validate original input maps without schema normalization dropping that key |
+| Maximum-size check input lists broke subsequent reads | 100 explicit inputs plus automatic manifests created a ledger the old reader rejected | Validate the combined maximum consistently |
+| Incomplete receipt/history validation | Incorrectly typed evidence, reordered history and malformed retractions could be accepted | Strict receipt, metadata, revision-order and history-completeness validation; preserve and refuse malformed data |
+| Non-object Cursor settings could be rewritten | Setup could replace an unexpected existing configuration shape | Reject before any planned settings/instruction edits are applied |
+| Unbounded CLI stdin | Oversized input was buffered and parsed | Enforce a 16 KiB limit while reading and before parsing |
+
+Additional hardening sanitizes parser and filesystem errors so damaged-file
+contents are not returned to an MCP client. Unsafe controls and direction
+overrides are rejected after decoding. The memory interface remains local stdio.
+The later project-view feature adds an opt-in HTTP listener bound only to
+127.0.0.1, with a per-process capability, strict Host/Origin validation and no
+command execution. It adds no telemetry, cloud upload or background daemon.
+See [the project-view validation](PROJECT-VIEW-VALIDATION.md) for its separate
+browser and request-security checks. The counts below describe the earlier audit.
+
+## Adversarial evidence
+
+`test-work-adversarial.mjs` contains **19 scenarios**. The first baseline had
+14 failed assertions. Further probing then reproduced execution of a synthetic
+Git fsmonitor hook and caught a normalization issue in the first prototype-key
+fix. These are regression probes, not 14 independent vulnerability ratings.
+No real credentials, personal home files or external attack targets were used.
+
+The final suite passes all 19 assertions. Eighteen scenarios verify defenses;
+one deliberately demonstrates the remaining valid-receipt-tampering boundary
+and verifies that it is explicitly disclosed. A passing test count must not be
+interpreted as proof that every attack is blocked.
+
+Covered attacks include host command/environment access through MCP, Git-hook
+execution during resume, damaged-file error leakage, multiple secret formats,
+invisible and directional text, Markdown spoofing, special dictionary keys,
+input limits, malformed and reordered history, configuration clobbering,
+oversized stdin, symlink escape, shell metacharacters and personal-scope requests.
+
+Run the dedicated suite with:
+
+```sh
+node test-work-adversarial.mjs
+```
+
+`npm test` includes it alongside the existing functional suites. The dependency
+audit against the npm advisory data reported **zero known vulnerabilities** in
+the production dependency tree at the time of this audit. That result does not
+cover application logic or prove the absence of undisclosed dependency bugs.
+
+After the final fixes, **22 full test suites passed** and the installed-package
+smoke test passed. The new 19-scenario adversarial suite and the existing
+17-group handoff suite are included in that result.
+
+The live Cursor app connection was reloaded and tested in the existing
+“Memoir project continuation” conversation. A harmless `memoir_work_check`
+request returned the explicit MCP-execution refusal. A subsequent
+`memoir_work_resume` still returned both saved answers and the unauthenticated
+receipt warning. No fallback command was run for this denial probe. This verifies
+the active client received the hardened server, not only an isolated test copy.
+
+## What this does not secure
+
+- **Valid local receipt forgery remains possible.** A process with ledger write
+  access can change a failed exit code to zero and construct valid-looking
+  metadata. The suite demonstrates this. Receipts are local, unauthenticated
+  observations, not signed attestation or release authorization.
+- **Semantic prompt injection is not solved.** Escaping blocks structural
+  spoofing and active Markdown, but an AI can still mishandle hostile text.
+  Stored claims and source labels never grant authority.
+- **The CLI is not an independent sandbox.** It executes the authorized command
+  with the terminal client's permissions and environment. Declared input hashes
+  are evidence scope, not restrictions on what that process can read or write.
+- **Same-user hostile filesystem races are outside the boundary.** Stable
+  symlinks and traversal are rejected, but this is not OS-level isolation from
+  a process that can concurrently alter the project, server installation or
+  ancestor directories. A stronger boundary needs OS-enforced isolation and
+  separately protected evidence signing.
+- **Privacy detection is heuristic.** Arbitrary personal sentences and every
+  encoded credential cannot be identified automatically. Local files/backups
+  are plaintext, and connected AI clients receive the project context they use.
+- **Scope is the new handoff.** This is a focused source and local adversarial
+  audit, not an independent penetration test of all legacy Memoir commands,
+  hosted APIs, cloud authorization or cross-tenant isolation. Those were not
+  exercised against a live service here.
+
+## Local audit trail
+
+Baseline and rerun logs are beside this checkout:
+`../memoir-adversarial-before.log`,
+`../memoir-adversarial-additional-before.log`,
+`../memoir-adversarial-after.log`, and
+`../memoir-security-full-tests.log`. The dependency result is
+`../memoir-handoff-npm-audit.json`. Current execution receipts and the saved audit
+decision are in the ignored `.memoir/work.json`; none of these logs were published.

package/docs/LOCAL-HANDOFF-VALIDATION.md

@@ -0,0 +1,129 @@
+# Local handoff validation — 2026-09-06
+
+The Codex → Cursor → Codex workflow completed in this Memoir checkout on this
+Mac. Both continuations used the saved answers and reused the saved integration
+check. This exercise was performed before publication; the counts below describe that local candidate.
+
+This report records the original functional exercise. A subsequent
+[adversarial audit](HANDOFF-SECURITY-AUDIT.md) found and fixed security gaps.
+In the hardened version, check execution is available through the CLI under
+normal terminal permissions; the MCP check tool deliberately refuses commands.
+Memory reads also omit Git dirty-status checks to avoid executing repository
+hooks. Later receipts supersede the original receipts described below.
+
+For everyday use, open the **same folder and branch** in either tool and say
+**“Continue this project.”** Run one-time setup in the project you want to continue. See
+[the usage guide](PROJECT-HANDOFF.md) for the full reference.
+
+## What was tested in actual clients
+
+| Step | Observed result | Evidence |
+|---|---|---|
+| Codex, first session | Saved the goal, two user answers, an output-privacy decision, a real integration receipt and Cursor's next task | Ledger revisions 1–6; local Codex event log |
+| Cursor desktop, local environment | Resumed without receiving the task description again, wrote the requested guide, marked its task done and left a review for Codex | Cursor conversation “Memoir project continuation”; ledger revisions 7–8; guide file |
+| Codex, fresh return session | Found Cursor's completed task, reviewed and corrected the guide, preserved answers and marked the review done | Ledger revision 13; local Codex return event log/result |
+| Cursor MCP connection | Initially disabled; enabling only this project's Memoir source connected four tools. A follow-up direct `memoir_work_resume` call returned both answers and the matching check | Cursor Customize → MCPs and the conversation's tool result |
+
+Codex ran using the app-bundled **CLI 0.153.4**, with the existing configured
+model, in two fresh sessions. Cursor was the installed **desktop app 3.17.19**,
+using **This Mac**, this checkout and `fix/audit-reliability`. This was not a
+separate fresh Codex desktop-chat test. The older standalone Codex CLI 0.146.0
+could not run the configured model; it was left unchanged.
+
+Codex loaded the project MCP configuration, but its test sessions' `never`
+approval policy refused MCP calls. Both sessions successfully used the generated
+CLI fallback. No approval policy or model setting was relaxed. Cursor's initial
+work also used the fallback before its new project connection was enabled.
+Successful server setup alone is not treated as proof of client acceptance.
+
+## Did it reduce repeated work?
+
+- Both continuations reused the original delivery and privacy answers; their
+  record revisions remained 2 and 3. No repeated answered question was observed.
+- The integration check was executed **once during the three-leg round trip**.
+  Cursor and returning Codex both reused its revision-5 receipt because its
+  declared files and runtime still matched.
+- Cursor obtained its task from the handoff, and Codex obtained the review from
+  Cursor's update. Neither continuation prompt copied those task descriptions
+  or the earlier conversation.
+- Returning Codex added a separate documentation check. Its first attempt
+  mishandled Git's no-index exit status; the corrected check passed. Memoir
+  retained the failed receipt and the later pass. This was additional work on
+  a new check, not a rerun of the saved integration check.
+
+This demonstrates continuity in one useful local exercise. It is not a timed
+comparison against working without Memoir, a guarantee of fewer questions in
+every task, or evidence that agents will always follow the instructions.
+
+## Changed conditions and rechecks
+
+After the round trip, the setup message was clarified and the integration
+fixture was strengthened to actually exercise paths containing spaces and
+quotes. A fresh resume correctly changed the integration result to
+`needs-recheck` and named:
+
+```text
+Changed input: src/work/setup.js
+Changed input: test-work-handoff.mjs
+```
+
+The documentation check also became stale because it included the setup source.
+The guide then gained the final usage and removal instructions. Targeted reruns
+passed: integration receipt **14**, documentation receipt **15**. Both now show
+matching declared inputs. The warning cleared because the checks ran against
+the new files; no completion flag was manually substituted for a check.
+
+Relevant file changes, missing files, changed local Node runtime, newly added
+dependency manifests, failed executions and changes during a run trigger
+specific recheck reasons. Unrelated documentation edits do not invalidate the
+integration result. External observations always need current verification:
+for example, a prior Stripe dashboard check does not prove today's settings.
+Only the declared inputs are covered, so agents must include all relevant files.
+
+## Implementation and verification
+
+- Separate project ledger and MCP server; no global personal-memory or transcript
+  import. Records include source, rationale, branch, revisions and next-action
+  completion. Corrections reject stale revisions; retractions retain history.
+- Checks execute an argument array and retain exit status, timestamps, input
+  fingerprints and an output digest. Raw terminal output is discarded.
+- Setup preserves unrelated project settings and backs up changed existing
+  files. Existing conflicting Memoir connections are preserved with a warning.
+  No unrelated global configuration was edited. Only the new project source
+  was enabled in Cursor's UI.
+- **21 test suites passed**, including the project handoff suite. The final
+  focused run passed **17 groups**, including privacy canaries, actual process
+  execution, stale-input detection, concurrency, settings preservation, real
+  MCP restarts and fallback paths containing spaces and quotes.
+- The **installed-package smoke test passed** with the new project CLI, setup,
+  check receipt and MCP resume, alongside the existing backup/restore tests.
+- The guide's examples, command help and whitespace were checked; its semantic
+  content was also reviewed against the implementation. A passing syntax check
+  alone does not establish that a guide is correct.
+
+## What remains manual or limited
+
+- Choose the same local checkout and branch, then ask the next agent to continue.
+  The ledger is ignored by Git: GitHub pushes, another worktree or another
+  computer do not carry it. The older Memoir backup commands do not sync this
+  new ledger.
+- A client can require project trust or MCP approval. Cursor's connection is
+  enabled here; Codex can use the fallback under its existing policy.
+- Agents must save important decisions and use Memoir's check command/tool.
+  Ordinary shell checks and unsaved conversation are not captured by a hook.
+- Personal-scope records and recognized secrets are rejected, and raw output is
+  not retained. Detection is heuristic. Project files and backups are plaintext
+  locally; connected AI clients receive the project context used for the task.
+  This is not an isolation barrier against a process with filesystem access.
+- External app settings can change independently. Evidence is scoped and
+  attributable, but local receipts and source labels are not cryptographic
+  authentication against a process allowed to edit the ledger.
+
+## Local evidence locations
+
+The ignored `.memoir/` directory contains `work.json`, the refreshed
+`HANDOFF.md`, both Codex event logs and results, `after-input-change.json`, and
+the final integration/documentation receipts. Exact setup backups are under
+`.memoir/setup-backups/`. Full-suite and package-test logs are beside this
+checkout in `../memoir-handoff-full-tests.log` and
+`../memoir-handoff-packed-test.log`. These local logs are not published.

package/docs/MCP-V2-MIGRATION.md

@@ -0,0 +1,17 @@
+# MCP SDK v2 compatibility assessment
+
+Checked 5 September 2026. Memoir currently declares `@modelcontextprotocol/sdk ^1.29.0` and Node `>=18`.
+
+The [official SDK repository](https://github.com/modelcontextprotocol/typescript-sdk) documents v2 as stable for the 2026-07-28 protocol specification, with separate server/client packages and Standard Schema support. The npm manifests for [server 2.0.0](https://registry.npmjs.org/@modelcontextprotocol/server/2.0.0) and [client 2.0.0](https://registry.npmjs.org/@modelcontextprotocol/client/2.0.0) both declare Node `>=20`. The upstream README promises v1 bug/security fixes for at least six months after v2 release. This is a planned compatibility migration, not evidence that Memoir's current SDK is vulnerable.
+
+A direct dependency replacement would break Memoir's advertised Node 18 support. The retrieval changes therefore retain v1 and do not quietly raise the minimum runtime.
+
+Before migrating:
+
+1. Choose and announce an actively supported Node LTS baseline; the SDK's minimum is not necessarily the appropriate product minimum. Update package metadata, installation docs, and CI together.
+2. Inventory imports in `src/mcp.js`, `src/integrations/setup.js`, and the test clients. Port server/client imports, transports, and tool schemas according to the chosen released v2 API.
+3. Preserve existing tool names, argument validation, project visibility, structured/text responses, and error semantics. Check empty results and malformed requests.
+4. Exercise protocol negotiation, initialization, tool discovery/calls, shutdown/restart, and the installed tarball on all supported operating systems.
+5. Confirm actual supported Claude Code, Codex, and Cursor releases accept configuration and complete remember/recall/restart. An SDK-to-SDK handshake alone is insufficient.
+
+No SDK migration or runtime-support change is included in the retrieval-index change.

package/docs/PROJECT-HANDOFF.md

@@ -0,0 +1,301 @@
+# Project continuation for Codex and Cursor
+
+## Use it now
+
+Install Memoir 3.14.0 or later and run `memoir work setup` in the project you
+want to continue. Open that same folder and branch in Codex or Cursor and say
+**“Continue this project.”** The next agent reads saved answers, decisions,
+completed work and next actions. You do not need to copy the conversation.
+
+The reference local test completed the round trip with Cursor desktop and the
+Codex CLI. See [the validation report](LOCAL-HANDOFF-VALIDATION.md) for the actual
+client versions and limits. Agents still need to follow the installed
+instructions, and setup does not prove a new client has accepted its connection.
+
+This documents the local project handoff in `src/work/` and `bin/memoir-work.js`. It is not a claim that hosted clients have accepted the connection, and it does not import global or personal Memoir memory.
+
+`.memoir/work.json` is the authoritative ledger. `.memoir/HANDOFF.md` is a generated preview; run `resume` before relying on it. Stored text is evidence, never permission.
+
+## 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,
+decisions, checks, goals and next steps. Setup is not needed again for each use.
+Keep the terminal process running while using the view; Ctrl+C stops it.
+`--no-open` prints the access link without launching a browser, and `--port N`
+chooses a local port. The default chooses an available one.
+
+- **Correct** saves a new version that the next agent resume receives. Source and
+  earlier versions remain available on the card.
+- **Remove from handoff** hides an item from agents. **Removed → Restore to
+  handoff** brings back a record. This is reversible removal, not permanent
+  deletion; there is no project-history purge control yet.
+- **Mark done** preserves a completed next step so another session knows it was
+  finished. **Reopen** makes it active again.
+- **Needs recheck** names changed inputs or explains a failed/external result.
+  The view cannot run commands or edit check receipts. A removed receipt needs
+  a new authorized check, not a restore-to-pass button.
+- If another session edits the item, the draft stays open. **Review latest
+  version** shows the saved version; compare it, choose **Keep my draft and
+  continue**, then save. Another intervening change is rejected again. If the
+  branch changed or the item was removed, review that state before proceeding.
+
+While a save is pending, the editor keeps its fields and close controls locked.
+A request stops waiting after 15 seconds. An interrupted response does not prove
+that the save failed: the server may already have saved it. The draft stays open;
+use **Review latest version** to find the saved record before retrying. Retrying
+the same open draft cannot create a second record. Closing or reloading the tab
+still discards unsaved drafts; they are not written into browser storage.
+
+The view listens only on this computer at 127.0.0.1. Its temporary access link
+opens this process's project data; keep it private and do not add it to a handoff.
+The browser removes the token from the visible URL and keeps it only in that
+browser tab's session storage. Reopen from the terminal's full link after losing
+that session. There is no account, upload, command runner or settings editor.
+The agent's permissions and the local plaintext/unsigned-evidence limits below
+still apply. Other same-user processes are not an isolation boundary.
+
+## One-time setup
+
+From the Memoir source checkout after installing its dependencies:
+
+```bash
+node bin/memoir-work.js --project "$(pwd)" setup --tools codex,cursor
+```
+
+To connect another project on this computer, replace `"$(pwd)"` with that
+project's absolute folder path. Keep the Memoir installation in place: the
+generated connection and fallback refer to it. For this tested Cursor version,
+open **Customize → MCPs → memoir-work** and enable the project source if it shows
+Disabled. Existing unrelated connections remain unchanged.
+
+`--tools` accepts `codex`, `cursor`, or both (default: both). Setup verifies a live MCP handshake: the server must expose `memoir_work_resume`, `memoir_work_record`, `memoir_work_check`, and `memoir_work_retract`.
+
+If the handshake succeeds, setup writes only the files that actually change:
+
+| File | Role |
+|---|---|
+| `AGENTS.md` | Managed instruction block (`<!-- memoir:project-work -->` … `<!-- /memoir:project-work -->`), for either tool selection |
+| `.cursor/rules/memoir-work.mdc` | With `cursor`: same instructions; a new file gets `alwaysApply: true`, existing frontmatter is preserved |
+| `.cursor/mcp.json` | With `cursor`: `mcpServers.memoir-work` stdio entry |
+| `.codex/config.toml` | With `codex`: `mcp_servers.memoir-work` stdio entry |
+| `.gitignore` | Keeps `/.memoir/`, `/.codex/config.toml`, `/.cursor/mcp.json`, and `/.cursor/rules/memoir-work.mdc` out of ordinary commits |
+
+The MCP entry runs `src/work/server.js` with `MEMOIR_PROJECT_ROOT` set to the project directory and `DO_NOT_TRACK=1`. Previous contents of changed, non-empty text files are copied under `.memoir/setup-backups/<uuid>/` before edits are written. Empty or newly created files have no backup entry. Setup is not a transaction across all files; an interrupted write can leave partial edits.
+
+A second setup with unchanged generated content leaves the listed files alone, but still verifies the server and refreshes `.memoir/HANDOFF.md`. The `.gitignore` additions apply for either tool selection.
+
+Text outside the managed instruction block and existing TOML comments are preserved. Cursor configuration must be valid JSON: comments are unsupported, and adding a connection rewrites JSON formatting while preserving unrelated settings and servers. An existing `memoir-work` entry is left unchanged; a different command, args, or project root produces a CLI-fallback warning. Other differences, such as `DO_NOT_TRACK`, are not reconciled. Parsing errors, detected malformed instruction markers, or an explicitly invalid MCP server map or Memoir connection (including null, false, zero, empty strings and arrays) abort before the planned edits are written. This is not comprehensive client-configuration validation.
+
+After setup, open the project in Cursor or Codex, accept the normal project/MCP trust prompt if shown, and start with “Continue this project.” Setup alone does not verify client acceptance; see the recorded observation below for this project's tested routes.
+
+## Daily Codex / Cursor workflow
+
+1. **Resume first.** Call `memoir_work_resume` (or `node bin/memoir-work.js --project "$(pwd)" resume`). Reuse recorded answers and applicable checks marked **PASSED; declared inputs still match**. Matching file hashes alone do not make a failed or external check current.
+2. **Do the recorded next action within the user's current scope.** Mark a next action `done` only after completing it. Pass that record's revision as `expected_revision` from the current resume, not the overall handoff revision.
+3. **Record as you go.** Save explicit project decisions, resolved questions, and the next action with `memoir_work_record`. Identify the source. Do not save personal preferences, credentials, raw transcripts, or guesses as answers.
+4. **Capture checks through Memoir's CLI.** Run `memoir work check` through the client's normal terminal permissions and sandbox. The MCP check tool deliberately refuses execution. An ordinary shell pass outside the wrapper is not recorded evidence.
+5. **Update the action at the stopping point.** Save its completion or remaining authorized work and relevant decisions. If the action is complete, no additional task needs to be invented. Updates are written immediately; no separate handoff request is needed.
+
+MCP tools (stdio server, project-bound):
+
+| Tool | Purpose |
+|---|---|
+| `memoir_work_resume` | Current branch: answers, decisions, next actions, and checks with freshness |
+| `memoir_work_record` | Save a project-only `goal`, `answer`, `decision`, or `next` |
+| `memoir_work_check` | Refuse host command execution and direct existing clients to the CLI check command |
+| `memoir_work_retract` | Hide a mistaken record from the current view; history stays local |
+
+CLI fallback (`memoir work` delegates to the same entry):
+
+Use the direct `bin/memoir-work.js` entry for the project-only workflow. Generated project instructions contain absolute, quoted paths to Node, this entry, and the project root; use those if `node` is unavailable on the client PATH. A configured MCP tool can also be unavailable because its call requires approval under a policy that forbids approval. Use the authorized CLI fallback in that case; do not change approval policies or app settings as part of continuation.
+
+```bash
+node bin/memoir-work.js --project "$(pwd)" resume
+node bin/memoir-work.js --project "$(pwd)" resume --json
+node bin/memoir-work.js --project "$(pwd)" record --file .memoir/record-input.json
+node bin/memoir-work.js --project "$(pwd)" check CHECK_ID --title 'What this proves' --files SOURCE_FILE TEST_FILE -- node TEST_FILE
+node bin/memoir-work.js --project "$(pwd)" retract RECORD_ID --revision N --category record
+```
+
+`--file -` reads record JSON from stdin. For `record`, provide exactly one of `--json` or `--file`; a record file must be project-relative and at most 16 KiB. Record fields: `id`, `kind` (`goal` \| `answer` \| `decision` \| `next`), `text`, `source`; optional `answer`, `why`, `status`, `expected_revision`, `scope`. `scope` defaults to `project` and accepts no other value.
+
+## Correction
+
+Resume first. Corrections require the target record's current revision as `expected_revision`. History is appended; the latest matching branch record is what resume shows unless retracted. The numbers and IDs below are illustrative: use an existing record's actual ID and revision, and only describe a user correction when one was actually given.
+
+Create `.memoir/record-input.json` (gitignored under `/.memoir/`):
+
+```json
+{
+  "id": "answer.provider",
+  "kind": "answer",
+  "text": "Payment provider?",
+  "answer": "CorrectedPay",
+  "source": "User correction after resume",
+  "expected_revision": 3
+}
+```
+
+```bash
+node bin/memoir-work.js --project "$(pwd)" record --file .memoir/record-input.json
+```
+
+Rules from the current implementation:
+
+- Omitting `expected_revision` on an existing ID fails.
+- A new ID may omit `expected_revision` or pass `0`. A non-zero revision on a missing ID fails.
+- A correction cannot change `kind`; use another ID.
+- Only `next` records may use `status: "done"`. An `answer` requires `answer`.
+- IDs match `^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$`. Text fields are 1–2000 characters after trim.
+
+MCP equivalent: `memoir_work_record` with the same object under `record`.
+
+## Retraction
+
+Retraction removes the record from the current resume view. The ledger keeps the history, and the same ID can be recorded again.
+
+```bash
+node bin/memoir-work.js --project "$(pwd)" resume
+node bin/memoir-work.js --project "$(pwd)" retract next.test --revision 12 --category record
+```
+
+Then record a replacement, passing that same record revision as `expected_revision` (12 in this example), not the newer revision of the retraction or overall handoff. Resume again before the correction; the retracted record is hidden, so retain its original revision or consult its latest entry in `.memoir/work.json`.
+
+```json
+{
+  "id": "next.test",
+  "kind": "next",
+  "text": "Add test",
+  "source": "Correction after retract",
+  "status": "open",
+  "expected_revision": 12
+}
+```
+
+`--category check` retracts a saved check the same way. Resume before retracting; a stale revision is rejected. MCP: `memoir_work_retract` with `id`, `expected_revision`, and optional `category` (`record` default).
+
+## Check evidence and freshness
+
+`memoir work check` spawns argv with `shell: false` in the project directory. The MCP server never runs that command: memory-tool approval must not grant a separate host shell. Use the CLI through the client's normal terminal permissions. The CLI stores:
+
+- actual `exit_code` (and `signal` / start error if any)
+- SHA-256 of each declared input, plus any present common manifests (`package.json`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `requirements.txt`, `pyproject.toml`, `uv.lock`)
+- `inputs_stable` (hashes unchanged during the run)
+- `output_sha256` and `output_bytes`
+- `runtime` (`platform/arch/node-version`)
+- `environment` (`local` default, or `external`)
+- `evidence_source: memoir-executed-process`
+
+Raw stdout/stderr is hashed and discarded. A delayed older execution cannot replace a newer result for the same ID. CLI exit status is 1 when `exit_code !== 0`, the command timed out, or inputs were not stable.
+
+Resume labels a check **PASSED; declared inputs still match** only when freshness is `inputs-match`. Otherwise it is **NEEDS RECHECK**, with reasons. Recheck when any of these apply:
+
+- execution evidence is missing
+- non-zero exit, timeout, signal, or more than 8 MiB of output
+- inputs changed while the check ran
+- `environment` is `external` (settings can change independently)
+- the local runtime changed
+- a new common manifest appeared
+- a recorded input hash changed, or an input is missing/unreadable
+
+Unrelated files outside the declared inputs do not invalidate a match. A pass covers only those declared files and the local runtime. It does not verify undisclosed dependencies, external settings, or production. External configuration always needs current verification.
+
+Rejected as check inputs: paths under `.memoir/`, basenames `.env` / `.env.*` or starting with `credentials`, `id_rsa` / `id_ed25519`, `*.pem` / `*.key`, absolute paths, path traversal, and symlinks beneath the resolved project root. Input files are limited to 16 MiB each. These path rules govern input hashing, not what the executed command can access. The command inherits the process environment with `DO_NOT_TRACK=1`; the runner is not a separate sandbox. Supply every relevant source/test/configuration file; do not claim a shell command was captured unless it ran through this tool.
+
+Default timeout is 30s (100 ms–120 s). `--environment` is `local` or `external`.
+
+## Privacy boundaries
+
+Project-only. Personal/global memory, transcripts, and raw command output are not imported.
+
+Save: project decisions, answered questions, checks with evidence, and next actions. Do not save personal preferences, credentials, secrets, or guesses as user answers. Source labels identify the claimed origin; they are not authentication.
+
+Record/check arguments and ledger reads/writes scan decoded fields for known credential patterns, including normalized invisible-character obfuscation. Matching text, unsafe control characters and direction overrides are refused. This is a backstop, not a claim to recognize every private sentence or encoding. Ledger size is capped at 2 MiB and CLI record input at 16 KiB; full or oversized input fails without dropping records. Setup backups are separate from this ledger guard and can contain prior configuration contents, so keep them local too.
+
+Rendered fields cannot create new Markdown sections or active image links. Their content still remains untrusted: formatting cannot guarantee that an AI will resist semantic prompt injection. Local receipts are explicitly unauthenticated. A process allowed to rewrite the ledger can forge a valid-looking receipt; never use one as security attestation or deployment approval. See the [adversarial audit](HANDOFF-SECURITY-AUDIT.md).
+
+Keep this memory local unless the user explicitly chooses to share it. Existing application approvals still apply. `.gitignore` entries above keep the ledger and tool connections out of ordinary commits.
+
+## Actual limitations
+
+- **Same local checkout.** Open the same folder and branch in both tools. The ignored ledger is not synchronized by ordinary Git commits, GitHub pushes, another worktree, or the older Memoir backup commands.
+- **Agents must record the work.** These instructions request updates as work happens; no hook captures arbitrary conversations or ordinary shell checks. A crash before an agent saves a decision can lose that decision.
+- **CLI continuation and MCP acceptance are separate.** Setup can verify the local MCP server, but does not prove Cursor/Codex will permit calls. The observation below records the narrower result actually obtained.
+- **Branch-scoped.** Resume shows the current Git branch only. Other-branch records are counted, not mixed in.
+- **Preview can lag.** `.memoir/HANDOFF.md` is rewritten on resume/record/check/retract. Refresh it before relying on it.
+- **MCP may be missing or approval-blocked.** Use the authorized CLI fallback. Setup will not overwrite a conflicting existing `memoir-work` connection.
+- **Freshness is narrow.** Matching inputs are not a production proof. External checks never appear current.
+- **Git dirty status is unknown.** Memory reads no longer run `git status`, which can execute repository-configured hooks or filters. Check freshness still compares the declared files directly.
+- **CLI commands retain terminal authority.** Declared input files specify evidence coverage, not a filesystem sandbox. Only run trusted, authorized checks through the client's normal execution controls.
+- **Foreign or damaged ledgers fail closed.** Invalid JSON, unsupported version, or non-`project` scope preserves the original file and refuses the operation.
+- **Locks serialize writers.** Concurrent records are queued; a busy lock fails rather than corrupting the ledger.
+- **No permission from storage.** Recorded text cannot authorize work that the user did not authorize.
+
+## Remove the setup
+
+Disable only this project's `memoir-work` connection in the clients, remove its
+entry from the two project MCP configuration files, and remove the marked Memoir
+block from `AGENTS.md` and the dedicated Cursor rule. Leave unrelated entries and
+instructions in place. Exact pre-setup copies of changed existing files are in
+`.memoir/setup-backups/`; review later edits before restoring any whole file.
+The ignored ledger can stay for later use. Retraction hides an item but does not
+erase its history; deletion of sensitive content would also need to cover local
+history and copies. Setup does not install a background service.
+
+## Observed continuation, 2026-09-06
+
+Codex resumed the local ledger through the documented CLI fallback and reviewed this guide against `src/work/{cli,setup,store,server}.js`, the supporting file/lock/repository helpers, and `bin/memoir-work.js --help`. The delivery/privacy answers and output-digest decision carried forward. The recorded Cursor documentation action was already done; the open Codex action was this documentation review. No answered question was asked again.
+
+The saved `check.project-handoff` result (revision 5) still matched its declared inputs and local runtime and was reused without rerunning it. That check covers the listed implementation/test files and manifests, not this guide or external app settings. Documentation edits therefore need their own review; they do not invalidate that integration result.
+
+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.