synartesis 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -2,6 +2,69 @@
 
 What changed, and why it mattered. Dates are release dates.
 
+## 0.8.1 — 2026-09-19
+
+Documentation only. No code changed, and the published package behaves exactly
+as 0.8.0 did.
+
+### Changed
+
+- **The README is laid out as a page rather than a document.** Somebody
+  arriving from a link wants to know within one screen what this is, that it
+  works, and which of the four ways in is theirs. None of that was visible
+  without scrolling past four screens of prose. The top is now a centred hero,
+  a badge row and a contents bar, then **Choose your path** — four cards, one
+  per way in, each carrying the command that starts it — and a short list of
+  first results that take the least time.
+
+- **Two things came out of hiding, in the README and on the site.** The
+  interactive screen was a footnote inside Install despite being the interface
+  most people will use, and there was nothing anywhere about writing a policy
+  for a server that does not ship with one — which is the case for every server
+  but four, and the contribution most worth asking for. Both are now sections
+  of their own: `synartesis.online/install.html#write-a-policy` covers `init`
+  drafting fail-closed and `check` refusing a policy that names a tool the
+  server no longer has.
+
+- **A contributing section, and the star asked for out loud.** The README
+  explained the tool thoroughly and then stopped, with no issue link and
+  nothing a reader who agreed with it could do next.
+
+- `SECURITY.md` said the 0.6.x line was the supported one, two minors after it
+  stopped being.
+
+## 0.8.0 — 2026-09-16
+
+### Added
+
+- **`expect: absent`, and `move_file` becomes undoable.** A pre-read normally
+  captures what a call is about to replace, so a read that finds nothing means
+  there is nothing to put back. For a few calls that is exactly backwards:
+  moving a file onto a free path is undone by moving it back, and it is finding
+  *something* there that puts the call beyond undo, because one inverse cannot
+  both move your file back and restore what it landed on.
+
+  Both halves were measured before anything was written. Declared plainly
+  `reversible`, the safe move came back `partial` with the file still moved —
+  the trivially reversible case was the one that could not be undone — and the
+  dangerous one came back `rolled_back` with the overwritten file gone, which
+  is the confident wrong undo this exists to prevent. `expect: absent` on the
+  snapshot swaps the two: finding nothing is reversible and the inverse runs;
+  finding something is held for a person and recorded with **no inverse**, so
+  undo says it cannot be undone rather than putting half of it back.
+
+  The shipped filesystem policy uses it, so moving a file to a fresh path is
+  now an ordinary undoable action instead of an approval prompt. A policy that
+  declares it on a non-`reversible` rule, on a `verify` read, or with an
+  inverse reading `$snapshot.` — which can never resolve, since nothing is
+  captured — is refused at load.
+
+  Worth recording: this server's own description of `move_file` says "If the
+  destination exists, the operation will fail." It does not; it renames over
+  the top, because that is what `rename(2)` does. Taking the documentation at
+  its word would have made the rule unconditionally reversible and the
+  overwrite both unrecoverable and unremarked.
+
 ## 0.7.0 — 2026-09-16
 
 A pass over everything, after an audit of the desktop app, the core and the

package/README.md

@@ -1,27 +1,79 @@
 <!-- Absolute URLs, not relative paths: this README is also the npm package
      page, and npm does not resolve relative image paths against the repo. -->
+<div align="center">
+
 [![Synartesis — an undo layer for AI agents](https://raw.githubusercontent.com/ArhaanDev24/Synartesis/main/brand/synartesis-banner.png)](https://synartesis.online)
 
+**Give AI agents a way back.**
+Synartesis sits between your MCP client and the servers it talks to, records
+every tool call with the state that call replaced, and can put that state back.
+What cannot be put back, it refuses to let an agent do unsupervised.
+
+### [Install it, then read the five minutes ahead of you →](docs/synartesis-user-guide.md#the-five-minutes-ahead-of-you)
+
 [![check](https://github.com/ArhaanDev24/Synartesis/actions/workflows/check.yml/badge.svg)](https://github.com/ArhaanDev24/Synartesis/actions/workflows/check.yml)
 [![npm](https://img.shields.io/npm/v/synartesis?color=5e1420&label=npm)](https://www.npmjs.com/package/synartesis)
 [![downloads](https://img.shields.io/npm/dm/synartesis?color=5e1420&label=downloads)](https://www.npmjs.com/package/synartesis)
 [![node](https://img.shields.io/node/v/synartesis?color=5e1420)](https://nodejs.org)
 [![MIT](https://img.shields.io/badge/licence-MIT-5e1420.svg)](LICENSE)
+[![site](https://img.shields.io/badge/synartesis.online-5e1420)](https://synartesis.online)
+[![star this repo](https://img.shields.io/badge/★_star_this_repo-2c080f)](https://github.com/ArhaanDev24/Synartesis)
+
+[Choose your path](#choose-your-path) · [See it in action](#see-it-in-action) ·
+[Install](#install) · [The screen](#the-screen) ·
+[The desktop window](#the-desktop-window) ·
+[The four classes](#what-it-can-and-cannot-do) ·
+[Your own server](#writing-a-policy-for-your-own-server) ·
+[Commands](#commands) · [What it does not do](#what-it-does-not-do) ·
+[Trust](#trust) · [Contributing](#contributing)
+
+</div>
 
 An agent with write access to a real system runs twenty steps, misreads step
 seven, and applies the rest to the wrong records. Today your options are to
 reverse it by hand from the transcript, restore a backup and lose every
 legitimate change made in the same window, or accept the damage.
 
-Synartesis sits between your MCP client and the servers it talks to. It records
-every tool call with the state that call replaced, and it can put that state
-back. What cannot be put back, it refuses to let an agent do unsupervised.
-
 It is not a sandbox: the container your agent runs in is disposable, but the
 CRM row it updated over the network is not. It is not a tracing tool: a trace
 tells you `update_customer` ran forty times, not what the values were before.
 
-## What it looks like
+**If this is a problem you have, [a star](https://github.com/ArhaanDev24/Synartesis) helps other people find it.**
+It is a young project, and that is most of how anybody learns it exists.
+
+---
+
+## Choose your path
+
+<table>
+<tr>
+<td width="50%"><a href="#install"><img src="https://raw.githubusercontent.com/ArhaanDev24/Synartesis/main/brand/synartesis-card-install.png" alt="Cover what you already have — one command, every client. Finds what Claude Code, Claude Desktop, Cursor and Codex already list and points every entry at the proxy. $ synartesis install"></a></td>
+<td width="50%"><a href="#the-screen"><img src="https://raw.githubusercontent.com/ArhaanDev24/Synartesis/main/brand/synartesis-card-screen.png" alt="The screen — everything, on the arrow keys. What your agents have done, what is held for approval, and the undo for any of it. $ synartesis"></a></td>
+</tr>
+<tr>
+<td width="50%"><a href="#the-desktop-window"><img src="https://raw.githubusercontent.com/ArhaanDev24/Synartesis/main/brand/synartesis-card-desktop.png" alt="The desktop window — the same engine, with a conversation. Talk to any model. Every tool it calls goes out through the proxy on its way. $ synartesis desktop"></a></td>
+<td width="50%"><a href="#writing-a-policy-for-your-own-server"><img src="https://raw.githubusercontent.com/ArhaanDev24/Synartesis/main/brand/synartesis-card-policy.png" alt="Your own server — four ship with a policy, hundreds do not. Introspect a server, draft a manifest from it, then correct it where you know better. $ synartesis init crm -- ./crm-mcp"></a></td>
+</tr>
+</table>
+
+**Your first result**, in the order they take the least time:
+
+- **Undo a real write:** [run the filesystem demo](demo/filesystem-demo.sh) — it
+  makes a file, has an agent overwrite it, and puts it back, in about a minute
+  and without touching anything of yours.
+- **Cover the agents on this machine:** [`synartesis install`](#install), then
+  `synartesis status` to see what is now covered and what is not.
+- **Watch one happen:** [`synartesis watch`](#commands) prints each call as it
+  goes out, and lets you answer an approval where you are standing.
+- **Ask what an agent already did:** [`synartesis show <id> --live`](#has-anybody-touched-it-since)
+  reads every resource a session touched, as it is now, and says which still match.
+
+Nothing above sends anything anywhere. The journal is a SQLite file on your
+machine, and the proxy talks only to the servers your policy names.
+
+---
+
+## See it in action
 
 Both shots are real output from [`./demo/filesystem-demo.sh`](demo/filesystem-demo.sh),
 pasted rather than typeset. An agent overwrote a file and tried to move another.
@@ -41,6 +93,9 @@ It stops at the record that moved and exits non-zero. Anything already put back
 stays put back, and it prints the three ways on: leave it, restore the resource
 and `--replan`, or `--force` to overwrite deliberately.
 
+[The desktop window](#the-desktop-window) · [What it can and cannot do](#what-it-can-and-cannot-do) · [What it does not do](#what-it-does-not-do) · [User guide](docs/synartesis-user-guide.md)
+
+---
 ## Install
 
 ```bash
@@ -67,6 +122,12 @@ installed.**
 Needs Node 22 or newer. npm ships a prebuilt SQLite binding, so no toolchain is
 required unless you build from a clone.
 
+[User guide](docs/synartesis-user-guide.md#install-it) · [Claude Desktop](docs/synartesis-user-guide.md#claude-desktop) · [Claude Code](docs/synartesis-user-guide.md#claude-code) · [Any other client](docs/synartesis-user-guide.md#any-other-mcp-client)
+
+---
+
+## The screen
+
 Then just:
 
 ```bash
@@ -74,7 +135,17 @@ synartesis
 ```
 
 One screen: what agents have done, what is held for approval, every AI on the
-machine, and undo — all on the arrow keys.
+machine, and undo — all on the arrow keys. `enter` opens a session, `u` undoes
+it, `p` previews that undo without running it, `l` reads the world as it is now,
+`f` expands every argument, `c` lists every AI on the machine, `g` shows what is
+held. Nothing in it is a second implementation: it is the same journal and the
+same planner the [commands](#commands) below use, so a session undone in the
+screen and one undone in a script end the same way.
+
+There is no mode in it that acts without telling you what it is about to do. An
+undo shows you the plan first, and a held call shows you why it is held.
+
+---
 
 ## The desktop window
 
@@ -143,6 +214,8 @@ want. The `release` workflow builds all three platforms on their own machines
 and attaches the installers to the release for a tag. Both the window and the terminal share
 one journal, so either can undo what the other did.
 
+---
+
 ## What it can and cannot do
 
 Every tool gets one of four classifications, written down in a manifest:
@@ -156,7 +229,54 @@ Every tool gets one of four classifications, written down in a manifest:
 
 A tool your manifest does not mention is treated as `irreversible`. That is
 deliberate: silently forwarding an unknown destructive call is the one failure
-worth avoiding most.
+worth avoiding most. `synartesis check` names them, so you meet that decision
+before your agent does.
+
+A few calls are reversible only when nothing is in the way — moving a file onto
+a free path is undone by moving it back, moving it onto an existing file
+destroys what was there. For those, `expect: absent` on the pre-read swaps the
+two: finding nothing is the reversible case, finding something is held for a
+person and recorded with no inverse, so undo says it cannot be undone rather
+than putting half of it back and calling that success.
+
+---
+
+## Writing a policy for your own server
+
+Four servers ship with a policy. For anything else — a database, a ticketing
+system, the MCP server you wrote last week — start by asking the server what it
+has:
+
+```bash
+synartesis init crm -- ./crm-mcp
+```
+
+That connects, lists every tool, and writes a manifest drafted from what the
+server says about itself. If it recognises the server as one that already ships
+with a policy, it adopts that one instead — but only when every tool the policy
+calls is actually there, because a policy whose inverses cannot be called is
+worse than a file of TODOs: it looks finished.
+
+Drafted, not decided. A tool the server marks read-only is written `readonly`
+with a comment telling you to check, since that hint is a statement of intent
+and not a guarantee; everything else lands `irreversible` and gated. The draft
+is fail-closed on purpose, and you open it up one tool at a time as you work
+out how each of them is undone.
+
+Then check it against the running server:
+
+```bash
+synartesis check
+```
+
+It loads the manifest, connects to every server it names, and says which tools
+your policy covers, which it does not, and where the two disagree. A policy
+that names a tool the server no longer has is an error, not a warning.
+
+[Writing a manifest](docs/synartesis-user-guide.md#open-the-file) · [The four classes](docs/synartesis-user-guide.md#the-four-classes) · [Checking it](docs/synartesis-user-guide.md#check-that-it-worked) · [Pinning a tool's shape](#when-the-server-changes-underneath-you)
+
+
+---
 
 ## Has anybody touched it since?
 
@@ -179,6 +299,8 @@ answers. `l` in the screen does the same.
 If you decide the recorded value is the one worth keeping, `undo --force` prints
 every line it would write over and stops; `--force --yes` goes ahead.
 
+---
+
 ## What each policy has actually been tested against
 
 A policy that has met a real server and one written from its documentation are
@@ -204,6 +326,8 @@ wrote yourself: the tool has no business grading your work. Nothing is inferred
 from silence, and all three states are printed, because if silence meant "fine"
 then an ungraded policy and a known-untested one would look identical.
 
+---
+
 ## Undoing something that was never read first
 
 Most undo rides on a pre-read: the value before the write is captured, and
@@ -237,6 +361,8 @@ It is consulted only where there is no read already, so it can never displace a
 working pre-read with a differently shaped one — which would make the post-state
 and the snapshot incomparable and every later comparison meaningless.
 
+---
+
 ## When the server changes underneath you
 
 A policy is a claim about what a tool does, and a tool's name is a weak place to
@@ -276,6 +402,8 @@ reads as protected and is not. Tools that no policy matches need no pin: they ar
 already fail-closed as irreversible and gated, so there is no classification for a
 schema change to corrupt.
 
+---
+
 ## Commands
 
 `synartesis desktop` opens [the window](#the-desktop-window), and says where to
@@ -301,8 +429,8 @@ get it if it is not installed.
 | `prune` | Delete sessions older than 30 days and reclaim the space |
 | `close [id]` | End a session a killed proxy left open |
 
-In the screen: `enter` opens, `u` undoes, `p` previews, `l` checks the world
-now, `f` expands, `c` shows every AI on the machine, `g` shows what is held.
+Every one of those can also be done from [the screen](#the-screen), on the
+arrow keys.
 
 `--manifest` and `--journal` are found rather than typed, from the current
 directory upwards the way a version control tool finds its root, then from
@@ -312,6 +440,8 @@ and `gates`. Exit codes: `0` succeeded, `1` halted or refused, `2` bad usage.
 **Full walkthrough, writing a manifest, and serving over HTTP for clients that
 cannot start a process:** see the [user guide](docs/synartesis-user-guide.md).
 
+---
+
 ## What it does not do
 
 - **It cannot un-send what has been seen.** An email that has been read, a
@@ -353,6 +483,8 @@ means an agent stopping mid-task on a call nobody expected. `synartesis check`
 names every such tool, and the proxy warns about them at startup, so you can
 write a policy before meeting one rather than after.
 
+---
+
 ## Trust
 
 A manifest names commands and Synartesis runs them. Treat one you did not write
@@ -378,6 +510,8 @@ or of the CLI mid-undo loses nothing; only the machine losing power can cost the
 tail of the write-ahead log. `SYNARTESIS_SYNC=full` asks for an fsync per commit
 instead — worth it where fsync is cheap, and measurably not where it is not.
 
+---
+
 ## Development
 
 ```bash
@@ -397,6 +531,44 @@ is expected to work, the code has no platform-specific paths outside
 `src/locate.ts` and `src/install/clients.ts`, and nobody has proved it. If you
 run Windows and something is wrong there, that is worth an issue.
 
+---
+
+## Contributing
+
+The most useful thing you can send is a policy. Four servers ship with one;
+there are hundreds that do not. If you run one — a database, a ticketing
+system, your own — `synartesis init <name> -- <command>` drafts a
+manifest by introspecting it, and a pull request adding that draft under
+[`manifests/`](manifests) makes the tool cover a server it could not cover
+before. Say in the description whether you ran it against the real thing; that
+is what `provenance:` records, and an honest `documented` is worth more than an
+optimistic `live`.
+
+Also wanted, in rough order of how much they help:
+
+- **Windows.** The installer is built and never tested — see
+  [Development](#development). A report either way is worth an issue.
+- **A case where undo got it wrong.** The failure this project cares about most
+  is a confident wrong answer. If undo told you it reverted something and it had
+  not, that is the bug report to open.
+- **A server whose tools do not fit the four classes.** The model has held so
+  far, and the first case it cannot express is worth knowing about.
+
+[`CONTRIBUTING.md`](CONTRIBUTING.md) has the setup, and one command runs the
+same gate a pull request has to pass:
+
+```bash
+pnpm check
+```
+
+Bugs and questions go in [issues](https://github.com/ArhaanDev24/Synartesis/issues).
+Security reports do not — [`SECURITY.md`](SECURITY.md) says where those go
+instead. And if it saved you an afternoon, **[star the
+repo](https://github.com/ArhaanDev24/Synartesis)**; it costs you a click and is
+most of how a project this size gets found.
+
+---
+
 ## Licence
 
 MIT. See [LICENSE](LICENSE).

package/SECURITY.md

@@ -20,8 +20,8 @@ patches to older ones.
 
 | Version | Supported |
 |---|---|
-| 0.6.x | yes |
-| < 0.6 | no |
+| 0.8.x | yes |
+| < 0.8 | no |
 
 ## What the journal holds, and why it matters
 

package/dist/{chunk-FXSKWMNG.js → chunk-O3QDPYEL.js}

@@ -1155,7 +1155,11 @@ var templateValue = z2.lazy(
 var callTemplate = z2.strictObject({
   tool: z2.string().min(1),
   args: z2.record(z2.string(), templateValue).default({}),
-  absent_when: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]).optional()
+  absent_when: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]).optional(),
+  // Only `absent` for now. `present` would mean "refuse unless something is
+  // already here", which is a different feature nobody has asked for, and a
+  // value with no meaning behind it is worse than one that is missing.
+  expect: z2.literal("absent").optional()
 });
 var toolPolicy = z2.strictObject({
   match: z2.string().min(1),
@@ -1304,12 +1308,25 @@ function validate(source, manifest) {
     if (policy.class === "readonly" && policy.snapshot !== void 0) {
       source.fail([...path, "snapshot"], "a readonly tool must not declare a snapshot");
     }
+    const expectsAbsent = policy.snapshot?.expect === "absent";
+    if (policy.verify?.expect !== void 0) {
+      source.fail(
+        [...path, "verify", "expect"],
+        "expect belongs on a snapshot; a verify read runs after the call, when there is nothing left to expect"
+      );
+    }
+    if (expectsAbsent && policy.class !== "reversible") {
+      source.fail(
+        [...path, "snapshot", "expect"],
+        `expect: absent says this call is reversible exactly when the read finds nothing, which only means something for a reversible tool, not a ${policy.class} one`
+      );
+    }
     if (policy.snapshot !== void 0) {
       checkCall(source, [...path, "snapshot"], policy.snapshot, servers, ["$."]);
     }
     if (policy.inverse !== void 0) {
       const allowed = ["$.", "$result."];
-      if (policy.snapshot !== void 0) {
+      if (policy.snapshot !== void 0 && !expectsAbsent) {
         allowed.push("$snapshot.");
       }
       checkCall(source, [...path, "inverse"], policy.inverse, servers, allowed);
@@ -1329,7 +1346,8 @@ function withGate(policy) {
     args: call.args,
     ...call.absent_when === void 0 ? {} : {
       absentWhen: typeof call.absent_when === "string" ? [call.absent_when] : [...call.absent_when]
-    }
+    },
+    ...call.expect === void 0 ? {} : { expect: call.expect }
   });
   const gate = policy.gate ?? (policy.class === "irreversible" ? "always" : "never");
   return {
@@ -1993,4 +2011,4 @@ export {
   observeState,
   connectStdioUpstream
 };
-//# sourceMappingURL=chunk-FXSKWMNG.js.map
+//# sourceMappingURL=chunk-O3QDPYEL.js.map

package/dist/cli.js

@@ -38,7 +38,7 @@ import {
   verifyAgainstServers,
   warnUntested,
   wasRefused
-} from "./chunk-FXSKWMNG.js";
+} from "./chunk-O3QDPYEL.js";
 import {
   DriftConflict,
   ManifestError,

package/dist/proxy.js

@@ -25,7 +25,7 @@ import {
   verifyAgainstServers,
   warnUntested,
   withIdempotencyKey
-} from "./chunk-FXSKWMNG.js";
+} from "./chunk-O3QDPYEL.js";
 import {
   SnapshotError,
   UpstreamError,
@@ -709,18 +709,39 @@ function createProxyServer(options) {
         let snapshot;
         let verify;
         let probe;
-        let missingPriorState;
+        let noWayBack;
+        let foundNothing = false;
+        const expectsAbsent = policy.snapshot?.expect === "absent";
         if (policy.snapshot !== void 0) {
           try {
             verify = planRead(policy.snapshot, { args });
             probe = verify;
             snapshot = await runRead(router, verify, extra.signal);
-            journal.attachSnapshot(pending.actionId, snapshot);
+            if (expectsAbsent) {
+              noWayBack = {
+                asked: `something is already there, so this cannot be undone \u2014 putting back what this call moves would leave nothing where the old contents were`,
+                recorded: `the pre-read expected nothing and found something, so this call overwrote it and no single inverse can put both back`
+              };
+              verify = void 0;
+            } else {
+              journal.attachSnapshot(pending.actionId, snapshot);
+            }
           } catch (error) {
             const reason = describe(error);
             if (error instanceof SnapshotError && error.absent) {
-              missingPriorState = reason;
-              verify = void 0;
+              foundNothing = true;
+              if (expectsAbsent) {
+                log?.debug(
+                  { seq: pending.seq, tool: route.tool },
+                  "pre-read found nothing, which is what makes this reversible"
+                );
+              } else {
+                noWayBack = {
+                  asked: `nothing was captured to restore, so this cannot be undone \u2014 the read said: ${reason}`,
+                  recorded: `no prior state existed, so there is nothing to restore: ${reason}`
+                };
+                verify = void 0;
+              }
             } else {
               journal.markFailed(pending.actionId, reason);
               log?.error(
@@ -734,8 +755,8 @@ function createProxyServer(options) {
             }
           }
         }
-        const priorState = probe === void 0 || missingPriorState !== void 0 ? { present: false } : { present: true, value: snapshot };
-        if (missingPriorState !== void 0 && !askedAlready) {
+        const priorState = probe === void 0 || foundNothing ? { present: false } : { present: true, value: snapshot };
+        if (noWayBack !== void 0 && !askedAlready) {
           const standing = journal.findApproval({
             server: route.upstream.name,
             tool: route.tool,
@@ -743,18 +764,14 @@ function createProxyServer(options) {
             notBefore: new Date(Date.now() - APPROVAL_WINDOW_MS).toISOString()
           });
           if (standing === void 0) {
-            await decide(
-              `nothing was captured to restore, so this cannot be undone \u2014 the read said: ${missingPriorState}`
-            );
+            await decide(noWayBack.asked);
           } else if (journal.adoptApproval(pending.actionId, standing)) {
             log?.info(
               { action: pending.actionId, by: standing.approvedBy, from: standing.runId },
               "proceeding on a standing approval"
             );
           } else {
-            await decide(
-              `nothing was captured to restore, so this cannot be undone \u2014 the read said: ${missingPriorState}`
-            );
+            await decide(noWayBack.asked);
           }
         }
         const forwarded = {
@@ -800,13 +817,11 @@ function createProxyServer(options) {
           if (inferred !== void 0) {
             warnings.push(inferred);
           }
-          if (missingPriorState !== void 0) {
-            warnings.push(
-              `no prior state existed, so there is nothing to restore: ${missingPriorState}`
-            );
+          if (noWayBack !== void 0) {
+            warnings.push(noWayBack.recorded);
           }
           let inverse;
-          if (policy.inverse !== void 0 && missingPriorState === void 0) {
+          if (policy.inverse !== void 0 && noWayBack === void 0) {
             try {
               inverse = planInverse(policy.inverse, context);
             } catch (error) {
@@ -857,7 +872,7 @@ function createProxyServer(options) {
               const recovered = recoverInverse(
                 policy,
                 { args, snapshot },
-                missingPriorState !== void 0
+                noWayBack !== void 0
               );
               journal.markApplied(pending.actionId, {
                 result: void 0,

package/manifests/filesystem.yaml

@@ -88,16 +88,46 @@ tools:
         path: "$.path"
         content: "$snapshot.content"
 
-  # Only reversible when the destination did not exist. Moving onto a file
-  # that did overwrites it, and moving back afterwards restores the source and
-  # leaves nothing where the destination's contents were: undo reports success
-  # while the file it destroyed stays destroyed. There is no pre-read that
-  # would tell the two cases apart -- a snapshot that finds nothing is how this
-  # policy says "cannot be undone", which is backwards here, since finding
-  # nothing is the safe case. So it asks.
+  # Reversible exactly when the destination did not exist, which is what
+  # `expect: absent` says.
+  #
+  # Moving onto a path where nothing is, is undone by moving the file back:
+  # the state this replaces is absence, and moving it off restores absence
+  # exactly. Moving onto a file that does exist overwrites it, and one inverse
+  # cannot both move the file back and restore what it landed on -- undo would
+  # report success over a file it had destroyed.
+  #
+  # Both cases were gated before, because the machinery read "the pre-read
+  # found nothing" as "there is nothing to put back" -- true of a write, and
+  # precisely backwards here, where finding nothing is the safe case. Measured
+  # both ways against the real server: as a plain reversible rule the safe move
+  # came back `partial` with the file still moved, and the dangerous one came
+  # back `rolled_back` with the overwritten file gone.
+  #
+  # And the pre-read is load-bearing, not belt and braces. This server's own
+  # description of move_file says "If the destination exists, the operation
+  # will fail" -- it does not. It renames over the top, silently, because
+  # that is what rename(2) does on POSIX. Taking the description at its word
+  # would have made this rule unconditionally reversible and the overwrite
+  # unrecoverable and unremarked. tests/expect-absent.test.ts pins the real
+  # behaviour so a version that starts matching its documentation is a
+  # failing test rather than a surprise.
   - match: "fs.move_file"
-    class: irreversible
-    gate: always
+    class: reversible
+    snapshot:
+      tool: "fs.read_text_file"
+      args:
+        path: "$.destination"
+      # Same reasoning as the two writes above: anything that is not absence
+      # is a failed read, not an empty destination, and a destination that
+      # exists but cannot be read must not be treated as a free space.
+      absent_when: ["ENOENT", "no such file"]
+      expect: absent
+    inverse:
+      tool: "fs.move_file"
+      args:
+        source: "$.destination"
+        destination: "$.source"
 
   # No rmdir exists on this server, so a directory once created stays.
   - match: "fs.create_directory"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synartesis",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "An undo layer for AI agents.",
   "type": "module",
   "private": false,