synartesis 0.6.22 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,111 @@
 
 What changed, and why it mattered. Dates are release dates.
 
+## 0.7.0 — 2026-09-16
+
+A pass over everything, after an audit of the desktop app, the core and the
+release. Most of what it found was not broken code but things that stated
+something untrue.
+
+### Fixed
+
+- **Every desktop binary since 0.6.12 carried the wrong version.**
+  electron-builder reads the version from `app/package.json`, which nothing
+  else reads, so it stayed put while the root moved. The nine installers
+  attached to v0.6.23 were all named `0.6.12`, byte-identical in name to the
+  ones on v0.6.12 — two people on different releases could not tell their
+  builds apart. `app-packaging.test.ts` already checked seven agreements
+  between the packaging files; the absence of the eighth is why this ran for
+  eleven releases.
+
+- **A spent approval read as "refused" in `watch` and the console.** `labelFor`
+  was written for exactly this and `list` and `show` were taught to use it;
+  `plainly` was not — and `plainly` is what the two live screens render, so a
+  person was told their own yes had been a no, seconds after giving it.
+
+- **`undo --dry-run --force` printed no plan.** It showed what forcing would
+  write over and returned, so the flag whose whole job is to print the plan
+  printed none. A dry run no longer needs `--yes` either: the two-step ask
+  protects a write, and a preview writes nothing.
+
+- **A `verify:` read was never validated.** `snapshot` and `inverse` are
+  checked against the servers at load; `verify` was not, and it is the one
+  whose failure is silent — the proxy turns it into a soft warning and carries
+  on, so a typo meant that tool had no drift detection at all while both the
+  policy and `check` said it was fine.
+
+- **A failed inverse on the lost-answer path was swallowed whole.** An inverse
+  reading `$result.` cannot be rebuilt when the answer is what went missing,
+  and undo reported "cannot be undone" without saying why — on the path where
+  undo matters most.
+
+- **`--client` with a typo blamed the machine**, reporting "No MCP client
+  config was found on this machine". On `uninstall` it said "Nothing was
+  covered, so nothing was changed", which reads as reassurance.
+
+- **`undo --to` always exited 1.** A floor makes a run `partial` by
+  construction, correctly, and the exit code was read off that — so an undo
+  that did exactly what it was told could not be told from one that halted on
+  somebody's edit.
+
+- **`status` read "when was this server last used" off the newest five hundred
+  actions**, so a server whose last use had scrolled out of that window came
+  back as never used: "covered, nothing through it yet". Asked exactly now,
+  from a covering index — 75ms to 3.5ms on sixty thousand actions.
+
+### Fixed — the desktop window
+
+- **With no policy the window could not be quit.** The branch that drew the
+  no-policy screen returned before the IPC handlers were registered and before
+  the quit handlers were attached; on Windows and Linux that left a process
+  running with no window. Everything after `whenReady` is now one path in
+  `boot.ts`, which imports no Electron — which is also how the key-page
+  allowlist became testable.
+
+- **Two spurious errors before the no-policy screen.** The window asked the
+  engine two questions the moment it mounted, which with no policy came back as
+  "No handler registered" and were drawn as errors. The push is now a pull.
+
+- **`Bridge` was declared twice and neither copy was connected to the
+  preload** — the only one that was true. They had already drifted. The shared
+  one survives, the exposed object is annotated rather than inferred, and both
+  the compiler and a test now catch a future drift.
+
+- **A server that would not start vanished**: no event, no log, nothing in the
+  window, and a briefing that went on announcing it as connected. It now
+  reaches the transcript with the server's own words, and the model is told not
+  to plan around tools that are not there.
+
+### Changed
+
+- `pnpm check` runs build, typecheck, lint and the suite in one command.
+- The release workflow runs that gate before building installers, builds the
+  desktop app in CI, runs the memory demo, and takes its release notes from
+  `CHANGELOG.md` instead of a list of commit subjects.
+- `npm publish` runs the whole gate rather than only a build.
+- `list --json` and `show --json` both carry `actionCount`, so one name means
+  one thing in both. The existing `actions` shape is untouched.
+- The site points at `/releases/latest` rather than a pinned version.
+- The user guide covers `install`, `uninstall`, `status` and `desktop`, and is
+  no longer stamped twenty releases back. `CONTRIBUTING.md` no longer shows a
+  manifest syntax that throws on load, or asks for a C toolchain the project
+  disables.
+
+## 0.6.23 — 2026-09-16
+
+### Docs
+
+- **What to do with a tool that does two things at once.** A call that both
+  writes something recoverable and does something that is not -- saves a file
+  and posts to an API, updates a record and sends the email about it -- takes
+  the class of its least recoverable part, because a rule matches a tool name
+  and gives it one class. The guide now says so, says why the alternative is
+  worse (undo puts the file back, reports `rolled_back`, and says nothing about
+  the request still out there), points at `move_file` as the shipped example of
+  the same shape, and shows the one way out: a `compensable` rule whose inverse
+  neutralises the unrecoverable half. Asked often enough to be worth writing
+  down rather than answering again.
+
 ## 0.6.22 — 2026-09-16
 
 ### Added

package/README.md

@@ -385,11 +385,17 @@ pnpm test
 ```
 
 ```bash
-pnpm typecheck && pnpm lint
+pnpm check
 ```
 
-Every push runs those on Linux and macOS across Node 22 and 24, plus the demo
-and the installer.
+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.
+
+**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
+`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.
 
 ## Licence
 

package/SECURITY.md

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

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

@@ -325,6 +325,20 @@ CREATE INDEX IF NOT EXISTS actions_unresolved ON actions(run_id, server, tool)
 -- ordering it asks for, so the index both filters and sorts.
 CREATE INDEX IF NOT EXISTS actions_writes ON actions(run_id, seq)
   WHERE class <> 'readonly';
+
+-- Covering, like actions_run_status and for the same reason. status asks when
+-- each server was last used; without this the group-by walks the table, and
+-- the table carries the snapshots, so the cost of drawing a connection list
+-- grew with the size of the data those connections had touched rather than
+-- with how many there were. Both columns the query reads are here, so sqlite
+-- never reaches into a row -- the plan says COVERING INDEX, and it is the
+-- covering half that does the work. Measured on sixty thousand actions across
+-- twelve servers with two-kilobyte snapshots: 75ms to 3.5ms.
+--
+-- Added the same way as the ones above and for the same reason: no row
+-- changes, no meaning changes, IF NOT EXISTS makes it idempotent, and an older
+-- build opening the same file afterwards neither notices nor cares.
+CREATE INDEX IF NOT EXISTS actions_seen ON actions(server, ts);
 `;
 
 // src/journal/journal.ts
@@ -336,6 +350,7 @@ var runSchema = z.object({
   ended_at: z.string().nullable(),
   status: z.enum(["active", "complete", "rolled_back", "partial"])
 });
+var seenSchema = z.object({ server: z.string(), ts: z.string() });
 var tallySchema = z.object({
   run_id: z.string(),
   actions: z.number(),
@@ -847,6 +862,33 @@ var SqliteJournal = class {
       return raw === void 0 ? void 0 : toAction(raw);
     });
   }
+  /**
+   * When each server was last used, over everything, not over a window.
+   *
+   * This was a scan of the newest five hundred actions, which answers a
+   * different question: on a busy journal a server whose last use had fallen
+   * out of that window came back as never used at all, and `status` reported
+   * "covered, nothing through it yet" about a server somebody uses daily.
+   * Wrong, and reassuringly so -- it reads as though the connection were
+   * merely new.
+   *
+   * Exact instead, and answered entirely from actions_seen: the query reads
+   * only the two columns that index holds, so it never touches the rows
+   * carrying snapshots.
+   */
+  lastSeenPerServer() {
+    return this.#run("lastSeenPerServer", () => {
+      const rows = this.#db.prepare("SELECT server, MAX(ts) AS ts FROM actions GROUP BY server").all();
+      const seen = /* @__PURE__ */ new Map();
+      for (const row of rows) {
+        const read2 = seenSchema.safeParse(row);
+        if (read2.success) {
+          seen.set(read2.data.server, read2.data.ts);
+        }
+      }
+      return seen;
+    });
+  }
   recentActions(limit) {
     return this.#run(
       "recentActions",
@@ -1272,6 +1314,13 @@ function validate(source, manifest) {
       }
       checkCall(source, [...path, "inverse"], policy.inverse, servers, allowed);
     }
+    if (policy.verify !== void 0) {
+      const allowed = ["$.", "$result."];
+      if (policy.snapshot !== void 0) {
+        allowed.push("$snapshot.");
+      }
+      checkCall(source, [...path, "verify"], policy.verify, servers, allowed);
+    }
   });
 }
 function withGate(policy) {
@@ -1561,7 +1610,7 @@ function describeStanding(entry) {
       return "no claim either way";
   }
 }
-var LIVE_IS_NOT_RECOVERY = "`live` means the policy has met its server, not that undo has been round-tripped against it. Of the policies that ship, filesystem and memory have been; git and github have not.";
+var LIVE_IS_NOT_RECOVERY = "`live` means the policy has met its server, not that undo has been round-tripped against it. Whether it puts anything back is a separate question, and only a test against the real server answers it.";
 function warnUntested(servers) {
   const names = servers.join(", ");
   const these = servers.length === 1 ? "this policy has" : "these policies have";
@@ -1944,4 +1993,4 @@ export {
   observeState,
   connectStdioUpstream
 };
-//# sourceMappingURL=chunk-JLLAK2QC.js.map
+//# sourceMappingURL=chunk-FXSKWMNG.js.map

package/dist/cli.js

@@ -38,7 +38,7 @@ import {
   verifyAgainstServers,
   warnUntested,
   wasRefused
-} from "./chunk-JLLAK2QC.js";
+} from "./chunk-FXSKWMNG.js";
 import {
   DriftConflict,
   ManifestError,
@@ -1076,7 +1076,7 @@ function plainly(action) {
     case "rolling_back":
       return { text: "undoing", needs: false };
     case "denied":
-      return { text: "refused", needs: false };
+      return labelFor(action) === "used" ? { text: "used", needs: false } : { text: "refused", needs: false };
     case "failed":
       return { text: "failed", needs: false };
     case "approved":
@@ -1526,6 +1526,12 @@ var LABELS = {
   cursor: "Cursor",
   codex: "Codex"
 };
+var CLIENT_IDS = Object.keys(LABELS).filter(
+  (name) => name in LABELS
+);
+function isClientId(value) {
+  return CLIENT_IDS.some((known) => known === value);
+}
 function claudeDesktopPath() {
   const home = homedir();
   switch (platform()) {
@@ -1946,14 +1952,7 @@ function applyUninstall(sites, manifestPath) {
 // src/install/connections.ts
 var ACTIVE_WITHIN_MS = 2 * 60 * 1e3;
 function lastSeenByServer(journal) {
-  const seen = /* @__PURE__ */ new Map();
-  for (const action of journal.recentActions(500)) {
-    const known = seen.get(action.server);
-    if (known === void 0 || action.ts > known) {
-      seen.set(action.server, action.ts);
-    }
-  }
-  return seen;
+  return journal.lastSeenPerServer();
 }
 function commandMissing(command) {
   if (command === void 0) {
@@ -2848,7 +2847,8 @@ Most commands end by naming the one thing worth doing next, worked out from
 what is actually in the journal rather than from what was typed. Set
 SYNARTESIS_NO_HINTS to turn that off; --json never carries it.
 
-Exit codes: 0 complete, 1 halted or partial, 2 bad usage or configuration.
+Exit codes: 0 did what was asked, 1 stopped or left something in place,
+            2 bad usage or configuration.
 `;
 var UsageError = class extends Error {
   /**
@@ -2940,6 +2940,20 @@ async function runPin(argv) {
   out("");
   return 0;
 }
+function namedClient(argv) {
+  const typed = flag(argv, "--client");
+  if (typed === void 0) {
+    return void 0;
+  }
+  if (!isClientId(typed)) {
+    const near = didYouMean(typed, CLIENT_IDS);
+    throw new UsageError(
+      `--client ${typed} is not a client this knows${near === void 0 ? "" : `; did you mean ${near}?`}
+It knows: ${CLIENT_IDS.join(", ")}`
+    );
+  }
+  return typed;
+}
 async function runCheck(argv) {
   const path = findManifest(flag(argv, "--manifest"));
   const manifest = loadManifest(path);
@@ -3037,7 +3051,7 @@ async function runCheck(argv) {
 }
 async function runInstall(argv) {
   const manifestPath = findManifest(flag(argv, "--manifest"));
-  const only = flag(argv, "--client");
+  const only = namedClient(argv);
   const dryRun = argv.includes("--dry-run");
   const printOnly = argv.includes("--print");
   const sites = discover(process.cwd()).filter(
@@ -3122,7 +3136,7 @@ async function runInstall(argv) {
 }
 async function runUninstall(argv) {
   const manifestPath = findManifest(flag(argv, "--manifest"));
-  const only = flag(argv, "--client");
+  const only = namedClient(argv);
   const sites = discover(process.cwd()).filter(
     (site) => only === void 0 || site.client === only
   );
@@ -3396,7 +3410,14 @@ function runList(journal, asJson, journalPath) {
   const tally2 = journal.tallyRuns();
   const counted = (id) => tally2.get(id) ?? { actions: 0, unknown: 0, waiting: 0, applied: 0 };
   if (asJson) {
-    out(JSON.stringify(runs.map((run) => ({ ...run, actions: counted(run.id).actions }))));
+    out(
+      JSON.stringify(
+        runs.map((run) => {
+          const actions = counted(run.id).actions;
+          return { ...run, actions, actionCount: actions };
+        })
+      )
+    );
     return 0;
   }
   if (runs.length === 0) {
@@ -3452,6 +3473,9 @@ async function runShow(argv, journal, asJson) {
       JSON.stringify({
         run,
         actions: journal.getActions(runId),
+        // The same name means the same thing in `list --json`, where `actions`
+        // has always been a count and cannot change.
+        actionCount: journal.getActions(runId).length,
         ...inspection === void 0 ? {} : { live: inspection.resources }
       })
     );
@@ -3907,7 +3931,7 @@ function report(result, alreadyForcing = false, as = "") {
       needs: ["manifest", "journal"]
     });
   }
-  return result.status === "rolled_back" ? 0 : 1;
+  return result.halted === void 0 && permanent.length === 0 ? 0 : 1;
 }
 async function withUpstreams(manifestPath, use, only) {
   const manifest = loadManifest(manifestPath);
@@ -4025,6 +4049,8 @@ async function runUndo(argv, journal) {
   if (said && !forcing) {
     process.stderr.write("synartesis: --yes only means anything with --force; ignoring it\n");
   }
+  const dryRun = argv.includes("--dry-run");
+  const forcePlan = forcing && (said || dryRun);
   if (forcing && !said) {
     const over = (await withUpstreams(
       manifestPath,
@@ -4048,25 +4074,30 @@ async function runUndo(argv, journal) {
         }
       }
       out("");
-      out(`  ${style.quiet("nothing has been written. To go ahead and lose that:")}`);
-      out(`  ${style.strong(`${cliCommand()} undo ${runId.slice(0, 8)} --force --yes`)}`);
-      out("");
-      return 1;
+      if (!dryRun) {
+        out(`  ${style.quiet("nothing has been written. To go ahead and lose that:")}`);
+        out(`  ${style.strong(`${cliCommand()} undo ${runId.slice(0, 8)} --force --yes`)}`);
+        out("");
+        return 1;
+      }
     }
   }
   const replan = argv.includes("--replan");
   return report(
     await performUndo(manifestPath, journal, runId, {
-      dryRun: argv.includes("--dry-run"),
+      dryRun,
       ...toSeq === void 0 ? {} : { toSeq },
       replan,
-      ...forcing && said ? { force: true } : {}
+      ...forcePlan ? { force: true } : {}
     }),
     forcing,
     // --to is deliberately absent, and cannot reach here: a floor leaves
     // actions below it alone, which makes the result `partial`, and the hint
     // is only offered on `rolled_back`.
-    `${replan ? " --replan" : ""}${forcing && said ? " --force --yes" : ""}`
+    // forcePlan, not `forcing && said`: on a dry run the command that does
+    // this for real is the forced one, and offering it without --force would
+    // hand back something that halts on the drift the preview just showed.
+    `${replan ? " --replan" : ""}${forcePlan ? " --force --yes" : ""}`
   );
 }
 var KNOWN_COMMANDS = [

package/dist/proxy.js

@@ -25,7 +25,7 @@ import {
   verifyAgainstServers,
   warnUntested,
   withIdempotencyKey
-} from "./chunk-JLLAK2QC.js";
+} from "./chunk-FXSKWMNG.js";
 import {
   SnapshotError,
   UpstreamError,
@@ -399,6 +399,18 @@ function compatible(tool, seen) {
   }
   return { ...tool, outputSchema: withoutDialect(tool["outputSchema"], seen) };
 }
+function recoverInverse(policy, captured, noPriorState) {
+  if (policy.inverse === void 0 || noPriorState) {
+    return {};
+  }
+  try {
+    return { inverse: planInverse(policy.inverse, { ...captured, result: void 0 }) };
+  } catch (error) {
+    return {
+      warning: `and its inverse could not be resolved without that answer: ${describe(error)}`
+    };
+  }
+}
 function createProxyServer(options) {
   const { upstreams, manifest, journal } = options;
   const router = createRouter(upstreams, manifest);
@@ -842,19 +854,19 @@ function createProxyServer(options) {
             } else if (settled === "unknown") {
               journal.markUnknown(pending.actionId, describe(error));
             } else {
-              let recovered;
-              if (policy.inverse !== void 0 && missingPriorState === void 0) {
-                try {
-                  recovered = planInverse(policy.inverse, { args, snapshot, result: void 0 });
-                } catch {
-                  recovered = void 0;
-                }
-              }
+              const recovered = recoverInverse(
+                policy,
+                { args, snapshot },
+                missingPriorState !== void 0
+              );
               journal.markApplied(pending.actionId, {
                 result: void 0,
-                ...recovered === void 0 ? {} : { inverse: recovered },
+                ...recovered.inverse === void 0 ? {} : { inverse: recovered.inverse },
                 ...verify === void 0 ? {} : { verify },
-                warning: `the call applied but its answer never arrived: ${describe(error)}`
+                warning: [
+                  `the call applied but its answer never arrived: ${describe(error)}`,
+                  ...recovered.warning === void 0 ? [] : [recovered.warning]
+                ].join("; ")
               });
             }
           }
@@ -1199,7 +1211,6 @@ async function main() {
     upstreams,
     manifest,
     journal,
-    gateTimeoutMs: argv.gateTimeoutMs,
     logger: log,
     // Absolute, because whoever approves may be in any directory at all.
     approveHint: (actionId) => `${cliCommandFrom(import.meta.url)} approve ${actionId.slice(0, 8)} --journal ${resolve(argv.journal)}`

package/manifests/filesystem.yaml

@@ -88,9 +88,6 @@ tools:
         path: "$.path"
         content: "$snapshot.content"
 
-  # Reversible from its arguments alone: no pre-read could say anything the
-  # arguments do not already. Drift cannot be checked for the same reason, so
-  # undo reports it as unverified.
   # 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

package/manifests/memory.yaml

@@ -42,19 +42,14 @@ tools:
   # undoing by argument would delete a Grace who was there long before the
   # agent ran. The result carries only what was actually created.
   #
-  # $result.entities, not $result: this server answers with both a text block
-  # holding a bare array and a structuredContent object wrapping it, and
-  # structured data wins over re-parsed text. Written against the text block,
-  # the first version of this policy resolved to nothing and undo halted. It is
-  # the same mistake the filesystem policy made, and the reason neither of them
-  # can be trusted until it has met a real server.
-  #
-  # $result is the structured block, not the text one, and here the two
-  # disagree: the text is a bare list of entities while structuredContent wraps
-  # it as {"entities": [...]}. The structured block is the machine-readable
-  # contract, so that is the one a path walks. Writing $result[].name here is
-  # the natural mistake, and it was the first thing this policy got wrong
-  # against the live server.
+  # $result.entities, not $result. $result is the structured block, not the
+  # text one, and here the two disagree: the text is a bare list of entities
+  # while structuredContent wraps it as {"entities": [...]}. The structured
+  # block is the machine-readable contract, so that is the one a path walks.
+  # Writing $result[].name is the natural mistake, and it was the first thing
+  # this policy got wrong against the live server -- the same mistake the
+  # filesystem policy made, and the reason neither can be trusted until it has
+  # met one.
   - match: "memory.create_entities"
     class: compensable
     inverse:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synartesis",
-  "version": "0.6.22",
+  "version": "0.7.0",
   "description": "An undo layer for AI agents.",
   "type": "module",
   "private": false,
@@ -57,7 +57,8 @@
     "app:dist": "pnpm app:build && node app/build/pack.mjs",
     "demo": "tsup --silent && ./demo/filesystem-demo.sh",
     "demo:memory": "tsup --silent && ./demo/memory-demo.sh",
-    "prepublishOnly": "tsup"
+    "check": "pnpm build && pnpm typecheck && pnpm lint && pnpm test",
+    "prepublishOnly": "pnpm check"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",