synartesis 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -2,6 +2,117 @@
 
 What changed, and why it mattered. Dates are release dates.
 
+## 0.9.2 — 2026-09-24
+
+For someone who has never used a terminal. Every screen was walked through as a
+new user would meet it, in a real terminal, from a fresh machine. Each place
+they would have got stuck is fixed.
+
+### Added
+
+- **`synartesis clean`**: one command, no questions to answer first. It clears
+  every finished session with nothing left to undo, and closes sessions left
+  open by an app that has since exited. It keeps anything you could still undo,
+  anything waiting for you, and anything whose outcome is unknown. Your
+  connected apps and your policy are not touched. It shows what it will do and
+  asks once. On a journal three weeks old it cleared 119 of 126 sessions.
+  `list` suggests it once there is clutter worth clearing.
+- Sessions now record which process opened them, so one left open by an app
+  that crashed or was force-quit can be told apart from one still in use.
+
+### Fixed
+
+- **The first screen was a dead end.** `synartesis` on a fresh machine said
+  "point your client at it" and accepted no keys. It now opens on the AI apps
+  found and their tools: `a` covers all of them, `enter` covers one. When the
+  first session arrives it switches to the sessions by itself.
+- **`watch` ignored keys.** With nothing waiting it showed no keys at all, not
+  even how to quit, and silently swallowed every key pressed. It always shows
+  its keys now, says so when there is nothing to approve yet, and answers a key
+  that does nothing instead of ignoring it. The console does the same.
+- **Opening `synartesis` because of a notification landed on the wrong
+  screen.** Approving was a screen away, behind a key labelled "held", so `a`
+  did nothing. It opens on the waiting call now, shows why it was held, and
+  flags new ones from any other screen.
+- **The notification said to type an approve command** with an id and an
+  absolute path, cut off before its end. It now says to open a terminal and run
+  `synartesis`.
+- After covering apps from the screen, it names which apps to quit and reopen,
+  and says why any server was not covered. It used to say "see the reasons
+  above" on a screen with nothing above.
+- The proxy wrote a routine schema note into the client's log as a warning, once
+  per tool on every start (fourteen for the filesystem server). It is debug
+  level now.
+
+### Docs
+
+- The README's Install section is three steps for somebody who has never used a
+  terminal, then what to do when something needs your OK, how to undo, how to
+  clean up, and how to take it all out.
+
+## 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

package/README.md

@@ -92,23 +92,48 @@ and `--replan`, or `--force` to overwrite deliberately.
 ---
 ## Install
 
-```bash
-npm install -g synartesis
-```
-
-Then, from anywhere:
-
-```bash
-synartesis install
-```
-
-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
-config is copied aside first, `synartesis uninstall` puts it back, and
-`synartesis status` says what is covered.
+**Three steps, if you have never used a terminal.** Open the Terminal app
+(on a Mac: press ⌘ Space, type *Terminal*, press Return), then:
+
+1. If `npm --version` says *command not found*, install Node.js from
+   [nodejs.org](https://nodejs.org) first (the LTS button), and open a new
+   Terminal window.
+2. Install Synartesis:
+
+   ```bash
+   npm install -g synartesis
+   ```
+
+3. Start it:
+
+   ```bash
+   synartesis
+   ```
+
+   It lists the AI apps on your computer and the tools they use. Press **a** to
+   cover all of them, then **quit and reopen** those apps (it names them).
+
+That is the whole setup. From then on:
+
+- **Something needs your OK.** A notification says a call is waiting. Open
+  Terminal, type `synartesis`: it opens on that call. **a** approves, **d**
+  denies, **A** approves and stops asking about that tool for an hour.
+- **Undo what an agent did.** Type `synartesis`, press **r** if it is showing
+  waiting calls, move to the session with the arrow keys, press **u**, then
+  **y**. Press **p** first to see what it would do without changing anything.
+- **Too many old sessions.** `synartesis clean` clears the finished ones and
+  keeps anything you could still undo or still need to decide.
+- **Take it all back out.** `synartesis uninstall` restores every app's
+  settings exactly as they were.
+
+The same thing without the screen: `synartesis install`. It 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 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, so **no tool is renamed** —
 the agent sees exactly the names it saw before. **Your agent needs nothing
@@ -487,6 +512,7 @@ get it if it is not installed.
 | `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 |
+| `clean` | Clear finished sessions; keep anything you could undo or still need to decide |
 | `prune` | Delete sessions older than 30 days and reclaim the space |
 | `close [id]` | End a session a killed proxy left open |
 
@@ -609,6 +635,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

package/dist/{chunk-AEEKBR5D.js → chunk-MTPUG26S.js}

@@ -31,10 +31,10 @@ function shown(name) {
 function unmarked(text) {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
-function words(notice) {
+function words(notice, open) {
   return {
     title: "Synartesis: a call is waiting for you",
-    body: `${shown(notice.server)}.${shown(notice.tool)} -- ${notice.approve}`
+    body: `${shown(notice.server)}.${shown(notice.tool)} -- open a terminal and run: ${open ?? notice.approve}`
   };
 }
 var KILL_AFTER_MS = 5e3;
@@ -51,14 +51,13 @@ function launch(command, args) {
   } catch {
   }
 }
-function desktopNotifier(env = process.env) {
+function desktopNotifier(env = process.env, os = platform(), open) {
   if (env["SYNARTESIS_NOTIFY"] === "0") {
     return SILENT;
   }
-  const os = platform();
   if (os === "darwin") {
     return (notice) => {
-      const { title, body } = words(notice);
+      const { title, body } = words(notice, open);
       launch("osascript", [
         "-e",
         "on run argv",
@@ -74,7 +73,7 @@ function desktopNotifier(env = process.env) {
   }
   if (os === "linux") {
     return (notice) => {
-      const { title, body } = words(notice);
+      const { title, body } = words(notice, open);
       launch("notify-send", ["--app-name=Synartesis", "--", title, unmarked(body)]);
     };
   }
@@ -440,6 +439,19 @@ CREATE TABLE IF NOT EXISTS allows (
 );
 CREATE INDEX IF NOT EXISTS allows_current ON allows(server, tool, until);
 
+-- Which process opened each session, so a session left open by an app that
+-- has since exited can be told from one still in use. Without it, closing an
+-- abandoned session was a person's guess (synartesis close), and every
+-- session a crashed or force-quit app left behind stayed "still open" in the
+-- list for ever. host and pid for the reason leases have both.
+--
+-- Not a schema version bump, for the reason the tables above are not.
+CREATE TABLE IF NOT EXISTS run_owners (
+  run_id  TEXT PRIMARY KEY REFERENCES runs(id),
+  host    TEXT NOT NULL,
+  pid     INTEGER NOT NULL
+);
+
 CREATE INDEX IF NOT EXISTS actions_by_run ON actions(run_id, seq);
 
 -- Deliberately not a schema version bump. Adding an index changes no row and
@@ -753,7 +765,10 @@ var SqliteJournal = class {
   beginRun(label) {
     const id = crypto.randomUUID();
     this.#run("beginRun", () => {
-      this.#db.prepare("INSERT INTO runs (id, label, started_at, status) VALUES (?, ?, ?, 'active')").run(id, label ?? null, (/* @__PURE__ */ new Date()).toISOString());
+      this.#db.transaction(() => {
+        this.#db.prepare("INSERT INTO runs (id, label, started_at, status) VALUES (?, ?, ?, 'active')").run(id, label ?? null, (/* @__PURE__ */ new Date()).toISOString());
+        this.#db.prepare("INSERT INTO run_owners (run_id, host, pid) VALUES (?, ?, ?)").run(id, hostname(), process.pid);
+      })();
     });
     return id;
   }
@@ -901,7 +916,7 @@ var SqliteJournal = class {
    * resource is contested.
    */
   markRollingBack(actionId, from = ["applied"]) {
-    return this.#run("markRollingBack", () => {
+    return this.#run("markRollingBack", () => this.#db.transaction(() => {
       const slots = from.map(() => "?").join(",");
       const result = this.#db.prepare(
         `UPDATE actions SET status = 'rolling_back' WHERE id = ? AND status IN (${slots})`
@@ -915,7 +930,7 @@ var SqliteJournal = class {
                pid = excluded.pid, claimed_at = excluded.claimed_at`
       ).run(actionId, hostname(), process.pid, (/* @__PURE__ */ new Date()).toISOString());
       return true;
-    });
+    }).immediate());
   }
   leaseFor(actionId) {
     return this.#run("leaseFor", () => {
@@ -1231,6 +1246,64 @@ var SqliteJournal = class {
   close() {
     this.#db.close();
   }
+  cleanable(idleBefore) {
+    return this.#run("cleanable", () => {
+      const here = hostname();
+      const open = z.array(
+        z.object({
+          id: z.string(),
+          host: z.string().nullable(),
+          pid: z.number().nullable(),
+          last: z.string()
+        })
+      ).parse(
+        this.#db.prepare(
+          `SELECT r.id, o.host, o.pid,
+                      COALESCE((SELECT MAX(a.ts) FROM actions a WHERE a.run_id = r.id), r.started_at) AS last
+                 FROM runs r LEFT JOIN run_owners o ON o.run_id = r.id
+                WHERE r.status = 'active'`
+        ).all()
+      );
+      const abandoned = open.filter(
+        (run) => run.pid === null ? run.last < idleBefore : (
+          // Only a process on this machine can be asked about; one opened
+          // elsewhere on a shared journal is left alone.
+          run.host === here && !running(run.pid)
+        )
+      ).map((run) => run.id);
+      const closing = new Set(abandoned);
+      const finished = z.array(
+        z.object({
+          id: z.string(),
+          label: z.string().nullable(),
+          status: z.enum(["active", "complete", "rolled_back", "partial"]),
+          at: z.string(),
+          actions: z.number()
+        })
+      ).parse(
+        this.#db.prepare(
+          `SELECT r.id, r.label, r.status, COALESCE(r.ended_at, r.started_at) AS at,
+                      (SELECT COUNT(*) FROM actions a WHERE a.run_id = r.id) AS actions
+                 FROM runs r
+                WHERE NOT EXISTS (
+                        SELECT 1 FROM actions a
+                         WHERE a.run_id = r.id
+                           AND a.status IN ('pending','gated','approved','rolling_back','unrecoverable'))
+                  AND NOT EXISTS (
+                        SELECT 1 FROM actions a
+                         WHERE a.run_id = r.id AND a.status = 'applied' AND a.inverse_json IS NOT NULL)
+                ORDER BY at, r.rowid`
+        ).all()
+      ).filter((run) => run.status !== "active" || closing.has(run.id)).map((run) => ({
+        id: run.id,
+        label: run.label ?? void 0,
+        at: run.at,
+        status: run.status === "active" ? "complete" : run.status,
+        actions: run.actions
+      }));
+      return { abandoned, finished };
+    });
+  }
   prunableRuns(before) {
     return this.#run(
       "prunableRuns",
@@ -1286,7 +1359,9 @@ var SqliteJournal = class {
         const dropDenials = this.#db.prepare(
           "DELETE FROM denials WHERE action_id IN (SELECT id FROM actions WHERE run_id = ?)"
         );
+        const dropOwner = this.#db.prepare("DELETE FROM run_owners WHERE run_id = ?");
         for (const id of ids) {
+          dropOwner.run(id);
           dropServers.run(id);
           dropLeases.run(id);
           dropDenials.run(id);
@@ -1530,7 +1605,7 @@ function walk(current, parts, at, reference) {
       return walk(current[segment.index], parts, at + 1, reference);
     }
     case "key": {
-      if (typeof current !== "object" || !(segment.key in current)) {
+      if (typeof current !== "object" || !Object.hasOwn(current, segment.key)) {
         throw new ManifestError(`${reference} is unresolvable: ${segment.key} is absent`);
       }
       const next = Object.getOwnPropertyDescriptor(current, segment.key)?.value;
@@ -2072,6 +2147,11 @@ function explainPins(server, faults) {
 
 // src/manifest/verify.ts
 import { z as z3 } from "zod";
+async function listAll(upstreams) {
+  return new Map(
+    await Promise.all(upstreams.map(async (upstream) => [upstream.name, await toolShapes(upstream)]))
+  );
+}
 var listSchema = z3.looseObject({
   tools: z3.array(
     z3.looseObject({
@@ -2103,11 +2183,11 @@ async function toolShapes(upstream) {
   } while (cursor !== void 0);
   return shapes;
 }
-async function verifyAgainstServers(upstreams, manifest) {
+async function verifyAgainstServers(upstreams, manifest, listed) {
   const shapes = /* @__PURE__ */ new Map();
   const available = /* @__PURE__ */ new Map();
   for (const upstream of upstreams) {
-    const advertised = await toolShapes(upstream);
+    const advertised = listed?.get(upstream.name) ?? await toolShapes(upstream);
     shapes.set(upstream.name, advertised);
     available.set(upstream.name, new Set(advertised.map((tool) => tool.name)));
   }
@@ -2154,10 +2234,11 @@ async function verifyAgainstServers(upstreams, manifest) {
     );
   }
 }
-async function withoutMissingTools(upstreams, manifest) {
+async function withoutMissingTools(upstreams, manifest, listed) {
   const available = /* @__PURE__ */ new Map();
   for (const upstream of upstreams) {
-    available.set(upstream.name, new Set((await toolShapes(upstream)).map((tool) => tool.name)));
+    const advertised = listed?.get(upstream.name) ?? await toolShapes(upstream);
+    available.set(upstream.name, new Set(advertised.map((tool) => tool.name)));
   }
   const missing = (qualified) => {
     const target = splitQualified(qualified);
@@ -2537,6 +2618,31 @@ function refusal(error) {
   }
   return void 0;
 }
+async function startTogether(items, start2) {
+  const settled2 = await Promise.allSettled(
+    items.map(async (item) => ({ item, upstream: await start2(item) }))
+  );
+  const started = [];
+  const failed = [];
+  items.forEach((item, index) => {
+    const result = settled2[index];
+    if (result?.status === "fulfilled") {
+      started.push(result.value.upstream);
+    } else if (result !== void 0) {
+      failed.push({ item, error: result.reason });
+    }
+  });
+  return { started, failed };
+}
+async function startAll(items, start2) {
+  const { started, failed } = await startTogether(items, start2);
+  const first = failed[0];
+  if (first !== void 0) {
+    await Promise.all(started.map((upstream) => upstream.close().catch(() => void 0)));
+    throw first.error;
+  }
+  return started;
+}
 
 // src/install/clients.ts
 import { existsSync as existsSync3, readFileSync as readFileSync2, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync } from "fs";
@@ -2854,7 +2960,15 @@ function discover(cwd) {
       sites.push({ client, label: LABELS[client], format: "json", path, scope, at: ["mcpServers"] });
     }
   }
-  return sites;
+  const seen = /* @__PURE__ */ new Set();
+  return sites.filter((site) => {
+    const key = `${resolve2(site.path)}\0${site.at.join("\0")}`;
+    if (seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  });
 }
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -3870,6 +3984,8 @@ export {
   cliCommand,
   cliCommandFrom,
   proxyCommand,
+  JOURNAL_NAME,
+  home,
   findManifest,
   findJournal,
   counted,
@@ -3891,6 +4007,7 @@ export {
   splitQualified,
   fingerprint,
   pinBlock,
+  listAll,
   toolShapes,
   verifyAgainstServers,
   withoutMissingTools,
@@ -3918,6 +4035,8 @@ export {
   differing,
   declaredNames,
   connectUpstream,
+  startTogether,
+  startAll,
   LOOKED_FOR,
   CLIENT_IDS,
   isClientId,
@@ -3932,4 +4051,4 @@ export {
   applyUninstall,
   clientEnvFor
 };
-//# sourceMappingURL=chunk-AEEKBR5D.js.map
+//# sourceMappingURL=chunk-MTPUG26S.js.map

package/dist/cli.js

@@ -33,6 +33,7 @@ import {
   isClientId,
   isWrapped,
   labelFor,
+  listAll,
   loadManifest,
   observeState,
   openJournal,
@@ -48,6 +49,8 @@ import {
   serversAt,
   splitQualified,
   standing,
+  startAll,
+  startTogether,
   style,
   toPayload,
   toResolvedRead,
@@ -59,7 +62,7 @@ import {
   verifyAgainstServers,
   warnUntested,
   wasRefused
-} from "./chunk-AEEKBR5D.js";
+} from "./chunk-MTPUG26S.js";
 import {
   DriftConflict,
   ManifestError,
@@ -372,7 +375,11 @@ ${seen}` : seen;
       }
       if (sameState(current, recordedPost.data)) {
         verified = true;
-      } else if (sameState(current, intendedAfterInverse(action))) {
+      } else if (sameState(current, intendedAfterInverse(action)) || // An inverse this undo sent before it was killed, whose owner is gone:
+      // the resource having reached the state it produces is the inverse
+      // having landed. Found by SIGKILLing undo mid-compensation: the delete
+      // had gone through, and every later attempt called its absence drift.
+      action.status === "rolling_back" && journal.leaseFor(action.id)?.alive === false && looksUndone(current, action)) {
         steps.push({
           ...describeStep(action),
           kind: "already-reverted",
@@ -487,6 +494,19 @@ ${seen}` : seen;
       journal.markRolledBack(action.id);
       continue;
     }
+    const landed = outcome.rejected && recordedPost.success && verifyRead.success ? await landedAnyway(router, toResolvedRead(verifyRead.data), recordedPost.data, action, signal) : void 0;
+    if (landed !== void 0) {
+      journal.markRolledBack(action.id);
+      steps[steps.length - 1] = {
+        ...describeStep(action),
+        kind: "revert",
+        reason: landed,
+        verified,
+        plan,
+        note: `the server reported an error (${truncated(outcome.message)}), but the resource had changed as this inverse changes it`
+      };
+      continue;
+    }
     const halt = new RollbackHalted(action.seq, outcome.message);
     if (outcome.rejected) {
       journal.markInverseRejected(action.id, halt.message);
@@ -544,6 +564,28 @@ function overwriteText(current, action) {
   }
   return changedLines(current, intended2);
 }
+async function landedAnyway(router, read, post, action, signal) {
+  let now;
+  try {
+    now = await observeState(router, read, signal);
+  } catch {
+    return void 0;
+  }
+  if (sameState(now, post)) {
+    return void 0;
+  }
+  return looksUndone(now, action) ? "done, despite the server reporting an error" : void 0;
+}
+function looksUndone(now, action) {
+  const intended2 = intendedAfterInverse(action);
+  if (intended2 !== void 0) {
+    return sameState(now, intended2);
+  }
+  return action.class === "compensable" && !now.present;
+}
+function truncated(text) {
+  return text.length > 160 ? `${text.slice(0, 157)}...` : text;
+}
 function intendedAfterInverse(action) {
   return action.snapshot === void 0 ? void 0 : { present: true, value: action.snapshot };
 }
@@ -1084,7 +1126,12 @@ function render(journal, options, tick, view) {
     });
     out2.push("");
     out2.push(
-      canDecide(options) ? `  ${keyHint("a", "approve")}   ${keyHint("A", "and for an hour")}   ${keyHint("d", "deny")}   ${keyHint("j/k", "move")}   ${keyHint("q", "quit")}` : `  ${style.quiet(`${options.approveWith} approve --all`)}`
+      canDecide(options) ? `  ${keyHint("a", "approve")}   ${keyHint("A", "approve for an hour")}   ${keyHint("d", "deny")}   ${keyHint("j/k", "move")}   ${keyHint("q", "quit")}` : `  ${style.quiet(`${options.approveWith} approve --all`)}`
+    );
+  } else if (canDecide(options)) {
+    out2.push("");
+    out2.push(
+      `  ${keyHint("q", "quit")}   ${style.quiet("A held call appears here; answer it with")} ${style.strong("a")} ${style.quiet("approve,")} ${style.strong("A")} ${style.quiet("approve for an hour, or")} ${style.strong("d")} ${style.quiet("deny.")}`
     );
   }
   if (view.notice !== "") {
@@ -1151,6 +1198,8 @@ async function watch(options) {
     const waiting = ready.listGated();
     const action = waiting[Math.min(view.cursor, waiting.length - 1)];
     if (action === void 0) {
+      view.notice = "Nothing is waiting right now. When an agent's call is held, it appears above and this key answers it.";
+      view.noticeUntil = tick + NOTICE_TICKS;
       return;
     }
     const changed = approve ? ready.approve(action.id, options.decideAs) : ready.denyByPerson(action.id, options.decideAs, "denied from the watch view");
@@ -1185,6 +1234,10 @@ async function watch(options) {
         view.cursor = Math.max(0, view.cursor - 1);
         return;
       default:
+        if (key.length === 1 && key >= " ") {
+          view.notice = `${key} does nothing here. Keys: a approve, A approve for an hour, d deny, j/k move, q quit`;
+          view.noticeUntil = tick + NOTICE_TICKS;
+        }
         return;
     }
   };
@@ -1278,7 +1331,9 @@ function scan(journal, cwd) {
     }
     const connections = Object.entries(servers).map(([server, entry]) => {
       const covered = isWrapped(entry);
-      const lastSeen = seen.get(server);
+      const args = entry.args ?? [];
+      const named = covered && args.includes("--server") ? args[args.indexOf("--server") + 1] : void 0;
+      const lastSeen = seen.get(named ?? server);
       return {
         client: site.client,
         scope: site.scope,
@@ -1526,12 +1581,13 @@ function gatesView(journal, screen, options) {
     return [`  ${style.quiet("Nothing is waiting for a decision.")}`];
   }
   const at = Math.min(screen.cursor, waiting.length - 1);
-  return waiting.map((action, index) => {
+  return waiting.flatMap((action, index) => {
     const here = index === at && canPress(options);
     const name = `${action.server}.${action.tool}`;
     const shown = here ? style.accent(name) : style.quiet(name);
     const args = style.quiet(truncate2(JSON.stringify(action.args), 54));
-    return `  ${here ? style.accent(CURSOR) : " "} ${shown}  ${args}`;
+    const why = here && action.error !== void 0 ? [`      ${style.quiet(truncate2(action.error, 90))}`] : [];
+    return [`  ${here ? style.accent(CURSOR) : " "} ${shown}  ${args}`, ...why];
   });
 }
 function footer(screen, options) {
@@ -1542,7 +1598,7 @@ function footer(screen, options) {
     const what = screen.confirmingForce ? `undo ${screen.confirmingLabel ?? "this session"} anyway, losing that change?` : `undo ${screen.confirmingLabel ?? "this session"}?`;
     return ["", `  ${style.accent(what)}  ${keyHint2("y", "yes")}   ${keyHint2("n", "no")}`];
   }
-  const keys = screen.mode === "connections" ? [keyHint2("enter", "connect"), keyHint2("a", "connect all"), keyHint2("r", "rescan"), keyHint2("j/k", "move"), keyHint2("h", "back")] : screen.mode === "gates" ? [keyHint2("a", "approve"), keyHint2("A", "and for an hour"), keyHint2("d", "deny"), keyHint2("j/k", "move"), keyHint2("r", "runs")] : screen.mode === "run" ? [
+  const keys = screen.mode === "connections" ? [keyHint2("enter", "connect"), keyHint2("a", "connect all"), keyHint2("r", "rescan"), keyHint2("j/k", "move"), keyHint2("h", "back")] : screen.mode === "gates" ? [keyHint2("a", "approve"), keyHint2("A", "approve for an hour"), keyHint2("d", "deny"), keyHint2("j/k", "move"), keyHint2("r", "runs")] : screen.mode === "run" ? [
     keyHint2("l", "check now"),
     keyHint2("p", "preview undo"),
     keyHint2("u", "undo"),
@@ -1553,10 +1609,38 @@ function footer(screen, options) {
     keyHint2("l", "check now"),
     keyHint2("u", "undo"),
     keyHint2("j/k", "move"),
-    keyHint2("g", "held")
+    keyHint2("g", "waiting calls")
   ];
   return ["", `  ${keys.join("   ")}   ${keyHint2("q", "quit")}`];
 }
+function welcomeFrame(screen, options, tick) {
+  const spinner = options.live ? `${style.accent(FRAMES2[tick % FRAMES2.length] ?? "")} ` : "";
+  const waiting = needsConnecting(screen.groups).length;
+  const lead = screen.groups.length === 0 ? [] : waiting === 0 ? [
+    `  ${style.strong("Everything below is covered.")} ${style.quiet("Restart those apps if you have not,")}`,
+    `  ${style.quiet("then use your agent as usual. Its sessions will appear here.")}`
+  ] : [
+    `  ${style.strong("Welcome.")} ${style.quiet("These are the AI apps on this machine and the tools they use.")}`,
+    `  ${style.quiet("Press")} ${style.strong("a")} ${style.quiet("to cover all of them, or move to one and press")} ${style.strong("enter")}${style.quiet(".")}`,
+    `  ${style.quiet("Nothing else on your machine is changed, and")} ${style.strong("synartesis uninstall")} ${style.quiet("puts it all back.")}`
+  ];
+  const notice = screen.notice === "" ? [] : ["", ...screen.notice.split("\n").map((line2) => `  ${style.accent(line2)}`)];
+  return [
+    "",
+    `  ${style.plate(WORDMARK)}`,
+    `  ${rule(70)}`,
+    "",
+    `  ${spinner}${style.quiet(screen.busy ?? "nothing has run through Synartesis yet")}`,
+    "",
+    ...lead,
+    ...lead.length === 0 ? [] : [""],
+    ...windowed(connectionsView(screen, options), screen.cursor, roomFor(options)),
+    ...notice,
+    "",
+    `  ${[keyHint2("a", "cover all"), keyHint2("enter", "cover this one"), keyHint2("j/k", "move"), keyHint2("r", "look again"), keyHint2("q", "quit")].join("   ")}`,
+    ""
+  ].join("\n");
+}
 function waitingForJournal2(options, tick) {
   const spinner = options.live ? `${style.accent(FRAMES2[tick % FRAMES2.length] ?? "")} ` : "";
   return [
@@ -1611,7 +1695,8 @@ async function openConsole(options) {
     groups: [],
     busy: void 0,
     notice: "",
-    noticeUntil: 0
+    noticeUntil: 0,
+    welcome: false
   };
   let tick = 0;
   const stopped = () => screen.stop;
@@ -1622,15 +1707,30 @@ async function openConsole(options) {
   const frame = () => {
     const ready = open();
     if (ready === void 0) {
+      if (options.scan !== void 0 && canPress(options)) {
+        return welcomeFrame(screen, options, tick);
+      }
       return waitingForJournal2(options, tick);
     }
+    if (screen.welcome) {
+      screen.welcome = false;
+      screen.mode = "runs";
+      screen.cursor = 0;
+      say("the first session has arrived");
+    }
     const tail = command(ready);
     const shout = screen.notice === "" ? 0 : screen.notice.split("\n").length;
     const room = Math.max(3, roomFor(options) - tail.length - shout);
     const body = screen.mode === "runs" ? windowed(runsView(ready, screen, options), screen.cursor, room) : screen.mode === "run" ? windowed(runView(ready, screen), 0, room) : screen.mode === "connections" ? windowed(connectionsView(screen, options), screen.cursor, room) : windowed(gatesView(ready, screen, options), screen.cursor, room);
     const notice = screen.notice === "" ? [] : ["", ...screen.notice.split("\n").map((line2) => `  ${style.accent(line2)}`)];
+    const held2 = screen.mode === "gates" || screen.mode === "connections" ? 0 : ready.listGated().length;
+    const alert = held2 === 0 ? [] : [
+      `  ${style.accent(`${String(held2)} ${held2 === 1 ? "call is" : "calls are"} waiting for you`)}  ${style.quiet("press")} ${style.strong("g")} ${style.quiet("to answer")}`,
+      ""
+    ];
     return [
       ...header(options, screen, tick),
+      ...alert,
       ...body,
       ...notice,
       ...tail,
@@ -1754,6 +1854,13 @@ async function openConsole(options) {
   const rescan = () => {
     screen.groups = options.scan?.() ?? [];
   };
+  if (!existsSync3(options.journalPath) && options.scan !== void 0) {
+    screen.welcome = true;
+    screen.mode = "connections";
+    rescan();
+  } else if (canPress(options) && (open()?.listGated().length ?? 0) > 0) {
+    screen.mode = "gates";
+  }
   const connect = async (targets) => {
     if (options.connect === void 0) {
       say("no way to connect was configured");
@@ -1937,6 +2044,9 @@ async function openConsole(options) {
         return;
       }
       default:
+        if (key.length === 1 && key >= " ") {
+          say(`${key} does nothing here; the keys that work are listed on the bottom line`);
+        }
         return;
     }
   };
@@ -1954,6 +2064,9 @@ async function openConsole(options) {
         return;
       }
       press(next.value);
+      if (screen.welcome && open() === void 0) {
+        screen.mode = "connections";
+      }
       if (stopped()) {
         return;
       }
@@ -2064,11 +2177,12 @@ if (NODE_MAJOR < 22) {
   process.exit(2);
 }
 var COMMANDS = `
-  synartesis                                      start here. Live activity,
-                                                  what is waiting for you, and
-                                                  undo -- all in one place, with
-                                                  the arrow keys. Everything
-                                                  below can be done from it.
+  synartesis                                      start here. The first time,
+                                                  it lists your AI apps: press a
+                                                  to cover them. After that it
+                                                  opens on anything waiting for
+                                                  you, and on what agents did,
+                                                  with undo on the arrow keys.
   synartesis install [--client <name>] [--remote] [--dry-run] [--print]
   synartesis uninstall [--client <name>]
   synartesis status
@@ -2079,6 +2193,8 @@ var COMMANDS = `
   synartesis show <runId> [--full] [--live] [--journal <path>]
   synartesis gates [--journal <path>]
   synartesis close [runId] [--journal <path>]
+  synartesis clean [--dry-run] [--yes]              clear finished sessions,
+                                                  keep what still matters
   synartesis prune [--older-than <days>] [--dry-run] [--journal <path>]
   synartesis proxy --manifest <path> [--server <name>]    what your agent runs
                   [--journal <path>]
@@ -2254,14 +2370,16 @@ async function startAsTheClientWould(manifestPath, name, spec, session) {
 async function runPin(argv) {
   const path = findManifest(flag(argv, "--manifest"));
   const manifest = loadManifest(path);
-  const shapes = /* @__PURE__ */ new Map();
+  let shapes = /* @__PURE__ */ new Map();
   const upstreams = [];
   try {
-    for (const [name, spec] of Object.entries(manifest.servers)) {
-      const upstream = await startAsTheClientWould(path, name, spec);
-      upstreams.push(upstream);
-      shapes.set(name, await toolShapes(upstream));
-    }
+    upstreams.push(
+      ...await startAll(
+        Object.entries(manifest.servers),
+        ([name, spec]) => startAsTheClientWould(path, name, spec)
+      )
+    );
+    shapes = await listAll(upstreams);
   } finally {
     for (const upstream of upstreams) {
       await upstream.close();
@@ -2321,13 +2439,17 @@ async function runCheck(argv) {
   const offered = /* @__PURE__ */ new Map();
   const trustedReads = /* @__PURE__ */ new Map();
   try {
-    for (const [name, spec] of Object.entries(manifest.servers)) {
-      upstreams.push(await startAsTheClientWould(path, name, spec));
-    }
-    await verifyAgainstServers(upstreams, manifest);
+    upstreams.push(
+      ...await startAll(
+        Object.entries(manifest.servers),
+        ([name, spec]) => startAsTheClientWould(path, name, spec)
+      )
+    );
+    const listed = await listAll(upstreams);
+    await verifyAgainstServers(upstreams, manifest, listed);
     const resolver = createPolicyResolver(manifest);
     for (const upstream of upstreams) {
-      const shapes = await toolShapes(upstream);
+      const shapes = listed.get(upstream.name) ?? [];
       const trusted = shapes.filter(
         (tool) => tool.readOnly === true && trustsMarks(manifest, upstream.name) && !resolver.resolve(`${upstream.name}.${tool.name}`).matched
       ).map((tool) => tool.name);
@@ -2594,10 +2716,16 @@ async function connectThese(targets, manifestPath) {
   );
   const applied = applyInstall(plans, manifestPath, yaml);
   const count = applied.reduce((sum, entry) => sum + entry.servers.length, 0);
+  const skipped = plans.flatMap((plan) => plan.skipped.map((skip) => `${skip.name}: ${skip.why}`));
   if (count === 0) {
-    return "nothing was connected; see the reasons above";
+    return skipped.length === 0 ? "nothing needed connecting" : `not connected -- ${skipped.join("; ")}`;
   }
-  return `connected ${String(count)}${count === 1 ? " server" : " servers"} \xB7 restart the client to pick it up`;
+  const apps = [...new Set(applied.map((entry) => entry.site.label))];
+  const restart = `quit and reopen ${apps.join(" and ")} to start using it`;
+  return [
+    `covered ${String(count)}${count === 1 ? " server" : " servers"} \xB7 ${restart}`,
+    ...skipped.length === 0 ? [] : [`not covered -- ${skipped.join("; ")}`]
+  ].join("\n");
 }
 function runStatus(argv) {
   const manifestPath = findManifest(flag(argv, "--manifest"));
@@ -2884,10 +3012,15 @@ function runList(journal, asJson, journalPath) {
   }
   hint(firstOf(
     () => heldCalls(journal),
+    () => {
+      const clearable = journal.cleanable(new Date(Date.now() - CLEAN_IDLE_MS).toISOString()).finished.length;
+      return clearable >= CLEAN_NAG_SESSIONS ? { why: `${String(clearable)} of these are finished with nothing left to undo; to clear them`, run: "clean", needs: ["journal"] } : void 0;
+    },
     () => whatChanged(journal)
   ));
   return 0;
 }
+var CLEAN_NAG_SESSIONS = 10;
 async function runShow(argv, journal, asJson) {
   const full = argv.includes("--full");
   const runs = [...journal.listRuns()].reverse();
@@ -3177,6 +3310,66 @@ function runPrune(argv, journal, journalPath) {
   out("");
   return 0;
 }
+var CLEAN_IDLE_MS = 24 * 60 * 60 * 1e3;
+async function runClean(argv, journal, journalPath) {
+  const idleBefore = new Date(Date.now() - CLEAN_IDLE_MS).toISOString();
+  const { abandoned, finished } = journal.cleanable(idleBefore);
+  const total = journal.listRuns().length;
+  const empty = finished.filter((run) => run.actions === 0).length;
+  const kept = total - finished.length;
+  const sizeBefore = sizeOf(journalPath);
+  out("");
+  out(`  ${style.label("clean")}  ${style.quiet(journalPath)}`);
+  out(`  ${rule(54)}`);
+  out("");
+  if (finished.length === 0 && abandoned.length === 0) {
+    out(`  ${style.quiet("Nothing to clear: every session here is still in use, or still has")}`);
+    out(`  ${style.quiet("something you could undo or decide.")}`);
+    out("");
+    return 0;
+  }
+  out(
+    `  ${style.strong("clears")}  ${counted(finished.length, "finished session")} with nothing left to undo` + (empty > 0 ? style.quiet(` (${String(empty)} of them empty)`) : "")
+  );
+  if (abandoned.length > 0) {
+    out(`  ${style.strong("closes")}  ${counted(abandoned.length, "session")} left open by an app that is no longer running`);
+  }
+  out(
+    `  ${style.strong("keeps ")}  ${counted(kept, "session")} ${style.quiet("still running, or with something to undo or decide")}`
+  );
+  out(`  ${style.quiet("        your connected apps and your policy are not touched")}`);
+  out("");
+  if (argv.includes("--dry-run")) {
+    out(`  ${style.quiet("Nothing was changed.")}`);
+    out("");
+    return 0;
+  }
+  if (!argv.includes("--yes")) {
+    if (!process.stdin.isTTY) {
+      out(`  ${style.quiet("Nothing was changed. Run it in a terminal to be asked, or add --yes.")}`);
+      out("");
+      return 1;
+    }
+    const answer = (await ask("  Go ahead? [y/N] ")).trim().toLowerCase();
+    if (answer !== "y" && answer !== "yes") {
+      out(`  ${style.quiet("Nothing was changed.")}`);
+      out("");
+      return 0;
+    }
+  }
+  for (const id of abandoned) {
+    journal.closeAbandonedRun(id);
+  }
+  const now = journal.cleanable(idleBefore).finished;
+  const removed = journal.deleteRuns(now.map((run) => run.id));
+  journal.vacuum();
+  out("");
+  out(
+    `  ${style.accent(`cleared ${counted(removed.runs, "session")}`)}` + style.quiet(`${abandoned.length > 0 ? `, closed ${String(abandoned.length)}` : ""} \xB7 journal ${sizeBefore} \u2192 ${sizeOf(journalPath)}`)
+  );
+  out("");
+  return 0;
+}
 function runResolve(argv, journal) {
   const applied = argv.includes("--applied");
   const failed = argv.includes("--failed");
@@ -3663,19 +3856,14 @@ function report(result, alreadyForcing = false, as = "") {
 }
 async function withUpstreams(manifestPath, use, only, session) {
   const manifest = loadManifest(manifestPath);
-  const upstreams = [];
-  const missing = [];
+  const wanted = Object.entries(manifest.servers).filter(([name]) => only === void 0 || only.has(name));
+  const { started, failed } = await startTogether(
+    wanted,
+    ([name, spec]) => startAsTheClientWould(manifestPath, name, spec, session)
+  );
+  const upstreams = [...started];
+  const missing = failed.map(({ item: [name], error }) => `${name}: ${describe(error)}`);
   try {
-    for (const [name, spec] of Object.entries(manifest.servers)) {
-      if (only !== void 0 && !only.has(name)) {
-        continue;
-      }
-      try {
-        upstreams.push(await startAsTheClientWould(manifestPath, name, spec, session));
-      } catch (error) {
-        missing.push(`${name}: ${describe(error)}`);
-      }
-    }
     if (upstreams.length === 0 && missing.length > 0) {
       throw new ManifestError(`no server could be started. ${missing.join("; ")}`);
     }
@@ -3869,6 +4057,7 @@ var KNOWN_COMMANDS = [
   "show",
   "gates",
   "close",
+  "clean",
   "prune",
   "proxy",
   "desktop",
@@ -4094,6 +4283,8 @@ ${COMMANDS}`);
         return runClose(argv, journal);
       case "prune":
         return runPrune(argv, journal, journalPath);
+      case "clean":
+        return await runClean(argv, journal, journalPath);
       case "gates":
         return runGates(journal, asJson);
       case "resolve":

package/dist/proxy.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import {
+  JOURNAL_NAME,
   PROXY_FLAGS,
   SILENT,
   canonical,
@@ -13,7 +14,9 @@ import {
   findJournal,
   findManifest,
   fingerprint2 as fingerprint,
+  home,
   isDisconnected,
+  listAll,
   loadManifest,
   mark,
   observeState,
@@ -23,8 +26,8 @@ import {
   qualify,
   refusal,
   runRead,
+  startAll,
   toPayload,
-  toolShapes,
   trustsMarks,
   ungoverned,
   untested,
@@ -33,7 +36,7 @@ import {
   warnUntested,
   withIdempotencyKey,
   withoutMissingTools
-} from "./chunk-AEEKBR5D.js";
+} from "./chunk-MTPUG26S.js";
 import {
   SnapshotError,
   UpstreamError,
@@ -41,7 +44,7 @@ import {
 } from "./chunk-YVOO3PTV.js";
 
 // src/proxy/stdio.ts
-import { resolve } from "path";
+import { join, resolve } from "path";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/proxy/http.ts
@@ -641,7 +644,7 @@ function createProxyServer(options) {
             }
             tools.push({
               ...compatible(tool, (dialect) => {
-                log?.warn(
+                log?.debug(
                   `${upstream.name}.${tool.name} declares JSON Schema ${dialect}; the dialect was dropped so clients that only accept 2020-12 can call it`
                 );
               }),
@@ -1303,8 +1306,8 @@ async function main() {
   const upstreams = [];
   const key = journal.fingerprintKey();
   const startedWith = /* @__PURE__ */ new Map();
+  upstreams.push(...await startAll([...wanted], ([name, spec]) => connectUpstream(name, spec, { env: source })));
   for (const [name, spec] of wanted) {
-    upstreams.push(await connectUpstream(name, spec, { env: source }));
     let client;
     try {
       client = source.kind === "inherit" ? clientEnvFor(argv.manifest, name)?.env : void 0;
@@ -1316,7 +1319,8 @@ async function main() {
       fingerprints: fingerprint(key, upstreamEnv(name, spec, source), declaredNames(spec, client))
     });
   }
-  const { manifest: served, disabled } = await withoutMissingTools(upstreams, manifest);
+  const listed = await listAll(upstreams);
+  const { manifest: served, disabled } = await withoutMissingTools(upstreams, manifest, listed);
   for (const line of disabled) {
     log.warn(line);
   }
@@ -1325,14 +1329,15 @@ async function main() {
     argv.server === void 0 ? served : {
       ...served,
       tools: served.tools.filter((rule) => rule.match.startsWith(`${String(argv.server)}.`))
-    }
+    },
+    listed
   );
   const uncovered = ungoverned(
     served,
-    new Map(await Promise.all(upstreams.map(async (upstream) => [
+    new Map(upstreams.map((upstream) => [
       upstream.name,
-      (await toolShapes(upstream)).filter((tool) => !(tool.readOnly === true && trustsMarks(served, upstream.name))).map((tool) => tool.name)
-    ])))
+      (listed.get(upstream.name) ?? []).filter((tool) => !(tool.readOnly === true && trustsMarks(served, upstream.name))).map((tool) => tool.name)
+    ]))
   );
   for (const entry of uncovered) {
     log.warn(
@@ -1359,7 +1364,13 @@ async function main() {
       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)}`,
-      notify: desktopNotifier()
+      // Plain `synartesis` when this is the journal it finds by itself, which
+      // is the usual case; otherwise told where to look.
+      notify: desktopNotifier(
+        process.env,
+        void 0,
+        resolve(argv.journal) === resolve(join(home(), JOURNAL_NAME)) ? cliCommandFrom(import.meta.url) : `${cliCommandFrom(import.meta.url)} --journal ${resolve(argv.journal)}`
+      )
     });
     proxy2.ready.then((runId) => {
       for (const [server, started] of startedWith) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synartesis",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "An undo layer for AI agents.",
   "type": "module",
   "private": false,
@@ -58,6 +58,8 @@
     "demo": "tsup --silent && ./demo/filesystem-demo.sh",
     "demo:memory": "tsup --silent && ./demo/memory-demo.sh",
     "check": "pnpm build && pnpm typecheck && pnpm lint && pnpm test",
+    "stress": "tsup --silent && SYNARTESIS_STRESS_SESSIONS=500 SYNARTESIS_KILL_ROUNDS=25 SYNARTESIS_RACE_ROUNDS=10 vitest run tests/stress-undo.test.ts tests/kill-undo.test.ts tests/race-approval.test.ts",
+    "coverage": "tsup --silent && vitest run --testTimeout=240000 --coverage --coverage.provider=v8 --coverage.include='src/**' --coverage.reportOnFailure",
     "prepublishOnly": "pnpm check"
   },
   "dependencies": {
@@ -93,6 +95,7 @@
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "@vitejs/plugin-react": "^6.1.1",
+    "@vitest/coverage-v8": "4.1.11",
     "electron": "^44.3.0",
     "electron-builder": "^26.15.3",
     "eslint": "^10.8.1",