synartesis 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 What changed, and why it mattered. Dates are release dates.
 
+## 0.5.2 — 2026-09-10
+
+### Changed
+
+- **The README is a third of its former length** — 714 lines to 210. It had
+  grown a full walkthrough and a manifest-authoring guide, both of which already
+  exist in the user guide, so it was three documents pretending to be one and
+  the first screen was a long way from `npm install`. What is left is the
+  argument, the two real terminal shots, install, the four classes, the commands,
+  and the limits; the walkthrough and manifest authoring are one link away.
+
+  It also documents what has shipped since it was last written: `show --live`,
+  `show --full`, `undo --force [--yes]`, `undo --replan`, the `l` key and the
+  rest of the screen's keys, `SYNARTESIS_SYNC`, and which policies are actually
+  proven against a real server rather than merely checked for tool existence.
+
+  No code changed. npm cannot refresh a package page without a version, and this
+  also carries 0.5.1's latency fix to anyone installing from npm.
+
+## 0.5.1 — 2026-09-10
+
+### Changed
+
+- **The journal is back to `synchronous = NORMAL`, reverting 0.5.0.** The
+  argument for FULL was right and the measurement behind it was taken on the
+  wrong machine.
+
+  This proxy commits three times per tool call — the pending row, the snapshot,
+  and the outcome — and under FULL each commit is an fsync that has to reach the
+  platter. On the NVMe it was benchmarked on, that is microseconds, and the
+  change looked free: 0.0246 ms per write against 0.0594. On a CI runner, a
+  container, or anything with networked storage an fsync is tens of
+  milliseconds, and three of them put the proxy's p95 overhead at **132 ms
+  against a 10 ms budget**. CI caught it on the release that shipped it, having
+  been green on every commit before.
+
+  The three commits cannot be collapsed into one: the snapshot has to be durable
+  *before* the call goes out, which is the entire point of taking it. So the
+  cost is structural, and the default returns to the setting whose cost is
+  predictable. `SYNARTESIS_SYNC=full` asks for the fsync where it is cheap or
+  where the tail of the log matters more than latency.
+
+  What is given up is stated plainly: under NORMAL, a crash of the process or of
+  the CLI mid-undo still loses nothing, but the machine losing power can cost
+  the tail of the write-ahead log — and what is at that tail is the record of
+  calls that really happened.
+
+  The performance thresholds that caught this were left exactly where they were.
+  A 10 ms budget that fails at 132 ms is a budget doing its job.
+
 ## 0.5.0 — 2026-09-10
 
 A safety release. Two more races of the same family as 0.4.2's, one structural

package/README.md

@@ -23,59 +23,23 @@ tells you `update_customer` ran forty times, not what the values were before.
 
 ## What it looks like
 
-Two commands, both real. The output below was produced by
-[`./demo/filesystem-demo.sh`](demo/filesystem-demo.sh) against the official
-filesystem MCP server and pasted, not typeset.
-
-An agent overwrote a file and tried to move another. One command puts the
-first back and reports that the second never happened:
+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.
+One command puts the first back and reports that the second never happened:
 
 ![synartesis undo, reverting a write and skipping a gated move](https://raw.githubusercontent.com/ArhaanDev24/Synartesis/main/brand/synartesis-undo.png)
 
-`skip` is the interesting row. `move_file` is irreversible on that server, so
-it was never applied in the first place — there is nothing to undo.
+`skip` is the interesting row. `move_file` is irreversible on that server, so it
+was never applied in the first place — there is nothing to undo.
 
 Now the same damage, except a colleague edited the file before you got to the
 undo. Writing the old contents back would destroy their work, so it does not:
 
 ![synartesis undo halting on drift, showing the human's line](https://raw.githubusercontent.com/ArhaanDev24/Synartesis/main/brand/synartesis-drift.png)
 
-It stops at the record that moved and exits non-zero. Anything it had already
-put back stays put back; `synartesis show` tells you what is left.
-
-## What it can and cannot do
-
-Every tool gets one of four classifications, which you write down in a manifest:
-
-| Class | Meaning | Example | What happens |
-|---|---|---|---|
-| `readonly` | Changes nothing | `get_customer` | Recorded, forwarded |
-| `reversible` | Prior state can be restored exactly | `update_customer` | State captured before the write; written back on undo |
-| `compensable` | Cannot be reversed, but can be offset | `create_charge` | A different call neutralises it |
-| `irreversible` | Neither | `send_email` | **Suspended until a human approves it** |
-
-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.
-
-## Requirements
-
-| Tool | Version | Check with |
-|---|---|---|
-| Node | 22 or newer | `node --version` |
-| pnpm | 9 or newer | `pnpm --version` |
-| A C toolchain | any | `cc --version` |
-
-`pnpm` comes with Node via corepack:
-
-```bash
-corepack enable pnpm
-```
-
-The C toolchain is only needed if you build from source: npm ships a prebuilt
-SQLite binding for common platforms and installs without one. To build from a
-clone on macOS run `xcode-select --install`; on Debian or Ubuntu,
-`apt install build-essential`.
+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.
 
 ## Install
 
@@ -89,612 +53,144 @@ Then, from anywhere:
 synartesis install
 ```
 
-That finds what Claude Code, Claude Desktop, Cursor or Codex already list, writes one
-policy covering all of it, and points each entry at the proxy. Servers it
-recognises get the policy that ships for them and work immediately; the rest
-are drafted with every tool held until you say how to undo it. Your config is
-copied aside first, `synartesis uninstall` puts it back, and `synartesis
-status` says what is covered.
+That finds what Claude Code, Claude Desktop, Cursor or Codex already list,
+writes one policy covering all of it, and points each entry at the proxy.
+Servers it recognises get the policy that ships for them and work immediately;
+the rest are drafted with every tool held until you say how to undo it. Your
+config is copied aside first, `synartesis uninstall` puts it back, and
+`synartesis status` says what is covered.
 
-Each server keeps its own entry and its own proxy, selected with `--server`,
-so **no tool is renamed** — the agent sees exactly the names it saw before.
+Each server keeps its own entry and its own proxy, so **no tool is renamed** —
+the agent sees exactly the names it saw before. **Your agent needs nothing
+installed.**
 
-That is for you: the screen, `undo`, `watch`, `approve`. **Your agent needs
-nothing installed** — the config block below fetches the proxy on demand.
+Needs Node 22 or newer. npm ships a prebuilt SQLite binding, so no toolchain is
+required unless you build from a clone.
 
-Or the script, which builds from source and links the same two commands:
+Then just:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/ArhaanDev24/Synartesis/main/install.sh | bash
+synartesis
 ```
 
-Or from a clone, if you would rather read it first:
+One screen: what agents have done, what is held for approval, every AI on the
+machine, and undo — all on the arrow keys.
 
-```bash
-git clone https://github.com/ArhaanDev24/Synartesis.git && cd Synartesis && ./install.sh
-```
-
-The script checks your Node version, builds, and links `synartesis` and
-`synartesis-proxy` into the first writable directory already on your PATH. It
-edits no shell profile and needs no sudo. Pass `--no-link` to build only.
-
-```bash
-synartesis --help
-```
-
-If nothing could be linked, nothing breaks: every command Synartesis prints
-spells itself out in whichever form actually runs on your machine.
-
-## Walkthrough
-
-This uses a toy CRM that ships with the repo, so you can see the whole loop
-without pointing anything at real data. Run it from a scratch directory.
-
-```bash
-mkdir -p /tmp/synartesis-demo && cd /tmp/synartesis-demo
-```
-
-### 1. Write a policy
-
-`init` starts a server, asks it what tools it has, and writes a manifest.
-Replace `SYNARTESIS` with the path you cloned into.
-
-```bash
-node SYNARTESIS/dist/cli.js init crm -- node SYNARTESIS/dist/toy-crm.js --state ./crm.json
-```
-
-For the servers most people start with — files, memory, git, github — `init`
-recognises the server and uses the finished policy bundled here, after checking
-every rule against the tools that server actually advertises. If a rule names a
-snapshot or an inverse the server does not have, the whole policy is dropped
-and you get the TODOs instead: a policy whose inverses cannot be called is
-worse than none, because it looks done.
-
-The toy CRM below is deliberately not one it knows, so this walkthrough shows
-the manual path.
-
-`init` prints the path it wrote to. Unless a policy already sits above the
-directory you are standing in, that is `~/.synartesis/synartesis.yaml`. Open it:
-every tool that isn't a self-declared read starts as `irreversible` with a
-`TODO`. **Working through those TODOs is the job.** A finished policy for this
-fixture ships in the repo, so copy it into this directory rather than typing it
-out — a policy here takes precedence over the one in your home:
-
-```bash
-cp SYNARTESIS/manifests/toy-crm.yaml ./synartesis.yaml
-```
-
-Then edit the `args` line so it points at your clone and keeps its data in
-this directory. The copy ships with `args: ["dist/toy-crm.js"]`; it needs both
-the path to your clone and the `--state` file:
-
-```yaml
-servers:
-  crm:
-    command: node
-    args: ["SYNARTESIS/dist/toy-crm.js", "--state", "./crm.json"]
-```
-
-### 2. Point your agent at the proxy
-
-Wherever your MCP client lists servers, replace the entry for the server you
-want covered with the proxy. For Claude Desktop or Claude Code that is a
-`mcpServers` block:
-
-```json
-{
-  "mcpServers": {
-    "crm": {
-      "command": "node",
-      "args": ["SYNARTESIS/dist/proxy.js", "--manifest", "/tmp/synartesis-demo/synartesis.yaml"]
-    }
-  }
-}
-```
-
-That spells out the clone, because this walkthrough runs from one. Outside it,
-there is nothing to install first and nothing to point at:
-
-```json
-{
-  "mcpServers": {
-    "synartesis": {
-      "command": "npx",
-      "args": ["-y", "synartesis", "proxy", "--manifest", "/Users/you/.synartesis/synartesis.yaml"]
-    }
-  }
-}
-```
-
-The agent sees the same tools with the same names and the same results. That is
-the point: nothing about your agent changes.
-
-For this walkthrough you do not need a real agent. This does the same thing:
-
-```bash
-printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"demo-agent","version":"0"}}}' '{"jsonrpc":"2.0","method":"notifications/initialized"}' '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"update_customer","arguments":{"id":"c_001","plan":"free","notes":"wrong edit"}}}' '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"delete_customer","arguments":{"id":"c_002"}}}' | node SYNARTESIS/dist/proxy.js --manifest ./synartesis.yaml --journal ./journal.db > /dev/null
-```
-
-Look at the damage:
-
-```bash
-cat crm.json
-```
-
-Ada is on the wrong plan with the wrong notes, and Grace is gone.
-
-### 3. See what it did
-
-```bash
-node SYNARTESIS/dist/cli.js list --journal ./journal.db
-```
-
-```bash
-node SYNARTESIS/dist/cli.js show RUN_ID --journal ./journal.db
-```
-
-`show` prints each call with its class, its status, and the exact call that
-would undo it, already resolved to literal values.
-
-### 4. Undo it
-
-Look before you leap:
-
-```bash
-node SYNARTESIS/dist/cli.js undo RUN_ID --dry-run --journal ./journal.db
-```
-
-Then do it:
-
-```bash
-node SYNARTESIS/dist/cli.js undo RUN_ID --journal ./journal.db
-```
-
-```bash
-cat crm.json
-```
-
-Grace is back and Ada is on her original plan, with her original notes.
-
-### 5. Watch it refuse
-
-Undo is not a blunt instrument. If something else changed a record after the
-agent touched it, writing the old value back would destroy that work, so
-Synartesis stops and shows you both values.
-
-Run the damage command from step 2 again. That creates a second run, so take
-the run id from the top of `list`, which is ordered most recent first. Then
-edit the record by hand:
-
-```bash
-node -e 'const f="./crm.json",s=JSON.parse(require("fs").readFileSync(f));s.customers.c_001.notes="a human wrote this";require("fs").writeFileSync(f,JSON.stringify(s,null,2))'
-```
-
-```bash
-node SYNARTESIS/dist/cli.js undo RUN_ID --journal ./journal.db
-```
-
-It halts at the record that moved, prints the expected and actual state, and
-exits non-zero. It is not all-or-nothing: undo works newest first, so anything
-it had already put back before reaching the drifted record stays put back —
-here `delete_customer` is reversed and `c_002` comes back, and then it stops.
-`show` afterwards tells you which actions are still outstanding. Once you have
-resolved the conflict yourself, `undo --replan` rebuilds the plan against the
-world as it now is and carries on.
-
-## Approving what cannot be undone
-
-`send_email` is classified `irreversible`, so the agent cannot send one on its
-own. The call is **refused immediately** with an action id and the command that
-would approve it. The agent tells you, you decide, and it tries again.
-
-It does not hold the call open while waiting. That was the first design and it
-does not survive contact with a real client: every useful window for a person
-to notice, open a terminal and decide is longer than a client will wait for a
-tool, so the two cannot be reconciled by picking a better timeout.
-
-Approval also does not happen on the terminal the agent is using: the proxy
-talks MCP over stdin and stdout, so there is nothing there to prompt on, and a
-desktop client has no terminal at all. The request goes to the journal, and you
-answer it from anywhere:
-
-```bash
-node SYNARTESIS/dist/cli.js gates --journal ./journal.db
-```
-
-```bash
-node SYNARTESIS/dist/cli.js approve ACTION_ID --by your-name --journal ./journal.db
-```
-
-```bash
-node SYNARTESIS/dist/cli.js deny ACTION_ID --by your-name --reason "not this one" --journal ./journal.db
-```
-
-An approval is **single use** and expires after an hour, so it covers the retry
-it was granted for and cannot quietly authorise the same call tomorrow. It is
-not tied to one session, because people restart their client and an approval
-stranded in a dead session would be no approval at all.
+## What it can and cannot do
 
-Nothing is ever approved by silence. An unanswered request simply stays
-unanswered, visible in `synartesis gates` until someone decides.
+Every tool gets one of four classifications, written down in a manifest:
 
-The agent is told all of this when it connects, so it can explain itself rather
-than reporting an opaque failure.
+| Class | Meaning | Example | What happens |
+|---|---|---|---|
+| `readonly` | Changes nothing | `get_customer` | Recorded, forwarded |
+| `reversible` | Prior state can be restored exactly | `update_customer` | State captured before the write; written back on undo |
+| `compensable` | Cannot be reversed, but can be offset | `create_charge` | A different call neutralises it |
+| `irreversible` | Neither | `send_email` | **Suspended until a human approves it** |
 
-## Real servers
+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.
 
-Synartesis has nothing to do with email in particular. It sits on the MCP
-protocol, so its subject is whatever the servers you have connected can do:
-your files, your repositories, your database, your tickets, your agent's own
-memory. What it can undo depends entirely on what those servers expose, and
-each manifest below says plainly where that runs out.
+## Has anybody touched it since?
 
-| Manifest | Server | State it governs |
-| --- | --- | --- |
-| [`filesystem.yaml`](manifests/filesystem.yaml) | `@modelcontextprotocol/server-filesystem` | real files on disk |
-| [`memory.yaml`](manifests/memory.yaml) | `@modelcontextprotocol/server-memory` | the knowledge graph an agent keeps about you |
-| [`git.yaml`](manifests/git.yaml) | `mcp-server-git` | a real repository's index and history |
-| [`github.yaml`](manifests/github.yaml) | `github/github-mcp-server` | issues, pull requests, file contents |
-| [`toy-crm.yaml`](manifests/toy-crm.yaml) | the fixture in this repo, not in the published package | the worked example of every class |
+Synartesis records what an agent does, not what happens to a file. Nothing you
+do by hand goes through the proxy — which is exactly what makes the drift check
+work: when undo reads a file and finds bytes it never recorded, it knows
+somebody else has been there.
 
-Every one of those but `github.yaml` was checked against the server actually
-running. Two demos run the whole loop for real:
+To ask before you find out the hard way:
 
 ```bash
-./demo/filesystem-demo.sh
-./demo/memory-demo.sh
-```
-
-The filesystem demo overwrites a file and moves another, restores both, then
-shows undo refusing when a human edited the file in between, and the gate
-refusing to create a directory this server has no way to remove.
-
-The memory demo is the sharper one. The agent adds two people to the graph, one
-of whom was already there, and the server quietly ignores the duplicate. Undo
-therefore has to remove exactly one of them: the inverse is built from what the
-server said it created, not from what the agent asked for, so the person who
-was there first survives being undone. The same session then tries to delete an
-entity and is held, because deleting an entity also deletes every relation
-touching it and one inverse call cannot put back both.
-
-### Where each one runs out
-
-The limits are the interesting part, and they are properties of the servers
-rather than of Synartesis.
-
-- **filesystem**: `move_file` is reversible from its arguments alone, so no
-  pre-read is declared and drift cannot be checked for it. `create_directory`
-  is `irreversible` not because directories are precious but because this
-  server exposes no way to remove one.
-- **memory**: `add_observations` and `delete_observations` are exact opposites
-  that disagree about what to call the same field. A path can read a field and
-  cannot rename one, so that inverse cannot be written at all and the call is
-  gated instead.
-- **git**: nearly every read this server offers answers in prose meant for a
-  person, so almost nothing can be inverted from a captured state however
-  reversible the underlying git operation is. Commits are gated because this
-  server exposes no reset, no revert, and no way to move a branch.
-
-Two things worth knowing if you write your own, both found by running these
-against live servers rather than by reading documentation:
-
-`$result` is the structured block, and it need not match the text one. The
-memory server answers `create_entities` with a bare list in its text block and
-`{"entities": [...]}` in `structuredContent`. Synartesis walks the structured
-one, because that is the machine-readable contract.
-
-And `synartesis check` proves a tool exists, not that a path resolves. It
-cannot: no call has been made, so there is no result to walk. Run the thing
-once and read `synartesis show` before you rely on an inverse.
-
-## Writing a manifest
-
-The manifest is the whole product. It should take fifteen minutes for an API
-you know.
-
-```yaml
-version: 1
-
-servers:
-  crm:
-    command: node
-    args: ["./crm-server.js"]
-
-tools:
-  - match: "crm.get_customer"
-    class: readonly
-
-  # Read the record before overwriting it, then write that record back.
-  - match: "crm.update_customer"
-    class: reversible
-    snapshot:
-      tool: "crm.get_customer"
-      args:
-        id: "$.id"
-    inverse:
-      tool: "crm.update_customer"
-      args:
-        id: "$.id"
-        name: "$snapshot.name"
-        plan: "$snapshot.plan"
-
-  # Nothing to read beforehand; the id only exists once the call returns.
-  - match: "crm.create_customer"
-    class: compensable
-    inverse:
-      tool: "crm.delete_customer"
-      args:
-        id: "$result.id"
-
-  - match: "crm.send_*"
-    class: irreversible
-    gate: always
-```
-
-There are exactly three things a value can refer to:
-
-| Prefix | Refers to | Available in |
-|---|---|---|
-| `$.` | the arguments the agent sent | `snapshot` and `inverse` |
-| `$snapshot.` | what the pre-read captured | `inverse` |
-| `$result.` | what the forward call returned | `inverse` |
-
-Anything else is a literal. A reference can stand alone, in which case the
-value keeps its type, or sit inside a sentence, in which case it is substituted
-as text:
-
-```yaml
-sha: "$result.content.sha"                 # the value itself
-message: "Revert agent change to $.path"   # text with the path substituted
-```
-
-Write `$$` for a literal dollar sign. There are no expressions, conditionals or
-functions, and there will not be: the moment this becomes a language it stops
-being something you can write in fifteen minutes.
-
-Paths can index a list with `[0]` and read one field from every element with
-`[]`:
-
-```yaml
-labels: "$snapshot.labels[].name"   # [{name: "bug"}, ...] becomes ["bug", ...]
-```
-
-That covers the common case where an API hands a field back richer than it
-takes it, which is what GitHub does with issue labels. `[]` reads the same key
-from each element and nothing else: it is still a path, not a transform. A
-reference copies values, it cannot compute them, so an API needing a genuinely
-different shape is one the inverse should leave that field out of, and say so.
-
-Other things to know:
-
-- `match` supports `*`, which matches within one segment: `crm.send_*` matches
-  `crm.send_email` but not `crm.a.b`. The most specific pattern wins regardless
-  of the order rules are written in.
-- The inverse of a patch should restore **every** field, not re-apply a patch.
-  If the same record is edited twice in one run, a partial inverse leaves the
-  fields the second edit touched behind.
-- `gate: on_write` is a heuristic for tools like a raw SQL runner, where
-  destructiveness cannot be read from the tool name. Anything it cannot
-  confidently read as a single read statement is gated. Use `gate: always`
-  wherever certainty matters.
-- A malformed manifest stops the proxy from starting, with the file and line to
-  fix. It will never run with a policy it could not understand.
-
-### Saying what absence looks like
-
-A pre-read that fails tells you nothing about *why*. MCP has no code for "not
-found", so a snapshot that comes back with an error could mean the resource was
-never there — an agent creating a file — or that it exists and could not be
-read. Those need opposite answers: the first is a call to ask a person about,
-the second is a call to refuse outright.
-
-Tell the policy what its server says when a thing is not there:
-
-```yaml
-- match: "fs.write_file"
-  class: reversible
-  snapshot:
-    tool: "fs.read_text_file"
-    args:
-      path: "$.path"
-    absent_when: ["ENOENT", "no such file"]
+synartesis show <session> --live
 ```
 
-Anything else the pre-read reports is then a failed snapshot, and the write is
-refused rather than offered for approval as a creation. Without `absent_when`,
-every error has to be read as absence, which is the safe reading but a blunt
-one. Every policy bundled here declares it.
+It reads every resource the session touched as it is now and says which still
+match. Nothing is written, no reversing call is sent, and unlike
+`undo --dry-run` it does not stop at the first conflict — five writes get five
+answers. `l` in the screen does the same.
 
-### The size of what you can snapshot
-
-Past a few megabytes a resource cannot be read back through a stdio MCP
-connection — the reply is too large to carry, and the connection closes.
-Synartesis reconnects and says so, and refuses the write rather than applying a
-change it could not capture. That is the right answer, but it does mean
-**writes to very large files are refused, not undone**. Nothing is lost; the
-call simply does not go through.
-
-Where the ceiling falls depends on the server and its transport, so no exact
-figure here would be true of every one. Measured against the bundled
-filesystem policy: a 4 MB file was captured and restored intact; 8 MB and above
-was refused with the file untouched.
+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.
 
 ## Commands
 
 | Command | Does |
 |---|---|
+| `synartesis` | The screen. Everything below can be done from it |
+| `install` / `uninstall` / `status` | Cover the clients on this machine, put them back, say what is covered |
 | `init <server> -- <cmd>` | Introspect a server and draft a manifest |
-| `list` | Every recorded run |
-| `show <runId>` | One run's timeline, with the undo for each step |
-| `show <runId> --live` | The same, plus what has changed in the world since |
-| `gates` | What is waiting for a decision |
-| `approve <actionId>` | Allow a suspended call |
-| `deny <actionId>` | Refuse one |
-| `undo <runId>` | Reverse a run, newest action first |
-| `undo <runId> --replan` | Same, but rebuild each undo from the current manifest |
-| `undo <runId> --force` | Print every change it would write over; `--yes` goes ahead |
 | `check` | Load a manifest and verify it against the servers it names |
-| `prune` | Delete runs older than 30 days and reclaim the space |
-| `close [runId]` | End a run a killed proxy left open. Nothing guesses at this: several proxies can share one journal, so a run left active is indistinguishable from one still being worked on |
-
-`--manifest` and `--journal` are found rather than typed. Both are looked for
-from the current directory upwards, the way a version control tool finds its
-root, so inside a project that has a `synartesis.yaml` every command works with
-no flags at all. When there is nothing above you either, both come from
-`~/.synartesis` — most of what anyone guards is not part of a project, and
-should not need a directory of its own. `SYNARTESIS_HOME` moves that. A journal
-that does not exist yet is placed beside the policy, so the proxy that creates
-it and the CLI that reads it agree without either being told.
-
-Other flags: `--dry-run`, `--to <seq>` and `--replan` on `undo`, `--all` on
-`approve` and `deny`, `--json` on `list`, `show` and `gates`, `--older-than
-<days>` and `--dry-run` on `prune`. `synartesis --version` prints the version
-and nothing else.
-
-Exit codes: `0` succeeded, `1` halted or refused, `2` bad usage or
-configuration.
-
-### Serving over HTTP
-
-Most clients start the proxy themselves over stdio. ChatGPT's connectors do
-not: they take a remote HTTPS endpoint and will not run a process on your
-machine. For those, serve it:
-
-```bash
-synartesis proxy --manifest ~/.synartesis/synartesis.yaml --http 9123 --token "$SYNARTESIS_TOKEN"
-```
-
-The endpoint is `/mcp` and every request needs `Authorization: Bearer <token>`.
-A token of at least 16 characters is **required** — it refuses to start without
-one — and it binds to `127.0.0.1` unless `--http-host` says otherwise, which
-warns when it is not loopback. A session that goes quiet for half an hour is
-closed; `--http-idle <seconds>` changes that.
-
-Reaching it from the internet means putting a tunnel in front of it. That is
-deliberately your decision and not a flag: what is on the other end can write
-through every server in your policy, so treat the token like a password and
-prefer a tunnel that does its own authentication.
-
-The proxy takes `--manifest`, `--journal` and `--log-level`. It also still
-accepts `--gate-timeout <seconds>`, which does nothing: a held call is refused
-immediately rather than holding the connection open, so there is no wait to cut
-short. Passing it logs a warning saying as much. It logs structured JSON to stderr; stdout is reserved for
-protocol traffic.
+| `list` | Every recorded session |
+| `show <id>` | One session's timeline, with the undo for each step |
+| `show <id> --live` | The same, plus what has changed in the world since |
+| `show <id> --full` | Every argument, snapshot and inverse, nothing elided |
+| `gates` / `approve <id>` / `deny <id>` | What is waiting, and answering it |
+| `undo <id>` | Reverse a session, newest action first |
+| `undo <id> --dry-run` | Plan it and change nothing |
+| `undo <id> --replan` | Rebuild each undo from the current manifest |
+| `undo <id> --force [--yes]` | Print what it would write over; `--yes` goes ahead |
+| `watch` | Live activity, with approvals answerable in place |
+| `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.
+
+`--manifest` and `--journal` are found rather than typed, from the current
+directory upwards the way a version control tool finds its root, then from
+`~/.synartesis`. `SYNARTESIS_HOME` moves that. `--json` works on `list`, `show`
+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
   posted message, a file deleted with no backup. This is why the gate exists.
 - **Compensable actions cannot be checked for drift.** They declare no pre-read,
-  so undo compensates them and marks them `[unverified]` in its report.
+  so undo compensates them and marks them `[unverified]`.
 - **Undo halts on uncertainty, and steps over the merely permanent.** Drift, an
-  unknown outcome, or a failed reversing call stop it, because continuing past
-  those could destroy something. An action that simply cannot be undone, like a
-  sent email, is reported and left in place while everything else is reverted:
-  no amount of stopping un-sends it, and stopping would only leave the rest
-  wrong too. Either way the run is marked `partial`.
-- **A call interrupted mid-flight is recorded as unknown**, not as failed. Undo
-  refuses to walk past it, because whether it applied cannot be determined.
+  unknown outcome, or a failed reversing call stop it. An action that simply
+  cannot be undone is reported and left in place while everything else is
+  reverted. Either way the session is marked `partial`.
+- **An error is not proof that nothing happened.** A timeout or a tool-level
+  error after a write leaves the outcome *unknown*, not failed, and undo will
+  not step past it. Where a pre-read exists it is consulted to settle the
+  question instead of guessing.
 - **An undo is only as good as the policy that recorded it.** Inverses are
-  resolved when the call happens, not when you undo, so a mistake in a manifest
-  is baked into every run made under it. `undo --replan` rebuilds them from a
-  corrected manifest using the state already captured, which is the way out.
-
-## Has anybody touched it since?
-
-Synartesis records what an agent does, not what happens to a file. Nothing you
-do by hand goes through the proxy, so an edit of your own is invisible to the
-journal — and that is what makes the drift check work: when undo reads a file
-and finds bytes it never recorded, it knows somebody else has been there.
-
-The cost used to be that you found out by walking into it. You ran the undo,
-and it refused. To ask first:
-
-```bash
-synartesis show <session> --live
-```
+  resolved when the call happens, so a mistake in a manifest is baked into every
+  run made under it. `undo --replan` rebuilds them from a corrected one.
 
-It reads every resource the session touched, as it is now, and says which of
-them still match what the run left:
-
-```
-  1  ← reversible   applied   filesystem.write_file  changed since
-       at line 13:
-       + A HUMAN WAS HERE
-       0 removed, 1 added.
-
-  1 changed since this ran; undoing would write over it
-```
-
-Nothing is written, no reversing call is sent, and no row changes status.
-Unlike `undo --dry-run`, it does not stop at the first conflict — a session
-with five writes reports on all five. `l` in the screen does the same thing.
-
-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.
-
-## Watching it work
-
-Synartesis is not a daemon and cannot be one. An MCP client spawns a stdio
-server itself and owns its lifetime, so nothing long-running could sit in
-between and see those calls. What a person wants from a daemon is usually the
-reassurance that it is there and doing something, and that needs somewhere to
-look rather than a background process:
-
-```bash
-synartesis watch
-```
-
-It redraws as the agent works: what has been called, what class each call was,
-and anything waiting on a decision, with the command to approve it. Ctrl-C
-stops it. Piped rather than run in a terminal, it prints the state once and
-exits.
+The bundled **filesystem** policy is tested against the real server: exact
+byte-for-byte restoration, drift refusal, and absence told apart from a read
+that failed. The **memory, git and github** policies are checked only for tool
+existence — their recovery guarantees are not yet proven.
 
 ## Trust
 
 A manifest names commands and Synartesis runs them. Treat one you did not write
 the way you would treat a shell script from the same source: read it first.
-There is no sandbox here, and there is not meant to be.
-
-### What the journal holds
-
-Putting a file back means having kept what was in it, so the journal is not a
-log of what happened. It is a copy of the data: the contents of every resource
-before it was written, the arguments of every call, and what each server sent
-back. A key that was sitting in a file your agent touched is in there in plain
-text. That is not a leak to be closed — it is the thing that makes undo work.
-
-So it is treated as private data. The journal is created `0600` and the
-directory Synartesis makes for it `0700`, and `0600` is re-applied every time a
-journal is opened, which closes one written by an older version the first time
-a newer one touches it. A directory that already existed is left alone, because
-a journal can sit beside a policy inside a project and silently making your
-project directory `0700` would be the worse surprise. If your `~/.synartesis`
-predates 0.3.0, `chmod 700 ~/.synartesis` is worth doing once by hand.
-
-Nothing is encrypted. Full-disk encryption answers a stolen laptop; file
-permissions answer another account on a machine you share.
-
-### How fast it grows
-
-Every write keeps the resource as it was, the resource as it became, and the
-call that did it, so the journal grows at roughly **four times the bytes your
-agent writes** and never shrinks on its own. Thirty edits of one 200 kB file
-came to 24 MB.
-
-```bash
-synartesis prune                      # runs finished more than 30 days ago
-synartesis prune --older-than 7 --dry-run
-```
-
-It deletes whole runs and then `VACUUM`s, since deleting rows leaves a SQLite
-file exactly the size it was. It will not touch a run that is still active, or
-one holding a call that is waiting on a person or whose outcome is unknown —
-age is not an answer to a question nobody answered. A pruned run cannot be
-undone afterwards, which is the whole of the trade.
 
-Nothing prunes on a timer. A tool for undoing things should not discard the
-record of what was done unless it is asked to.
+**The journal is a copy of your data, not a log.** Putting a file back means
+having kept what was in it, so the contents of every resource before it was
+written are in there in plain text — including any key that was sitting in a
+file your agent touched. That is not a leak to be closed; it is the thing that
+makes undo work. It is created `0600` in a `0700` directory, and nothing is
+encrypted: full-disk encryption answers a stolen laptop, permissions answer
+another account on a machine you share.
+
+**It grows at roughly four times the bytes your agent writes** and never shrinks
+on its own — thirty edits of one 200 kB file came to 24 MB. `synartesis prune`
+deletes whole sessions and `VACUUM`s. It will not touch one still active, or one
+holding a call waiting on a person, or one whose undo halted on a conflict. A
+pruned session cannot be undone afterwards, which is the whole of the trade.
+Nothing prunes on a timer.
+
+**Durability.** The journal runs `synchronous = NORMAL`. A crash of the process
+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
 

package/dist/{chunk-CACV6R74.js → chunk-DRDKIFD3.js}

@@ -340,7 +340,7 @@ function openDatabase(path) {
     db.pragma("foreign_keys = ON");
     db.pragma("busy_timeout = 5000");
     db.pragma(
-      process.env["SYNARTESIS_SYNC"]?.toLowerCase() === "normal" ? "synchronous = NORMAL" : "synchronous = FULL"
+      process.env["SYNARTESIS_SYNC"]?.toLowerCase() === "full" ? "synchronous = FULL" : "synchronous = NORMAL"
     );
     if (path !== ":memory:") {
       restrictToOwner(path);
@@ -1580,4 +1580,4 @@ export {
   observeState,
   connectStdioUpstream
 };
-//# sourceMappingURL=chunk-CACV6R74.js.map
+//# sourceMappingURL=chunk-DRDKIFD3.js.map

package/dist/cli.js

@@ -27,7 +27,7 @@ import {
   toResolvedRead,
   verifyAgainstServers,
   wasRefused
-} from "./chunk-CACV6R74.js";
+} from "./chunk-DRDKIFD3.js";
 import {
   DriftConflict,
   ManifestError,

package/dist/proxy.js

@@ -19,7 +19,7 @@ import {
   runRead,
   toPayload,
   verifyAgainstServers
-} from "./chunk-CACV6R74.js";
+} from "./chunk-DRDKIFD3.js";
 import {
   SnapshotError,
   UpstreamError,

package/package.json

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