@insitue/claude-plugin 0.6.0 → 0.6.2

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "insitue",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Drive a Claude Code session from the InSitue browser overlay. Pick an element in your app, claude reads the file and proposes the edit.",
   "mcpServers": {
     "insitue": {

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @insitue/claude-plugin
 
+## 0.6.2
+
+- **Echo the request before fixing.** The cloud-issue instructions (connect.md + the `claim_cloud_issue` tool) now require Claude to print the exact request verbatim ("Fixing locally: …") before any analysis or edits, so you always see what it's about to act on.
+
+## 0.6.1
+
+- **Fix: refuse to reuse a stale companion.** `ensureCompanion` now checks a reachable companion's version via the handshake and, if it is older than the cloud-feature floor (0.7.0), tears it down and spawns the current one — instead of silently attaching to a stale companion left on the port.
+
 ## 0.6.0
 
 - **Sign in from Claude.** New `/insitue:login` command + `authenticate` / `complete_authentication` MCP tools open a browser, you approve, and a token is stored automatically — no manual paste.

package/commands/connect.md

@@ -160,8 +160,14 @@ action.
 **Typical loop:**
 
 1. `list_cloud_issues` → pick an issue with the user.
-2. `claim_cloud_issue <id>` → read `source.file` around `source.line`,
-   understand the repro from `note` + `consoleErrors`, make the fix.
+2. `claim_cloud_issue <id>` → **before doing anything else**, echo the
+   exact request verbatim to the developer:
+
+   > **Fixing locally:** [verbatim `note` from the claim response]
+   > (Source: `source.file:source.line`)
+
+   Then read `source.file` around `source.line`, understand the repro
+   from `note` + `consoleErrors`, make the fix.
 3. Open a PR.
 4. `resolve_cloud_issue <id> <prUrl>`.
 
@@ -169,6 +175,18 @@ The cloud-issue workflow follows the same guardrails as browser picks:
 never auto-apply writes, always wait for explicit user approval before
 editing files.
 
+**Echo guardrail (cloud-issue path).** Mirroring the pick-loop rule
+("Always echo the prompt back first"): after a successful
+`claim_cloud_issue`, the FIRST thing you output to the developer MUST
+be the exact issue `note` in the format above — verbatim, not
+paraphrased. The CLI transcript only shows your output, not the
+dashboard description the reporter wrote. Without the echo the
+developer cannot confirm you're acting on the right issue before edits
+begin. Note: when an issue arrives via the browser "Fix locally"
+button it flows through the normal pick loop and the existing
+pick-echo rule already applies — but the same requirement holds when
+you claim via the cloud-issue tool path directly.
+
 ## Failure modes to handle gracefully
 
 - **`source.file` doesn't exist**: tell the user the path the

package/dist/mcp-server.js

@@ -291,30 +291,64 @@ var PickBuffer = class {
     this.waiters.length = 0;
   }
 };
+var MIN_COMPANION = "0.7.0";
+function semverGte(version, floor) {
+  function parse(v) {
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
+    if (!m) return [0, 0, 0];
+    return [parseInt(m[1], 10), parseInt(m[2], 10), parseInt(m[3], 10)];
+  }
+  const [vMaj, vMin, vPat] = parse(version);
+  const [fMaj, fMin, fPat] = parse(floor);
+  if (vMaj !== fMaj) return vMaj > fMaj;
+  if (vMin !== fMin) return vMin > fMin;
+  return vPat >= fPat;
+}
 async function probeCompanion(session2) {
   try {
     process.kill(session2.pid, 0);
   } catch {
-    return false;
+    return null;
   }
   return new Promise((resolve) => {
+    let rawBody = "";
     const req = httpRequest(
       {
         host: "127.0.0.1",
         port: session2.port,
         path: "/insitue/handshake",
         method: "GET",
+        // Include an Origin so the handshake endpoint returns 200 + JSON
+        // instead of 403 (which it returns when Origin is absent). We
+        // use the loopback Origin — the companion's allowLocalhost flag
+        // accepts any localhost:* Origin, or else this falls back to 403
+        // which we still treat as "reachable" (non-null return).
+        headers: { origin: "http://localhost:5747" },
         timeout: 1500
       },
       (res) => {
-        res.resume();
-        resolve(true);
+        res.setEncoding("utf8");
+        res.on("data", (chunk) => {
+          rawBody += chunk;
+        });
+        res.on("end", () => {
+          if (res.statusCode === 200) {
+            try {
+              const body = JSON.parse(rawBody);
+              resolve(body.companionVersion ?? "0.0.0");
+            } catch {
+              resolve("0.0.0");
+            }
+          } else {
+            resolve("0.0.0");
+          }
+        });
       }
     );
-    req.on("error", () => resolve(false));
+    req.on("error", () => resolve(null));
     req.on("timeout", () => {
       req.destroy();
-      resolve(false);
+      resolve(null);
     });
     req.end();
   });
@@ -322,12 +356,30 @@ async function probeCompanion(session2) {
 var ownedChild = null;
 async function ensureCompanion(projectDir2) {
   const existing = findSession(projectDir2);
-  if (existing && await probeCompanion(existing.session)) {
-    process.stderr.write(
-      `[insitue-mcp] reusing companion at :${existing.session.port} (pid ${existing.session.pid})
+  if (existing) {
+    const companionVersion = await probeCompanion(existing.session);
+    if (companionVersion !== null) {
+      if (semverGte(companionVersion, MIN_COMPANION)) {
+        process.stderr.write(
+          `[insitue-mcp] reusing companion at :${existing.session.port} (pid ${existing.session.pid}, v${companionVersion})
 `
-    );
-    return existing.session;
+        );
+        return existing.session;
+      }
+      process.stderr.write(
+        `[insitue-mcp] replacing stale companion (v${companionVersion} < ${MIN_COMPANION})
+`
+      );
+      try {
+        process.kill(existing.session.pid);
+      } catch {
+      }
+      const sessionPath = join3(projectDir2, ".insitue", "session.json");
+      try {
+        rmSync(sessionPath);
+      } catch {
+      }
+    }
   }
   process.stderr.write(
     `[insitue-mcp] starting companion via \`npx -y @insitue/companion@latest dev\` in ${projectDir2}\u2026
@@ -947,7 +999,7 @@ server.registerTool(
               source,
               url,
               consoleErrors,
-              instructions: "Read the source file around the line, reproduce the issue from the description, make the fix, open a PR, then call resolve_cloud_issue with the PR url."
+              instructions: 'FIRST, echo the exact issue note verbatim to the developer before any analysis or edits: output "**Fixing locally:** <note>" followed by "(Source: <file>:<line>)" so they can confirm what is being acted on. THEN read the source file around the line, reproduce the issue from the description, make the fix, open a PR, then call resolve_cloud_issue with the PR url.'
             })
           }
         ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@insitue/claude-plugin",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Drive Claude (Code AND Desktop) from the InSitue browser overlay — pick an element in your app, claude reads the file and proposes the edit.",
   "keywords": [
     "insitue",