synartesis 0.8.8 → 0.9.1

package/CHANGELOG.md

@@ -2,6 +2,185 @@
 
 What changed, and why it mattered. Dates are release dates.
 
+## 0.9.1 — 2026-09-24
+
+This release attacks undo instead of describing it. The new tests generate the
+agent sessions rather than script them, kill undo with SIGKILL partway through,
+and race several agents against one approval. They found five bugs that no
+hand-written scenario had reached.
+
+### Fixed
+
+- **An undo that succeeded could be stuck for good.** A server that applies an
+  inverse and then fails before answering (a crashed handler, a gateway timeout)
+  was read as having refused it. The next attempt found the resource already put
+  back, called that drift, and every attempt after that refused on it. Undo now
+  reads the resource when an inverse errors, and counts it as done when the
+  resource is where that inverse puts it.
+- **An undo killed at the wrong moment could block that action for ever.**
+  Claiming an action and recording which process holds it were two separate
+  writes, though the code's own comment said they were one transaction. A kill
+  between them left an action claimed by nobody, which no later undo could tell
+  from one still in progress. They are now one transaction.
+- **An undo killed while compensating stopped on its own success.** The delete
+  that undoes a create went through, and the resumed undo called the record's
+  absence drift. It now recognises it, but only when the owner is certainly
+  gone and the record is certainly gone. An edit a person made instead still
+  stops it.
+- **Running `install` from your home directory covered servers twice.** There,
+  a client's project config and its global one are the same file. It was listed
+  twice, and every server in it was drafted into the policy a second time under
+  another name.
+- **"Covered, nothing through it yet" about a server in daily use.** The connect
+  screen looked up the last use under the client entry's name, not the name the
+  policy gives the server, and those differ when two clients list a server with
+  the same name.
+- **A policy reading a field every object inherits** (`constructor`,
+  `toString`) resolved to nothing when the record lacked it, instead of saying
+  it was absent. The inverse then quietly left that field out of what it
+  restored.
+
+### Faster
+
+- **Servers start together.** Every path that starts more than one server
+  (a proxy serving several, `undo`, `check`, `pin`) waited for each before
+  starting the next. Three servers that take 800 ms each answered after 2.9 s;
+  now it is under 1.6 s, and the order they are reported in is unchanged.
+- **Each server's tools are listed once at start-up**, not three times.
+
+### Tests
+
+- `tests/stress-undo.test.ts`: random sessions with awkward values (unicode,
+  5,000-character strings, `__proto__`, text that looks like a template), undone
+  through injected crashes before and after writes, undone to random steps, and
+  with a person's edit that must survive.
+- `tests/kill-undo.test.ts`: `synartesis undo` killed with SIGKILL the moment a
+  random number of actions have been undone, again and again, with a real server
+  and store.
+- `tests/race-approval.test.ts`: eight separate agent processes retrying one
+  approved email in the same instant. Exactly one is sent.
+- Direct tests for the code only child processes reached before: which clients
+  are covered, the environment an undo starts a server with, and the Linux
+  notifier.
+- `pnpm stress` runs all three at full strength; `pnpm coverage` reports what
+  the suite reaches.
+
+## 0.9.0 — 2026-09-24
+
+0.8.4 to 0.8.8 made Synartesis correct once you were using it. This release is
+about the part before and around that: connecting what you already have without
+breaking it, and being asked less once you have. Several bugs made someone who
+followed the instructions worse off than someone who never installed it. Those
+come first.
+
+### Fixed: wrapping a server no longer breaks it
+
+- **Wrapping a server dropped its API keys.** `install` copied the client
+  entry's `env` onto the proxy's entry, and the proxy then started the real
+  server with almost none of it. Every server now starts through one path,
+  with the environment it was given. Existing installs are fixed without
+  re-running anything.
+- **`undo` could not authenticate, and in one case undid the wrong store.** It
+  started servers with only what the policy declared, so a token held in the
+  client config was missing. For the memory server that was silent: without
+  `MEMORY_FILE_PATH` it opened its default file, sent the inverse there, and
+  reported success. `undo` now reads the environment and working directory from
+  the client entry that wraps the server. Each session records a keyed
+  fingerprint of every declared variable, never the value, and an undo whose
+  variables differ refuses and names them.
+- **One server's missing token was everybody's problem.** `${VAR}` in a policy
+  was expanded for every server when the file was read, so undoing a filesystem
+  session failed unless the GitHub token was exported. It is expanded per
+  server, when that server starts.
+- **A server update took GitHub down.** github-mcp-server 1.12.2 renamed the
+  tools the shipped policy read from, and the proxy refused to start. A rule
+  whose snapshot, inverse or verify tool has gone now falls back to being held,
+  and the proxy starts and says which rules it disabled. `check` still fails
+  hard. `github.yaml` is rewritten for 1.12.
+- **`install` covers what it says.** It reads every Claude Code project, not
+  only the one it was run from (Claude Code's default scope is per project).
+  Running it again after `uninstall` covers the same server again instead of
+  duplicating it and then dropping it. Skip reasons are printed whole, where
+  "Please set SLACK_BOT_TOKEN" used to be cut off. It will not rewrite a Codex
+  table it could not fully read. `installed.json`, which holds the original
+  entries and their tokens, is now owner-only.
+- **Bare `undo` and `show` skip empty sessions.** Most sessions record nothing;
+  bare `undo` refused on the empty one instead of finding the one with work.
+
+### Added: cover more of what people connect
+
+- **Browsers.** Policies for Playwright MCP and Chrome DevTools MCP, written
+  from each server's real tool list. Reads are reads. Every interaction is
+  recorded, arguments included, and not held: nothing a browser does can be
+  undone, and holding every click made both unusable. Running agent-written
+  code and uploading files are still held.
+- **A tool its server marks read-only is read as a read** when no rule mentions
+  it, instead of held. The MCP specification calls annotations untrusted unless
+  they come from a trusted server; the trust relied on is that you chose to
+  connect this one. It only ever loosens a hold on a read. It never applies on a
+  pinned server, `trust_annotations: false` turns it off, and `check` lists
+  every tool let through this way.
+- **Hosted servers.** A server with a token in its headers is reached directly:
+  Streamable HTTP, falling back to SSE only where the server says it does not
+  speak the newer one, with redirects refused. `install` moves the header values
+  into the client entry's `env`, and the policy names the variables. A request
+  refused at the door, such as an expired token, is recorded as never sent. A
+  server that signs in through a browser is covered with `install --remote`,
+  through mcp-remote, which keeps the sign-in itself.
+- **Four more clients:** Gemini CLI, GitHub Copilot CLI, Antigravity, and
+  Devin Desktop (what Windsurf became) plus the older Windsurf path. Every path
+  and variable syntax was checked against the vendor's own documentation.
+- **Read-only policies** for fetch, Brave Search, Exa, Tavily and the AWS
+  documentation server. Each server was started and its tool list read first.
+
+### Added: ask less, tell the person
+
+- **A desktop notification when a call is held**, on macOS and Linux. It names
+  the server and the tool, never the arguments. `synartesis notify --test`
+  checks it reaches you; `SYNARTESIS_NOTIFY=0` turns it off.
+- **`synartesis allow <server.tool>`.** `--for 1h` stops holding that tool until
+  the time runs out, with no restart. `--always` edits the policy in place,
+  keeping its comments, and a tool that cannot be undone stays marked that way
+  (you type its name to confirm). `--stop` holds it again. `A` in `watch` and
+  the console, and a button on the desktop card, approve the call in front of
+  you and allow the tool for an hour.
+- **A person's no reaches the agent.** A retry of a denied call is told who
+  said no, when and why, instead of opening a fresh hold. `approve` on the
+  denied call takes the denial back. Denials live in their own table, so a
+  spent approval, which is also stored as denied, is never reported as a refusal.
+- **Why a call is held.** A tool with no rule says so, rather than "this action
+  cannot be undone".
+
+### Changed
+
+- **The agent is never handed the command to approve its own call.** It used
+  to be in the refusal text and in the instructions every agent receives, and
+  an agent with a shell could run it, recorded under your name. `approve` and
+  `allow` now need a person at a terminal unless given `--unattended`, which is
+  recorded. This stops an agent following instructions or making a mistake. It
+  does not stop a process working to defeat it while running as you, which can
+  write the journal directly.
+- **`show` and `undo` speak the same words as everything else.** No more
+  `reversible applied` or `result rolled_back` at the end of a dry run that
+  wrote nothing. A read-heavy session's reads fold into one line.
+- **`install --print` starts nothing.** It promised to write nothing and then
+  started every server, which meant a download for each npx server and a
+  browser window for each sign-in. `install` also says which server it is
+  starting, instead of going quiet until the last one answers.
+- `check` offers `pin` only once the policy has been used. The desktop window
+  points at `install`, not bare `init`. The `--http` server answers an ended
+  session with 404, as the MCP specification asks.
+- A policy using `{{args.id}}` (loaded, then sent as those characters) or
+  `${args.id}` (failed with no line number) is refused with the line and the
+  spelling that works.
+
+### Docs
+
+- The user guide's only complete policy example did not parse. It does now,
+  and a test loads every policy shown in the README, the guide and the install
+  page. The manual setup snippets give each server its own entry with
+  `--server`, and the Claude Code command has its `--`.
+
 ## 0.8.8 — 2026-09-22
 
 ### Fixed

package/README.md

@@ -102,7 +102,8 @@ Then, from anywhere:
 synartesis install
 ```
 
-That finds what Claude Code, Claude Desktop, Cursor or Codex already list,
+That finds what Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI, Copilot
+CLI, Antigravity or Devin Desktop (Windsurf) 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
@@ -219,12 +220,15 @@ Every tool gets one of four classifications, written down in a manifest:
 | `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** |
+| `irreversible` | Neither | `send_email` | **Suspended until a human approves it**, or recorded without asking where the policy says `gate: never` |
 
 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 check` names them, so you meet that decision
-before your agent does.
+worth avoiding most. The one exception is a tool its own server marks
+read-only: that is read as a read, and `check` lists every tool let through that
+way, so you can see exactly what was trusted. (`trust_annotations: false` on a
+server turns it off, and a pinned server never gets it.) `synartesis check`
+names the rest, 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
@@ -235,6 +239,65 @@ than putting half of it back and calling that success.
 
 ---
 
+## Being asked less, and told when it matters
+
+**You hear about a held call when it happens.** On macOS and Linux a desktop
+notification names the server and the tool, never the arguments, since they can
+carry secrets and notification history is kept. `synartesis notify --test`
+checks it reaches you; `SYNARTESIS_NOTIFY=0` turns it off. Windows has none yet,
+and `watch` shows every held call on every platform.
+
+**Stop being asked, for a while or for good.**
+
+```bash
+synartesis allow crm.send_email --for 1h      # a row in the journal; next call on
+synartesis allow crm.send_email --always      # edits the policy; next client restart
+synartesis allow crm.send_email --stop        # held again from the next call
+synartesis allow                              # what is let through right now
+```
+
+`--for` goes up to a day and runs out by itself. `--always` changes only that
+tool's gate, in place, keeping every comment in the file. A tool that cannot be
+undone stays marked that way everywhere it shows up: it is recorded, just no
+longer held. For those you type the tool's name to confirm. In `watch` and the
+console, `A` approves the call in front of you and stops asking about that tool
+for an hour. The desktop card has the same button.
+
+**A no reaches the agent.** When you deny a call and the agent tries the same
+call again, it is told who said no, when, and why. It does not see a fresh
+"waiting for approval". `approve` on the denied call takes the denial back.
+
+**The agent is never handed the way to approve itself.** Nothing it reads
+contains an `approve` or `allow` command, and both refuse to run without a
+person at a terminal unless given `--unattended`, which is recorded as such.
+
+---
+
+## Hosted servers and browsers
+
+**Hosted servers.** A server your client reaches at a `url` with a token in its
+headers is covered directly. `install` moves the header values into the
+client entry's `env`, where the client already keeps secrets, and the policy
+names the variables rather than holding the token. The proxy speaks Streamable
+HTTP, falls back to SSE only where the server says it does not speak the newer
+one, and refuses redirects. A request the server refuses at the door (an
+expired token, say) is recorded as never sent, not as an outcome nobody knows.
+A server that signs you in through a browser instead is covered with
+`install --remote`, through [mcp-remote](https://www.npmjs.com/package/mcp-remote),
+which does the sign-in and keeps the token itself.
+
+**Browsers.** Nothing a browser does can be undone, and holding every click
+made Playwright and Chrome DevTools unusable behind this. Their shipped policies
+read reads as reads and record every interaction, arguments included, without
+holding it. Running code the agent wrote, and uploading files from your disk,
+are still held.
+
+**Policies that ship:** filesystem, memory, git, github, Playwright, Chrome
+DevTools, and a read-only set for fetch, Brave Search, Exa, Tavily and the AWS
+documentation server. Each was written from the server's real tool list.
+
+---
+
 ## Writing a policy for your own server
 
 Four servers ship with a policy. For anything else — a database, a ticketing
@@ -407,6 +470,7 @@ get it if it is not installed.
 |---|---|
 | `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 |
+| `install --remote` | Also cover hosted servers that sign in through a browser, via mcp-remote |
 | `init <server> -- <cmd>` | Introspect a server and draft a manifest |
 | `check` | Load a manifest and verify it against the servers it names |
 | `pin` | Print the `pins:` block for the servers you have now |
@@ -415,6 +479,8 @@ get it if it is not installed.
 | `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 |
+| `allow <server.tool> --for 1h \| --always \| --stop` | Stop being asked about one tool, for a while or for good |
+| `notify --test` | Send one notification, to see whether they reach you |
 | `resolve <id> --applied\|--failed` | Settle a call whose outcome nothing established |
 | `undo <id>` | Reverse a session, newest action first |
 | `undo <id> --dry-run` | Plan it and change nothing |
@@ -515,6 +581,14 @@ 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.
 
+**What needing a terminal protects against.** `approve` and `allow` refuse to
+run without a person at a terminal, and nothing an agent reads names them. That
+stops an agent following its instructions, or making a mistake, into approving
+its own calls. It does not stop a process working to defeat it while running as
+you: anything with your permissions can write the journal directly. For a
+boundary the agent cannot cross, deny it those commands in its own permission
+settings.
+
 **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
@@ -535,6 +609,18 @@ pnpm check
 Every push runs that on Linux and macOS across Node 22 and 24, plus both demos,
 the installer, and a build of the desktop app.
 
+```bash
+pnpm stress
+```
+
+The same three attacks `check` runs lightly, at full strength: 500 random agent
+sessions, each undone and checked byte for byte against where it started (also
+undone to a random step, and with a person's edit made afterwards that must
+survive); `synartesis undo` killed with SIGKILL at random points 25 times over
+and run again; and eight agents racing one approval, ten times, which must send
+exactly one email. A failure names its seed, and `SYNARTESIS_STRESS_SEED`
+replays it. `pnpm coverage` reports what the suite reaches.
+
 **Windows is built and not tested.** The release attaches a Windows installer,
 and no CI job compiles or exercises it — the test matrix is Linux and macOS. It
 is expected to work, the code has no platform-specific paths outside