tandem-editor 0.21.0 → 0.22.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tandem",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Edit and iterate on documents with any MCP-capable AI. Claude is the default and best-supported client today.",
   "author": {
     "name": "Tandem"
@@ -11,14 +11,14 @@
   "mcpServers": {
     "tandem": {
       "command": "npx",
-      "args": ["-y", "tandem-editor@0.21.0", "mcp-stdio"],
+      "args": ["-y", "tandem-editor@0.22.0", "mcp-stdio"],
       "env": {
         "TANDEM_URL": "http://127.0.0.1:3479"
       }
     },
     "tandem-channel": {
       "command": "npx",
-      "args": ["-y", "tandem-editor@0.21.0", "channel"],
+      "args": ["-y", "tandem-editor@0.22.0", "channel"],
       "env": {
         "TANDEM_URL": "http://127.0.0.1:3479"
       }
@@ -28,13 +28,13 @@
     "monitors": [
       {
         "name": "tandem-events",
-        "command": "npx -y tandem-editor@0.21.0 monitor",
+        "command": "npx -y tandem-editor@0.22.0 monitor",
         "description": "Tandem real-time document events (annotations, chat, selections)",
         "when": "on-skill-invoke:tandem:tandem"
       },
       {
         "name": "tandem-events-user-skill",
-        "command": "npx -y tandem-editor@0.21.0 monitor",
+        "command": "npx -y tandem-editor@0.22.0 monitor",
         "description": "Tandem real-time document events (annotations, chat, selections)",
         "when": "on-skill-invoke:tandem"
       }

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.22.0] - 2026-08-11
+
+This release is about your AI noticing that you said something.
+
+Tandem has always been able to tell your AI that you commented on a paragraph or sent a chat message, but for sessions you started yourself, something had to be listening first — and nothing arranged that for you. A session you opened by typing `claude` would sit there while your comments piled up unread. Now it sets that up itself, on its own, the first time it touches Tandem, and Tandem says how at the moment the connection opens rather than hoping the subject comes up later. Measured across ten isolated sessions, the number that arranged it went from three in six to six in six.
+
+The rest is a smaller thing that will save you a round trip: bug reports now arrive with the details we would otherwise have to ask you for, and the Report a bug link fills them in.
+
+### Changed
+
+- **Hand-started Claude Code sessions now try to watch Tandem automatically on first use.** After the first successful read-only `tandem_status`, the bundled skill makes one persistent built-in Monitor attempt using the server-reported wake address; asking Claude to watch is now recovery rather than setup. Existing setup-managed skill copies refresh before Tandem reports ready, including when the launcher is disabled or deferred. A missing standalone skill does not install during generic startup, so plugin-only users do not silently acquire a second integration route. Plugin-only sessions receive the updated instructions when Claude Code refreshes its plugin cache, on a timeline Tandem does not control. If a plugin-backed session starts both its packaged monitor and the built-in watch automatically, wakes remain payload-free and inbox reads de-duplicate; `TaskStop` stops the built-in watch when doubled wakes make the overlap visible.
+
+- **Tandem now tells your AI how to be woken the moment the connection opens, not only once it reaches for the Tandem skill (#1397).** Tandem's connection has always been able to carry a short standing instruction, and Tandem sent nothing. That text is the only thing besides tool *names* that reaches your AI before it calls anything, so guidance about staying reachable arrived — when it arrived at all — after the moment a session decides how to behave. It now says that the inbox is the authority on your activity, that a client able to hold a persistent watch should open one on the address Tandem reports, and that annotations are held in solo mode. Sessions Tandem launches for you are told to skip the watch, because they are already woken directly and a second watch would deliver everything twice. It deliberately makes no claim about whether *this* session is covered and quotes no subscriber count — Tandem cannot see either, and a standing instruction is not a diagnosis. AI clients other than Claude Code receive the same text; nothing in it names a capability as a requirement, so it reads as inapplicable rather than wrong where no such watch exists. Measured across ten isolated authenticated sessions, first-use arming went from three of six to six of six with this and the two skill changes above in place — the three together, not this one alone.
+
+- **Copy Diagnostics now carries the facts a bug report needs, and the Report-a-bug link fills them in for you (#1394).** Diagnostics used to describe Tandem and almost nothing about the machine it ran on, so most reports opened with a round trip asking for the operating system version, the browser, and how much memory the machine had. Both the copied text and the `tandem_diagnostics` tool now include platform, architecture, OS release and version, CPU model and core count, total memory, Node version, and — in the browser distribution — a short browser descriptor. The Report a bug link in Settings opens a GitHub issue with that block already in the body instead of an empty form. **What is deliberately absent stays absent**, because this text lands in a public issue: your machine name, your username, your home directory path, your network interfaces, your locale and timezone. Paths that do survive are collapsed — your home directory becomes `~`, Tandem's data directory becomes `<app-data>` — including paths that arrive inside raw filesystem error messages, which no prefix list can be trusted to cover. The link gathers diagnostics only after your pointer or keyboard focus rests on it briefly, and not merely passes through: collecting them is not an inert read — it opens and drops a real connection to Tandem's own update stream and runs a global package listing — so a pointer crossing the sidebar on its way elsewhere must not trigger it. If gathering fails, the link still works, unfilled.
+
+### Tests
+
+- **A live-evidence gate for first-use session-monitor arming (#1393).** That a hand-started session arms a watch on first use could previously only be argued from source. This adds a harness that builds an isolated Claude Code and Tandem fixture — its own home, config directory and authentication — and drives real bounded sessions across a ten-trial matrix, emitting signed pass/fail evidence per trial. Two properties are load-bearing: a recorded decline must be shown to be the model's own choice rather than a broken rig, and a re-attempt supersedes prior evidence without erasing it. The suite is not wired into CI; #1399 records why and what it would cost. Harness only — no product code.
+
 ## [0.21.0] - 2026-08-10
 
 Most of this release is Tandem telling you the truth about itself.

package/README.md

@@ -107,9 +107,9 @@ You do not have to configure any of this by hand. Tandem opens a setup wizard th
 
 Prefer a different AI? Any MCP-capable client can connect to the same endpoint — see the [compatibility table](#the-mcp-integration-policy) for what is supported and what is untested, and [Cowork](#cowork) for connecting Claude Desktop on Windows.
 
-**How Claude starts matters.** Tandem talks to Claude over two independent connections: one lets Claude read and edit your document, the other tells it the moment you comment or send a chat message. Sessions Tandem launches for you — including the desktop app's **Relaunch Claude** button — get both, and need no setup from you. A session you start yourself by typing `claude` gets only the first until you add one of three things.
+**How Claude starts matters.** Tandem talks to Claude over two independent connections: one lets Claude read and edit your document, the other tells it the moment you comment or send a chat message. Sessions Tandem launches for you — including the desktop app's **Relaunch Claude** button — get both, and need no setup from you. A session you start yourself by typing `claude` begins with the first connection; on its first successful read-mode `tandem_status`, Tandem's bundled skill automatically tells it to attempt the second with the built-in Monitor when that tool is available.
 
-The simplest needs no installation at all: **ask Claude to watch for updates.** Tandem's bundled skill tells it how, so "watch Tandem for updates while we work" is usually enough — it opens a watch on Tandem's wake stream and is woken whenever you comment or send a message. Nothing to install, no flag, and it lasts as long as that session. It does need a Claude Code that offers a `Monitor` tool. That is enabled per account rather than per version, so upgrading will not add it, and on Windows it also needs Git Bash. If Claude tells you it has none, skip to the third option below — the plugin needs the same tool, so it will not help either.
+The simplest needs no installation at all: **the built-in Monitor watch starts automatically on first Tandem use.** The bundled skill reads the live wake-stream address from that first successful `tandem_status` and makes one persistent attempt for the session. If that attempt was skipped, asking Claude to watch is a recovery step, not normal setup. It does need a Claude Code that offers a built-in Monitor tool. That is enabled per account rather than per version, so upgrading will not add it, and on Windows it also needs Git Bash. The plugin monitor shares the same per-account feature gate, so it cannot help when that gate is off. But the plugin monitor does not require Git Bash on Windows and can fall back to PowerShell, so it may help when Git Bash is the missing precondition. The third option below, the channel shim, avoids both requirements.
 
 The second is to install the Tandem plugin, which also needs no flag — see [Real-time updates](#real-time-updates) below. It starts watching the first time Claude uses Tandem's skill in a session, so ask for Tandem by name ("let's work on this in Tandem") rather than expecting it to be listening before you have mentioned it. Start `claude` from a terminal window if you install it: the plugin's monitor uses whatever program path that shell has, and a Claude Code started from a desktop icon may not have one it can use.
 
@@ -120,7 +120,7 @@ tandem setup --apply --with-channel-shim                              # once
 claude --dangerously-load-development-channels server:tandem-channel  # every session
 ```
 
-Use one of the three, not several: each delivers independently, so a session running two receives every event twice.
+Choose one setup route where possible. A plugin-backed session whose Claude Code also offers the built-in Monitor may start both automatically when it first uses Tandem's skill. Those wakes contain no message content; host rate limiting can hide the overlap, and the inbox de-duplicates what Claude reads. If wakes visibly double, ask Claude to stop its built-in watch with `TaskStop`.
 
 Without any of them nothing breaks and nothing is lost: your messages and comments are saved, and Claude sees them the next time it checks its inbox. But it will not react on its own, which reads as Claude ignoring you. If that is what you are seeing, [this troubleshooting entry](docs/troubleshooting.md#i-sent-a-chat-message-or-left-a-comment-and-nothing-happened) walks through it, and **Settings → About → Copy Diagnostics** (or `tandem doctor`, on npm installs) reports whether anything is listening. More detail in [Real-time updates](#real-time-updates).
 
@@ -255,11 +255,11 @@ Tandem's MCP tools span six capability areas. Full reference: [docs/mcp-tools.md
 
 ### Real-time updates
 
-Real-time delivery gets events (annotation actions, chat messages) to the AI the moment they happen, so it does not have to wait until it next polls. There are three ways to get it, and they are alternatives — not layers.
+Real-time delivery gets events (annotation actions, chat messages) to the AI the moment they happen, so it does not have to wait until it next polls. There are three setup routes; they are not layers you need to configure together. When the plugin and built-in Monitor are both available, however, first skill use can start both automatically — a safe but potentially wasteful overlap described below.
 
 None of them is needed for a session Tandem launches for you. Those are woken directly by Tandem over the session's own input and use none of the three; everything below is about sessions you start by hand.
 
-**A self-armed watch** needs nothing installed and no flag. Ask Claude to watch Tandem for updates and it opens a watch on Tandem's wake stream itself; the bundled skill carries the instructions, and `tandem_status` reports the address to watch. It lasts for that session and disappears with it, which is also the point — nothing is left configured on your machine. This is the path that survives the failures the other two are prone to, so it is the one to try first. Two limits: it needs a Claude Code that offers a `Monitor` tool, and the wake stream is **loopback-only**, so it does not reach a session running anywhere but this machine — Cowork included.
+**A self-armed watch** needs nothing installed and no flag. On first Tandem use, the bundled skill automatically reads the wake-stream address from the first successful `tandem_status` and makes one persistent built-in Monitor attempt. It lasts for that session and disappears with it, which is also the point — nothing is left configured on your machine. Asking Claude to watch is recovery if the automatic attempt was skipped. Two limits: it needs a Claude Code that offers a built-in Monitor tool, and the wake stream is **loopback-only**, so it does not reach a session running anywhere but this machine — Cowork included.
 
 **The plugin monitor** needs no flag either, and once installed it applies to every session — but it starts watching only when Claude first uses Tandem's skill in that session, not the moment the session opens. In practice that means asking for Tandem by name; a Claude that has never been told about Tandem is not listening yet. That is deliberate: it used to start in every session including ones with nothing to do with Tandem, so when it could not run it reported a failure in all of them. Two further conditions: it requires **Claude Code 2.1.212 or newer** — on older versions the install still succeeds and the monitor simply never runs, with nothing to tell you so — and you should start `claude` from a terminal, because the monitor runs with whatever program path that session was given and a desktop-icon launch may not include Node. If it reports `exit 127`, that is this.
 
@@ -272,7 +272,7 @@ claude --dangerously-load-development-channels server:tandem-channel   # every s
 
 The flag is Claude Code's marker for unstable APIs. It works only in an interactive session, and it is required rather than optional: `tandem-channel` is a plain MCP server, and Claude Code's channel allowlist covers only plugins, so there is no list Tandem could join that would remove the need for it. If you already have it configured, your configuration is untouched and keeps working — the change is to what a *new* setup writes. To remove it, re-run `tandem setup --apply` without the flag.
 
-Do not enable more than one: each delivers independently, so a session running two receives every event twice.
+Choose one setup route where possible. A plugin-backed session may still start its packaged monitor and built-in watch automatically. Wakes carry no message content, the inbox de-duplicates what Claude reads, and host rate limiting can hide the overlap; if wakes visibly double, ask Claude to stop its built-in watch with `TaskStop`.
 
 Note that Solo mode suppresses annotation events on all three by design — chat still comes through. If you are testing real-time delivery and only chat arrives, check the mode toggle before debugging the transport.
 

package/dist/cli/index.js

@@ -101,19 +101,27 @@ var init_platform = __esm({
 import { execFile } from "child_process";
 import { join } from "path";
 import { promisify } from "util";
+function throwIfAborted(signal) {
+  if (signal?.aborted) {
+    throw signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+  }
+}
 function systemBin(name) {
   return join(process.env.SystemRoot ?? "C:\\Windows", "System32", name);
 }
-async function runPowerShell(script, env) {
+async function runPowerShell(script, env, signal) {
   const args2 = ["-NoProfile", "-NonInteractive", "-Command", script];
+  throwIfAborted(signal);
   try {
-    return await execFileAsync("pwsh.exe", args2, { env });
+    return await execFileAsync("pwsh.exe", args2, { env, signal });
   } catch (err) {
+    if (signal?.aborted) throw signal.reason ?? err;
     const code = err.code;
     if (code !== "ENOENT") throw err;
     try {
-      return await execFileAsync("powershell.exe", args2, { env });
+      return await execFileAsync("powershell.exe", args2, { env, signal });
     } catch (fallbackErr) {
+      if (signal?.aborted) throw signal.reason ?? fallbackErr;
       throw new Error(
         `runPowerShell: both pwsh.exe and powershell.exe failed (pwsh: ${err.message})`,
         { cause: fallbackErr }
@@ -121,9 +129,13 @@ async function runPowerShell(script, env) {
     }
   }
 }
-async function getCurrentUserSid() {
+async function getCurrentUserSid(signal) {
   if (cachedCurrentUserSid !== null) return cachedCurrentUserSid;
-  const { stdout } = await execFileAsync(systemBin("whoami.exe"), ["/user", "/fo", "csv", "/nh"]);
+  throwIfAborted(signal);
+  const { stdout } = await execFileAsync(systemBin("whoami.exe"), ["/user", "/fo", "csv", "/nh"], {
+    signal
+  });
+  throwIfAborted(signal);
   const match = stdout.match(/"(S-[\d-]+)"\s*$/m);
   if (!match) {
     throw new Error(`getCurrentUserSid: could not parse SID from whoami output: ${stdout.trim()}`);
@@ -133,29 +145,39 @@ async function getCurrentUserSid() {
 }
 async function setRestrictiveAcl(path9, opts = {}) {
   if (process.platform !== "win32") return;
-  const sid = await getCurrentUserSid();
+  const { signal } = opts;
+  throwIfAborted(signal);
+  const sid = await getCurrentUserSid(signal);
   const rights = opts.inheritable ? "(OI)(CI)F" : "F";
   try {
-    await execFileAsync(systemBin("icacls.exe"), [
-      path9,
-      "/inheritance:r",
-      "/grant:r",
-      `*${sid}:${rights}`
-    ]);
+    await execFileAsync(
+      systemBin("icacls.exe"),
+      [path9, "/inheritance:r", "/grant:r", `*${sid}:${rights}`],
+      { signal }
+    );
   } catch (err) {
+    if (signal?.aborted) throw signal.reason ?? err;
     throw new Error(`setRestrictiveAcl: icacls failed on ${path9}: ${err.message}`, {
       cause: err
     });
   }
-  await assertNoBroadAce(path9);
+  throwIfAborted(signal);
+  await assertNoBroadAce(path9, { signal });
 }
-async function assertNoBroadAce(path9) {
+async function assertNoBroadAce(path9, opts = {}) {
   if (process.platform !== "win32") return;
+  const { signal } = opts;
+  throwIfAborted(signal);
   const script = "Import-Module Microsoft.PowerShell.Security; (Get-Acl -LiteralPath $env:TANDEM_ACL_PATH).Sddl";
-  const { stdout } = await runPowerShell(script, {
-    ...process.env,
-    TANDEM_ACL_PATH: path9
-  });
+  const { stdout } = await runPowerShell(
+    script,
+    {
+      ...process.env,
+      TANDEM_ACL_PATH: path9
+    },
+    signal
+  );
+  throwIfAborted(signal);
   const sddl = stdout.trim();
   for (const fragment of BROAD_SDDL_FRAGMENTS) {
     if (sddl.includes(fragment)) {
@@ -477,7 +499,7 @@ function resolveChannelDist(env = process.env, exists = existsSync) {
   return resolve3(PACKAGE_ROOT, "dist/channel/index.js");
 }
 function resolveCliVersion() {
-  if (true) return "0.21.0";
+  if (true) return "0.22.0";
   if (typeof __APP_VERSION__ !== "undefined") return __APP_VERSION__;
   for (const rel of ["../../package.json", "../../../package.json"]) {
     try {
@@ -634,19 +656,42 @@ function detectTargets(opts = {}) {
   }
   return targets;
 }
-async function atomicWrite(content, dest) {
+function throwIfAborted2(signal) {
+  if (signal?.aborted) {
+    throw signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+  }
+}
+async function atomicWrite(content, dest, opts = {}) {
+  const { signal } = opts;
+  throwIfAborted2(signal);
   const tmp = join4(dirname2(dest), `.tandem-setup-${randomUUID2()}.tmp`);
-  await writeFile(tmp, content, { encoding: "utf-8", mode: 384 });
+  try {
+    await writeFile(tmp, content, { encoding: "utf-8", mode: 384, signal });
+  } catch (writeErr) {
+    await unlinkOrLeak(tmp, writeErr);
+    throw writeErr;
+  }
   try {
     if (process.platform === "win32") {
-      await setRestrictiveAcl(tmp);
+      await setRestrictiveAcl(tmp, { signal });
     } else {
+      throwIfAborted2(signal);
       await chmod(tmp, 384);
     }
+    throwIfAborted2(signal);
   } catch (tightenErr) {
     await unlinkOrLeak(tmp, tightenErr);
     throw tightenErr;
   }
+  try {
+    if (process.env.VITEST === "true") await opts.beforeCommitForTests?.();
+    throwIfAborted2(signal);
+    if (opts.requireExistingDest) await stat(dest);
+    throwIfAborted2(signal);
+  } catch (commitGuardErr) {
+    await unlinkOrLeak(tmp, commitGuardErr);
+    throw commitGuardErr;
+  }
   try {
     await rename(tmp, dest);
   } catch (err) {
@@ -665,6 +710,7 @@ async function unlinkOrLeak(path9, originalErr) {
   try {
     await unlink(path9);
   } catch (cleanupErr) {
+    if (cleanupErr.code === "ENOENT") return;
     if (originalErr instanceof Error && originalErr.cause === void 0) {
       originalErr.cause = cleanupErr;
     }
@@ -3531,21 +3577,21 @@ function evaluatePushPath(push) {
     return {
       status: "warn",
       message: "No real-time push consumer attached \u2014 Claude is not notified when you comment or send a chat message, and only sees them when it polls its inbox",
-      fix: "This affects sessions you start yourself; sessions Tandem launches are woken directly and do not use this path. Simplest first: ask Claude to watch for updates \u2014 it can arm a watch on Tandem's wake stream itself, with nothing to install and no flag (the bundled skill tells it how; `tandem_status` reports the address). That one needs a Monitor tool, which not every Claude Code has \u2014 it is enabled per account rather than per version, so upgrading will not add it, and on Windows it also needs Git Bash. If Claude says it has none, go straight to the channel shim below: the plugin monitor needs the same tool and will not help. Otherwise install the Tandem plugin, which registers a monitor needing no flag (`claude plugin list` to check) \u2014 start `claude` from a terminal if you do, since the monitor inherits that shell's PATH and cannot find Node without it \u2014 or register the channel shim with `tandem setup --apply --with-channel-shim` and start Claude Code with `--dangerously-load-development-channels server:tandem-channel`. Use ONE of the three, not several \u2014 each delivers independently, so running two means every event arrives twice.",
+      fix: "This affects sessions you start yourself; sessions Tandem launches are woken directly and do not use this path. Simplest first: ask Claude to watch for updates \u2014 it can arm a watch on Tandem's wake stream itself, with nothing to install and no flag (the bundled skill tells it how; `tandem_status` reports the address). That one needs a Monitor tool, which not every Claude Code has \u2014 it is enabled per account rather than per version, so upgrading will not add it, and on Windows it also needs Git Bash. If Claude says it has none, the channel shim below is the option that always avoids Monitor. The plugin monitor shares that per-account feature gate, so it will not help if the gate is off; however, the plugin monitor does not require Git Bash on Windows and can fall back to PowerShell, so it can help when Git Bash is the missing precondition. You can install the Tandem plugin, which registers a monitor needing no flag (`claude plugin list` to check) \u2014 start `claude` from a terminal if you do, since the monitor inherits that shell's PATH and cannot find Node without it \u2014 or register the channel shim with `tandem setup --apply --with-channel-shim` and start Claude Code with `--dangerously-load-development-channels server:tandem-channel`. Choose one setup route where possible. When the plugin and built-in Monitor are both available, invoking Tandem's skill can start both automatically; doubled wakes carry no content and the inbox de-duplicates, but they can waste a turn. Ask Claude to stop its built-in watch with `TaskStop` if that happens.",
       data
     };
   }
   if (eventCount === 0) {
     return {
       status: "pass",
-      message: `${subscribers} push consumer(s) attached; no events delivered yet this run (expected if you haven't edited, or if you're in Solo mode)`,
+      message: `${subscribers} push consumer(s) attached; no events delivered yet this run (expected if you haven't edited, or if you're in Solo mode; this is a process-global count, NOT that this Claude session is covered)`,
       data
     };
   }
   const agoS = p.lastEventAt ? Math.round((Date.now() - p.lastEventAt) / 1e3) : null;
   return {
     status: "pass",
-    message: `${subscribers} push consumer(s) attached; ${eventCount} event(s) delivered this run, most recently ${agoS === null ? "?" : `${agoS}s`} ago (confirms events reach a consumer, NOT that Claude sees them)`,
+    message: `${subscribers} push consumer(s) attached; ${eventCount} event(s) delivered this run, most recently ${agoS === null ? "?" : `${agoS}s`} ago (confirms events reach a process-global consumer, NOT that this Claude session is covered or saw them)`,
     data
   };
 }
@@ -3755,7 +3801,7 @@ function evaluateStaleGlobal(bundled, globalVersion) {
   };
 }
 async function checkStaleGlobal(r) {
-  const bundled = true ? "0.21.0" : null;
+  const bundled = true ? "0.22.0" : null;
   if (!bundled) return;
   let globalVersion;
   try {
@@ -4862,7 +4908,7 @@ process.once("unhandledRejection", (reason) => {
 `);
   process.exit(1);
 });
-var version = true ? "0.21.0" : "0.0.0-dev";
+var version = true ? "0.22.0" : "0.0.0-dev";
 var args = process.argv.slice(2);
 if (args.includes("--help") || args.includes("-h")) {
   console.log(`tandem v${version}