synartesis 0.6.12 → 0.6.15

package/CHANGELOG.md

@@ -2,6 +2,314 @@
 
 What changed, and why it mattered. Dates are release dates.
 
+## 0.6.15 — 2026-09-15
+
+One gap, named by a stranger on Reddit and real.
+
+### Security
+
+- **A retry of a call whose outcome nobody could establish is now held for a
+  person.** The tri-state was already there -- a write that times out is not
+  called `failed`, the resource is re-read to see which way it went, and what
+  cannot be settled is left `pending`, which undo refuses to step over. What
+  was missing was the other half: nothing stopped the agent from simply making
+  the call again.
+
+  The idempotency key cannot close this. It is `runId:seq`, so a retry is a new
+  row under a different key and no upstream can tell the two attempts were one
+  intention -- checked against the real proxy, which records `seq=1 key=…:1`
+  and `seq=2 key=…:2`. A comment beside the forward call claimed otherwise and
+  has been corrected.
+
+  So the person who can go and look is asked before a second side effect
+  exists. It reuses the gate rather than inventing a second mechanism: the call
+  appears in `synartesis gates` with a reason that says what happened, rather
+  than the generic policy text.
+
+  Three things it deliberately does not do. It never holds a **read** -- a read
+  that timed out is left `pending` like anything else, but reading twice
+  changes nothing, and an agent may always look freely. It holds only the
+  **identical** call, matched on server, tool and arguments: the uncertainty is
+  about one call, not about the tool. And approving the retry **does not
+  resolve the first attempt** -- that row stays `pending` and undo still stops
+  on it, because saying yes to going forward is not a claim about what already
+  happened.
+
+### Performance
+
+- `findPending` runs on the way in to every write, and left to choose sqlite
+  walked every action in the run -- rows that carry the snapshots -- to find
+  the handful that are pending. A partial index over exactly those rows, named
+  explicitly, on a single run of twenty thousand actions with two-kilobyte
+  snapshots: **24ms a call to 0.004ms**.
+
+## 0.6.14 — 2026-09-15 (tagged, never published)
+
+The terminal now says what to do next, and the argument parser stopped
+disagreeing with itself.
+
+### Added
+
+- **Most commands end by naming the one thing worth doing next**, with the
+  session id already filled in:
+
+  ```
+  fs.create_directory is held, and the agent is waiting on you:  synartesis approve f0c9935d
+  ```
+
+  It is worked out from the journal rather than from what was typed, so it
+  changes as the state does. A call held for approval outranks everything else
+  -- that is an agent stopped mid-task waiting on a person who may not know it
+  is waiting. Below that: the session that changed something, what is not
+  pinned, and `watch`. There is at most one, there is none when nothing
+  applies, and `--json` never carries it. `SYNARTESIS_NO_HINTS` turns it off.
+
+  The session it names is not simply the newest one. A client that connects
+  and reads opens a session like any other, so "the last thing that happened"
+  is regularly a session in which nothing happened; a session that only read,
+  or was already undone, or was held and never ran, is never offered for undo.
+
+- **A mistyped command gets the word that was meant.** `synartesis lst` used to
+  answer with forty lines of help, thirty-nine of them about something the
+  person was not doing. It now says `did you mean list?` and lists five
+  commands. Flags too: `--jounral`, `--dryrun`, `--forse` all resolve.
+
+- **A flag that belongs to `proxy` is named as such.** `--http`, `--token`,
+  `--server` and `--log-level` are in the help page, and answering one of them
+  with "unknown flag" sent people hunting through that page for a flag already
+  in it.
+
+### Fixed
+
+- **A wrapped server's own flags were read as ours.** `synartesis init db --
+  some-server --manifest audit.yaml` handed `--manifest` to the server
+  correctly and *also* took it, writing the policy to a path nobody asked for
+  -- on a machine where that path is real, one they already had. `positional`
+  and the unknown-flag check had always stopped at the bare `--`; the flag
+  reader had not.
+
+- **The value of a flag was read as a flag.** `deny --reason "-see ticket 42"`
+  answered `unknown flag -see ticket 42`, and `prune --older-than -5` answered
+  `unknown flag -5` instead of the message that knows what `--older-than` is
+  for. Three separate lists had to agree about which flags take a value and
+  did not; there is one now, and a test holds it against the help page.
+
+- **`undo --to 0` announced the session before refusing.** It printed "no
+  session named, so the most recent: a42bf93a" and only then rejected the
+  flag, which reads as though that session had been acted on.
+
+- **A hint that could not be pasted.** `list --journal ./bench.db` named a
+  session, and the `show` it offered read the *default* journal and answered
+  "no run matches". Hints now carry `--journal` and `--manifest` when those
+  were not the obvious ones, and `undo --replan --dry-run` offers a command
+  that still replans.
+
+- **Guessing at a typo was too eager.** A ceiling of half the word answered
+  `--server` with `--live` and `--token` with `--to`, neither of which anybody
+  meant. Two edits at most now, never for a word under three characters, and a
+  swapped pair counts as the one mistake it feels like -- which is what keeps
+  `shwo`, `pruen` and `--jounral` reachable at that ceiling.
+
+- **Colour was decided for both streams from stdout**, so `synartesis nonsense
+  2> errors.log` in a terminal wrote escape sequences into the file.
+
+### Performance
+
+- **`newestUndoable` runs on every `list`** and could only be answered by
+  reading the action rows, which carry the snapshots -- so the cost of one
+  screen of sessions grew with the size of the data rather than the number of
+  sessions. A partial index over exactly the rows it wants fixes that, but only
+  when named: left to choose, sqlite takes `actions_gated` and reads the rows
+  anyway. Measured on a 246MB journal: **56ms to 0.01ms**.
+
+## 0.6.13 — 2026-09-14
+
+Four things, all of them from one comment by a stranger on Reddit who had
+clearly built something like this before. Every one was real, and none of them
+would have announced itself.
+
+### Security
+
+- **A server that would not start said nothing useful about why, and could
+  hang the proxy outright.** Two faults in the same few lines, found by hitting
+  the first one in real use.
+
+  What it printed was `code: 'MODULE_NOT_FOUND', requireStack: [], },
+  Node.js v22.16.0` -- the last four lines of node's output, which are the four
+  least informative. `Error: Cannot find module '/path/to/thing'` sits in the
+  middle and was thrown away, so the message named neither the file nor
+  anything to act on. A line that states a fault now leads, stack frames are
+  dropped, and the tail is only the fallback when nothing states one.
+
+  The second was worse and was found while testing the first: nothing read the
+  server's stderr until after the connection failed. A pipe nobody reads fills
+  at around 64kB and blocks the writer, so a server that said more than that
+  before dying never exited, the connect never rejected, and `check` sat there
+  for ever with no output at all. Measured against a server writing 2.4MB to
+  stderr: **killed at 30 seconds, against 0.8 seconds and the right error**.
+  Stderr is now read as it arrives, capped so a logging loop cannot make the
+  proxy the thing that runs out of memory.
+
+- **The one remaining advisory is gone.** `esbuild` reached `pnpm audit`
+  through vite, in the renderer build only -- never in anything published, and
+  `--prod` was already clean. Pinned anyway, the same way as 0.6.12's three:
+  a low advisory nobody can reach is still a line of output that trains you to
+  ignore the tool.
+
+- **A server upgrade could silently invalidate the policy written for it.** A
+  policy is a claim about what a tool does, anchored to the tool's name -- and
+  a name is a weak anchor. A server can keep `write_file` and change what it
+  takes. The policy still says reversible, the snapshot still reads a field
+  that has moved, and the before-image captured no longer matches the write.
+  Nothing failed. The undo was produced later, on request, confidently, and was
+  wrong, which is worse than having no undo because somebody acted on it.
+
+  Startup already checked that the tools a policy names exist. It did not check
+  that they still have the shape the policy was written for.
+
+  A manifest may now pin that shape:
+
+  ```yaml
+  pins:
+    fs:
+      write_file: "sha256:ce17c85e8a58835..."
+  ```
+
+  `synartesis pin` prints the block for the servers you actually have. With it
+  in place, a tool whose shape has moved stops the proxy at startup and names
+  both fingerprints, instead of being quietly trusted.
+
+  It prints rather than rewriting the manifest: pinning is a person vouching
+  for what a tool does today, and a command that edited the policy for them
+  would let that happen with nobody reading it.
+
+  Pinning is per server and all-or-nothing. No pins means no checking, so every
+  manifest written before this keeps working. Any pins means that server is
+  checked in full -- a half-pinned server is the worst of both, because it
+  reads as protected and is not. Tools no policy matches need no pin; they are
+  already fail-closed as irreversible and gated.
+
+### Fixed
+
+- **Forward calls carried no idempotency key.** The key was minted for every
+  action and stored, and it was presented on the inverse -- but not on the
+  call going out. So a write that timed out in flight left the agent free to
+  retry, with nothing telling the server that the retry was the same intention.
+  Two side effects would sit behind one journal row, and undo would reverse one
+  of them and report success.
+
+  The key now rides out with the forward call as well, merged into `_meta`
+  rather than replacing it, so a client's own `progressToken` survives. It
+  remains advisory -- a server that ignores it gives no protection, which is
+  why the journal's state transitions are still the real guard.
+
+- **A compensable action could be undone over somebody's work, silently.** An
+  action whose undo is a compensating call -- a create offset by a delete --
+  has no before-image, because the thing did not exist before the call. So
+  there was nothing for undo to compare against: it compensated regardless and
+  marked the step `[unverified]`.
+
+  A policy may now declare a `verify` read, resolved *after* the call so it can
+  name a resource the call itself created:
+
+  ```yaml
+  verify:
+    tool: "memory.open_nodes"
+    args: { names: "$result.entities[].name" }
+  ```
+
+  Undo then halts on drift the way it does everywhere else. Measured against
+  the real `@modelcontextprotocol/server-memory`: an agent creates an entity, a
+  person adds an observation to it by hand, and undo is asked for. Before, it
+  deleted the entity, took the hand-written observation with it, and reported
+  `rolled_back`. Now it halts, prints the added line, and writes nothing.
+
+  It is consulted only where no read exists already, so it can never displace a
+  working pre-read with a differently shaped one -- which would leave the
+  post-state and the snapshot describing different things and make every later
+  comparison meaningless.
+
+  `memory.create_entities` gets one. Deleting an entity takes its observations
+  and relations with it, which is exactly the case worth refusing.
+
+- **Nothing said which policies had actually been run against a real server.**
+  Three of the four that ship were written against the live server; `github`
+  never has been, and its own header has said so in plain words since it was
+  written. Nothing in the code read that header. `check` did not mention it,
+  `install` adopted the policy without a word, and a held GitHub call looked
+  exactly as confident as a held filesystem one.
+
+  A server may now state it, and the four that ship do:
+
+  ```yaml
+  servers:
+    gh:
+      command: github-mcp-server
+      provenance: documented   # or: live
+  ```
+
+  Surfaced by `check`, by the proxy at every start -- before it connects, since
+  the untried adapter is the one whose server is least likely to be installed
+  -- and by `install` at the moment the policy is adopted. `init` writes the
+  claim into the manifest it generates, or the warning would go quiet exactly
+  when the policy starts being used.
+
+  Absent means no claim either way, which is right for a policy somebody wrote
+  themselves. All three states are printed: if silence meant "fine", an
+  ungraded policy and a known-untested one would look identical from here.
+
+- **A call somebody approved was reported as one they had refused.** When an
+  agent retries a held call, the approval moves onto the row that actually
+  runs and the original is retired -- stored as `denied`, with an error saying
+  where its approval went. `labelFor` existed to keep that out of the UI, and
+  three readers did not use it. `show` printed "denied by <name>" beside a call
+  that person had just approved and which had gone through; its footer counted
+  the row as a refusal; and `show --live` called it "never applied (denied)".
+  All three now go through `labelFor`, and the live view says what actually
+  happened: "its approval moved to the call that ran".
+
+- **Arguments are summarised for a terminal again.** A value with a newline in
+  it was printed verbatim, so writing two lines to a file broke the timeline
+  and left the second at column zero. A value over 48 characters was reduced to
+  a byte count -- which for a path is the one summary that answers nothing, so
+  every row of a filesystem session read `path 120 B` and named no file.
+  Values are flattened to one line, a long path keeps its end, and long prose
+  keeps its size, because the tail of a file tells you nothing.
+
+  The undo plan used raw truncated json for the same job and cut off mid-path;
+  it uses the same summary now, so a step reads
+  `would call fs.write_file path …/work/ledger.csv  content north,412800`.
+
+- **`synartesis close` treated a tidy journal as a usage error.** Nothing left
+  open is the ordinary state and the thing somebody runs the command to check.
+  It answered with exit 2 and forty lines of unrelated help. It now says
+  "nothing is open" and succeeds.
+
+  Separately, "there is no run to act on" and "no run matches <id>" stopped
+  reciting every command. They are facts about the journal rather than about
+  what was typed, and the command list buried the one sentence that mattered.
+  A mistyped command still gets the full list.
+
+- **`-v`, `version` and `help` answer.** `--version` worked and `synartesis
+  version` said "unknown command", which is a riddle rather than an answer.
+
+- **Listing sessions read every action of every run.** It needs a count and
+  three status tallies per run, and it was getting them by materialising every
+  row -- snapshots, results and inverses included, which is the bulk of the
+  table. So the cost of listing sessions grew with the size of the data those
+  sessions had touched rather than with how many there were. It is one grouped
+  query now, over a covering index. Measured on forty runs of five hundred
+  actions with two-kilobyte snapshots, a hundred-megabyte journal: **76ms to
+  2ms**.
+
+  The index is added the same way as the two in 0.6.12 and for the same reason:
+  no row changes, no meaning changes, and an older build opening the same file
+  neither notices nor cares.
+
+- `synartesis check` now says whether anything is pinned, either way. Silence
+  when nothing was would have left the safer state and the unchecked one
+  looking identical.
+
 ## 0.6.12 — 2026-09-13
 
 ### Security

package/README.md

@@ -179,6 +179,103 @@ 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
+not the same kind of claim, and the difference only shows up at the moment
+somebody needs undo to work. So a policy can say which it is:
+
+```yaml
+servers:
+  gh:
+    command: github-mcp-server
+    provenance: documented   # or: live
+```
+
+Of the four that ship, three say `live` — they were written against the real
+server and corrected where it disagreed with its own docs. **`github` says
+`documented`**: it has never been run against a real account, and its own header
+has always said so. Now `check` says it, the proxy says it at every start, and
+`install` says it at the moment the policy is adopted — rather than leaving it in
+a file for you to find afterwards.
+
+Absent means no claim either way, which is the right default for a policy you
+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
+before putting it back, undo reads the world again and refuses if it has moved.
+
+A compensable action has no such read. `create_entities` makes something that
+did not exist a moment earlier, so there is nothing to capture — it has a
+compensating action instead, a delete that offsets the create. Which means undo
+had nothing to compare against and compensated regardless. If you had added to
+that record in the meantime, the delete took your work with it and the run
+reported success.
+
+A policy can now declare a read used only for that check:
+
+```yaml
+- match: "memory.create_entities"
+  class: compensable
+  inverse:
+    tool: "memory.delete_entities"
+    args: { entityNames: "$result.entities[].name" }
+  verify:
+    tool: "memory.open_nodes"
+    args: { names: "$result.entities[].name" }
+```
+
+It is resolved *after* the call, so `$result` is available and it can name a
+resource the call itself created. Undo then halts on drift the same way it does
+everywhere else, and shows you the diff.
+
+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
+anchor that claim. A server upgrade can keep `write_file` and add an argument to
+it. The policy still says reversible, the snapshot still reads a field that has
+moved, and the before-image captured no longer matches the write. Nothing fails.
+The undo is produced on request, confidently, and is wrong — which is worse than
+having no undo, because somebody acted on it.
+
+So you can pin the shape a tool had when you wrote its policy:
+
+```bash
+synartesis pin
+```
+
+It prints a block. Paste it into the manifest:
+
+```yaml
+pins:
+  fs:
+    write_file: "sha256:ce17c85e8a5883552a11555f9b893de497fadab965a5c7935c0cb8f3c55b91d6"
+    edit_file: "sha256:88459ef670b139a12a3e0335ae0a4584dd892f60f45f565b545e1004d7565dd5"
+```
+
+From then on, a tool whose shape has moved stops the proxy at startup and names
+both fingerprints, instead of quietly serving the old policy. Re-run `pin` when
+you have looked at what changed and decided the policy still holds.
+
+It prints rather than writes on purpose: pinning is you vouching for what a tool
+does today, and a command that silently rewrote your policy would let that happen
+without anyone reading it.
+
+Pinning is per server and all-or-nothing. A server with no pins is not checked,
+so every manifest written before this existed keeps working. A server with any
+pins is checked in full — a half-pinned server is the worst of both, because it
+reads as protected and is not. Tools that no policy matches need no pin: they are
+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
@@ -190,6 +287,7 @@ get it if it is not installed.
 | `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 |
 | `check` | Load a manifest and verify it against the servers it names |
+| `pin` | Print the `pins:` block for the servers you have now |
 | `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 |
@@ -218,8 +316,11 @@ cannot start a process:** see the [user guide](docs/synartesis-user-guide.md).
 
 - **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]`.
+- **Compensable actions can only be checked for drift if their policy declares a
+  `verify` read.** They have no pre-read — the thing they made did not exist
+  before the call — so without one, undo compensates them and marks them
+  `[unverified]`. With one, the resource is read back after the write and undo
+  halts rather than compensating over somebody else's edit.
 - **Undo halts on uncertainty, and steps over the merely permanent.** Drift, an
   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