@insitue/claude-plugin 0.7.2 → 0.7.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "insitue",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "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,15 @@
 # @insitue/claude-plugin
 
+## 0.7.4
+
+- **`/insitue:connect` no longer blocks the session.** In poll mode the agent silently re-looped `next_pick` forever, freezing the chat (queued messages never processed). It now polls once then hands control back, drains buffered picks on your next message, and points you at channel mode (`--dangerously-load-development-channels --channels plugin:insitue`) for truly hands-free background picks.
+- **Brand the sign-in success page.** The loopback login success page uses the brand purple gradient heading instead of the off-brand green.
+
+## 0.7.3
+
+- **Device-flow login for SSH/remote.** `/insitue:login` (+ `authenticate` tool) auto-detects an SSH session and uses a device flow: shows a verification URL + pairing code to approve in any browser; `complete_authentication` polls for the token. `login --device` forces it. Loopback stays the default locally.
+- **Project-scope awareness.** Persists the token scope; cloud errors guide you to re-login for the current project when scoped elsewhere.
+
 ## 0.7.2
 
 - **Consistent slash commands.** Removed the duplicate MCP prompts for connect/login/logout, which Claude Code surfaced as differently-named `…insitue:<name> (MCP)` entries alongside the clean `/insitue:*` slash commands. Now there is one consistent surface: `/insitue:connect`, `/insitue:disconnect`, `/insitue:login`, `/insitue:logout` (from `commands/*.md`). On Claude Desktop, use the equivalent tools (`start_session`, `authenticate`+`complete_authentication`, `logout`).

package/README.md

@@ -47,6 +47,15 @@ auto-start the InSitue companion process in the background of
 your `claude` session — no separate terminal to babysit. The
 slash command `/insitue:connect` enters the loop.
 
+The plugin ships four slash commands:
+
+| Command | What it does |
+|---|---|
+| `/insitue:connect` | Enter the pick→edit loop — receive browser picks and act on them. |
+| `/insitue:disconnect` | Leave the loop: close the WS, stop receiving picks, and kill the companion the plugin spawned. |
+| `/insitue:login` | Browser sign-in (PKCE) to InSitue Cloud, then auto-link this repo to its project. |
+| `/insitue:logout` | Revoke the token server-side and clear local credentials. |
+
 ### 1B. Claude Desktop — one-command setup
 
 Claude Desktop doesn't have a plugin marketplace, but it does
@@ -275,8 +284,8 @@ If your project uses InSitue Cloud, bug reports captured in production land in y
 
 ### Prerequisites
 
-1. **Authenticate:** run `insitue login` (from the `@insitue/companion` CLI). This stores a token at `~/.insitue/auth.json`. Get the token at <https://app.insitue.com/app/settings/developer>.
-2. **Link your project:** run `insitue link <projectId>` in your project root. The tools read the linked project from `.insitue/project.json`.
+1. **Authenticate:** run `insitue login` (from the `@insitue/companion` CLI), or `/insitue:login` inside Claude Code. Bare `insitue login` is a tokenless **browser** sign-in via PKCE — it opens your browser, prints an authorize URL + a short code to confirm, and on success prints `✓ Signed in as <login>`. Credentials are saved to `~/.insitue/auth.json`. A token minted this way from inside a repo is **project-scoped** (it can only act on that project's issues). On SSH/remote where no browser or loopback redirect is available, the flow auto-switches to the device flow — or force it with `insitue login --device`. As a CI / headless fallback, paste a Personal Access Token directly with `insitue login --token pat_live_…` (mint PATs at <https://app.insitue.com/app/settings/developer>); PATs are account-wide.
+2. **Link your project:** `insitue login` already best-effort auto-links the current repo to its InSitue project, so this is usually unnecessary. If you need to link manually, run `insitue link` (auto-detects the project from the git remote) or `insitue link <projectId>` in your project root. The tools read the linked project from `.insitue/project.json`.
 
 ### The loop
 
@@ -352,7 +361,7 @@ The plugin is a stdio MCP server that:
 
 | Tool | Purpose |
 |---|---|
-| `next_pick` | Long-poll for the next browser pick (default 25 s; max 30 min). |
+| `next_pick` | Long-poll for the next browser pick (default 8 s; max 30 min). |
 | `list_recent_picks` | Up to N buffered picks since the MCP server started. |
 | `start_session` | Returns the operating instructions + current state. Desktop entry point. |
 | `end_session` | Cleanly disconnect: close WS, suppress reconnect, kill spawned companion, drop session file. |
@@ -364,6 +373,9 @@ The plugin is a stdio MCP server that:
 | `claim_cloud_issue` | Claim an issue by `id`; returns note, source `file:line`, page URL, and top console errors. |
 | `resolve_cloud_issue` | Mark an issue resolved; attach `prUrl` and optional `branch`. |
 | `release_cloud_issue` | Return a claimed issue to the open queue. |
+| `authenticate` | Start browser sign-in (PKCE): chooses the device vs loopback flow automatically and returns the authorize URL + code to confirm. |
+| `complete_authentication` | Poll for approval (~5 min), then save credentials and best-effort auto-link the current repo to its project. |
+| `logout` | Revoke the token server-side and clear local credentials. |
 
 All file tools resolve paths against the project dir and refuse
 anything that resolves outside it (realpath-checked, so `..` games

package/commands/connect.md

@@ -64,18 +64,33 @@ your context and skip any id you've already processed.
 1. Call `mcp__insitue__list_recent_picks` once. If there are
    any picks the user made before you attached, summarise them
    ("you picked X but haven't sent a description yet — make sure
-   to click Send in the InSitue panel"). Otherwise just say
-   "Connected — pick something in the browser when you're ready.
-   You can also just type to ask me anything anytime; I'll answer
-   and keep watching, no need to cancel."
-2. Enter the loop: call `mcp__insitue__next_pick`. It long-polls
-   (~8s — deliberately short. The user can type at ANY time without
-   cancelling: Claude Code queues their message and delivers it the
-   moment this call returns, so a short poll means they wait at most
-   ~8s to reach you and never need to hit Esc). When it returns with
-   `status: "timeout"` **and the user hasn't said anything**, call it
-   again immediately without announcing it — the timeout is just a
-   heartbeat, not news. When it returns with `status: "ok"`:
+   to click Send in the InSitue panel"). Otherwise say:
+
+   > Connected. Pick an element in the browser and I'll act on it
+   > here. You can also just type to ask me anything — I'll answer
+   > right away, then keep watching.
+   >
+   > Tip: for hands-free background picks (so I act the moment you
+   > pick, without you waiting on me), relaunch with
+   > `claude --dangerously-load-development-channels --channels plugin:insitue`.
+
+2. **Watch for a pick — ONE poll, then hand control back.** Call
+   `mcp__insitue__next_pick` (it long-polls ~8s).
+   - On `status: "timeout"` (no pick this window): **STOP. Do NOT
+     silently call `next_pick` again.** Parking yourself in back-to-back
+     polls FREEZES the session — a tool call can't be interrupted, so the
+     user types a message and you never see it (this is the #1 cause of
+     "InSitue is blocking me"). Instead, end your turn and hand control
+     back with one short line, e.g.:
+
+     > 👀 Watching. Pick something in the browser, or type anything — I'll
+     > grab whatever you picked.
+
+     Then wait for the user. You resume watching on their next message
+     (step 3). In plain poll mode you catch picks when the user next
+     interacts — for truly hands-free push *between* messages, they need
+     channel mode (the tip in step 1).
+   - On `status: "ok"` (a pick arrived):
    - **Always echo the prompt back first.** Before any action,
      diff, or follow-up question, lead with:
 
@@ -105,20 +120,22 @@ your context and skip any id you've already processed.
      Don't auto-apply.
    - On approval, write with the Edit tool (Code) or
      `mcp__insitue__apply_edit` (Desktop). Confirm what changed.
-   - Loop back to `next_pick`.
-3. If `next_pick` returns `status: "timeout"`, the user simply
-   hasn't picked anything yet. Stay quiet and call `next_pick`
-   again. **Do not narrate the loop** — no "still waiting…", no
-   "polling again…". The user sees `[insitue] 📥 pick received`
-   on stderr the moment their pick lands; that's the
-   confirmation, not your narration. **The user never has to cancel
-   the watch to talk to you.** When a message from the user arrives
-   while you're watching (it queues during the poll and lands the
-   moment `next_pick` returns), STOP looping, answer it fully, and do
-   whatever they ask — then resume the watch by calling `next_pick`
-   again. Their message is the priority; the watch waits for them, not
-   the other way around. Never tell the user to cancel or re-run
-   `/insitue:connect` just to ask a question.
+   - Then call `next_pick` once more to catch a rapid follow-up pick.
+     When it times out (picks have stopped), fall back to the
+     hand-back rule above — yield to the user; do NOT loop forever.
+3. **On each user message: drain picks first, then answer, then resume.**
+   Whenever the user sends a message, before responding call `next_pick`
+   with a short `timeout_ms` (e.g. `1500`), repeatedly, until it returns
+   `status: "timeout"` — handle each pick it returns (de-dupe by `id`).
+   This catches anything the user picked while you were idle; picks are
+   buffered server-side, so nothing is lost. Then answer the user's
+   message fully and do whatever they ask. Then resume watching with a
+   single `next_pick` poll (step 2's one-poll-then-hand-back rule).
+
+   The user's message is ALWAYS the priority. Never tell them to cancel
+   or re-run `/insitue:connect` to talk to you, and never narrate the
+   watch ("still waiting…", "polling again…") — the browser already shows
+   `[insitue] 📥 pick received` the moment a pick lands.
 4. **End the session properly.** When the user says "stop",
    "done", "quit", "thanks", "exit", "disconnect", "stop
    insitue", or anything else that clearly ends the InSitue

package/commands/login.md

@@ -10,9 +10,13 @@ Cloud issues will become available via the claude-plugin tools once signed in.
 
 ## Your behaviour
 
-1. Call `mcp__insitue__authenticate` (no arguments).
+1. Call `mcp__insitue__authenticate` (no arguments). It auto-detects the
+   environment: it opens a loopback browser flow locally, and automatically
+   switches to the device flow when an SSH session is detected or no loopback
+   port is available. Branch on the returned shape:
 
-2. The tool returns `{ status: "browser_opened", url, userCode, message }`.
+2. **Loopback flow** — the tool returns
+   `{ status: "browser_opened", url, userCode, message }`.
    Show the user:
 
    > I've opened your browser to sign in to InSitue. Please:
@@ -21,11 +25,20 @@ Cloud issues will become available via the claude-plugin tools once signed in.
    >
    > (If your browser didn't open, visit this URL manually: `<url>`)
 
-   Do NOT proceed to step 3 until the user says they've approved or you
-   detect they're ready. Wait for the user to confirm.
+   **Device flow** — the tool instead returns a device-flow shape with a
+   `verificationUrl` and `userCode` (no loopback redirect). This is what you'll
+   get over SSH or when no loopback port is free. Show the user:
 
-3. Call `mcp__insitue__complete_authentication` (no arguments).
-   This waits up to 5 minutes for the browser approval.
+   > To sign in to InSitue, open this URL in any browser:
+   > **`<verificationUrl>`**
+   >
+   > Then confirm the code matches: **`<userCode>`**
+
+   In both flows, do NOT proceed to step 3 until the user says they've approved
+   or you detect they're ready. Wait for the user to confirm.
+
+3. Call `mcp__insitue__complete_authentication` (no arguments). This polls
+   for the browser approval (up to ~5 minutes) for either flow.
 
 4. On `{ status: "ok" }`:
    - If `linked: true`: reply "Signed in as **@`<login>`** and linked to

package/dist/{chunk-RS3B7P4N.js → chunk-B2OV76P2.js}

@@ -19,8 +19,8 @@ var SUCCESS_HTML = `<!DOCTYPE html>
 <head><meta charset="utf-8"><title>InSitue \u2014 signed in</title>
 <style>body{font-family:system-ui,sans-serif;display:flex;align-items:center;justify-content:center;min-height:100vh;margin:0;background:#f9fafb;}
 .card{background:#fff;border-radius:12px;padding:40px 48px;text-align:center;box-shadow:0 1px 4px rgba(0,0,0,.12);}
-h1{font-size:1.4rem;margin:0 0 8px;}p{color:#6b7280;margin:0;}</style></head>
-<body><div class="card"><h1>You're signed in to InSitue</h1>
+h1{font-size:1.4rem;margin:0 0 8px;background:linear-gradient(180deg,#6b63ff,#5751e6);-webkit-background-clip:text;background-clip:text;color:transparent;}p{color:#6b7280;margin:0;}</style></head>
+<body><div class="card"><h1>You're signed in to InSitue!</h1>
 <p>You can close this tab and return to your terminal.</p></div></body></html>`;
 var ERROR_HTML = `<!DOCTYPE html>
 <html lang="en">
@@ -34,7 +34,113 @@ function openBrowserUrl(url) {
   } catch {
   }
 }
-async function startLogin(opts) {
+function isRemoteSession() {
+  return !!(process.env["SSH_CONNECTION"] || process.env["SSH_TTY"]);
+}
+async function startDeviceFlow(opts) {
+  const { host, label, repo, openBrowser = true } = opts;
+  const { verifier, challenge } = genPkce();
+  const startRes = await fetch(`${host}/api/v1/cli/authorize/start`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      code_challenge: challenge,
+      code_challenge_method: "S256",
+      ...label ? { label } : {},
+      ...repo ? { repo } : {}
+    })
+  });
+  if (!startRes.ok) {
+    const text = await startRes.text().catch(() => "");
+    throw new Error(`authorize/start failed: HTTP ${startRes.status} ${text}`);
+  }
+  const startJson = await startRes.json();
+  const { request_id: requestId, user_code: userCode, expires_in } = startJson;
+  const verificationUrl = `${host}/cli/authorize?request_id=${encodeURIComponent(requestId)}`;
+  if (openBrowser) {
+    openBrowserUrl(verificationUrl);
+  }
+  let cancelled = false;
+  let cancelFn = null;
+  function cancel() {
+    cancelled = true;
+    if (cancelFn) cancelFn();
+  }
+  function wait() {
+    return new Promise((resolve, reject) => {
+      const timeoutMs = Math.min((expires_in ?? 600) * 1e3, 6e5);
+      let pollIntervalMs = 5e3;
+      let timer;
+      let settled = false;
+      const overallTimeout = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        if (timer) clearTimeout(timer);
+        reject(new Error("timed out waiting for device approval (10 min)"));
+      }, timeoutMs);
+      cancelFn = () => {
+        if (settled) return;
+        settled = true;
+        if (timer) clearTimeout(timer);
+        clearTimeout(overallTimeout);
+        reject(new Error("cancelled"));
+      };
+      const poll = async () => {
+        if (settled || cancelled) return;
+        try {
+          const tokenRes = await fetch(`${host}/api/v1/cli/token`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+              request_id: requestId,
+              code_verifier: verifier
+            })
+          });
+          if (tokenRes.ok) {
+            if (settled) return;
+            settled = true;
+            clearTimeout(overallTimeout);
+            const tokenJson = await tokenRes.json();
+            resolve({
+              token: tokenJson.token,
+              host: tokenJson.host,
+              login: tokenJson.login,
+              projectId: tokenJson.projectId ?? null
+            });
+            return;
+          }
+          let errBody = {};
+          try {
+            errBody = await tokenRes.json();
+          } catch {
+          }
+          const errCode = errBody.error ?? "";
+          if (errCode === "authorization_pending") {
+          } else if (errCode === "slow_down") {
+            pollIntervalMs = Math.min(pollIntervalMs + 5e3, 3e4);
+          } else {
+            if (settled) return;
+            settled = true;
+            clearTimeout(overallTimeout);
+            reject(
+              new Error(
+                errCode === "invalid_grant" ? "sign-in failed: token request rejected (invalid_grant). The request may have expired." : `sign-in failed: ${errCode || `HTTP ${tokenRes.status}`}`
+              )
+            );
+            return;
+          }
+        } catch {
+        }
+        if (!settled && !cancelled) {
+          timer = setTimeout(() => void poll(), pollIntervalMs);
+        }
+      };
+      timer = setTimeout(() => void poll(), pollIntervalMs);
+    });
+  }
+  return { authorizeUrl: verificationUrl, userCode, port: 0, wait, cancel };
+}
+async function startLoopbackFlow(opts) {
   const { host, label, repo, openBrowser = true } = opts;
   const { verifier, challenge } = genPkce();
   const state = toBase64Url(randomBytes(16));
@@ -157,6 +263,18 @@ async function startLogin(opts) {
   }
   return { authorizeUrl, userCode, port, wait, cancel };
 }
+async function startLogin(opts) {
+  const { mode, ...rest } = opts;
+  const effectiveMode = (() => {
+    if (mode === "device") return "device";
+    if (mode === "loopback") return "loopback";
+    return isRemoteSession() ? "device" : "loopback";
+  })();
+  if (effectiveMode === "device") {
+    return startDeviceFlow(rest);
+  }
+  return startLoopbackFlow(rest);
+}
 function parseRemoteToOwnerName(remote) {
   remote = remote.trim();
   const sshMatch = remote.match(

package/dist/cloud/login.js

@@ -3,7 +3,7 @@ import {
   genPkce,
   pickProjectIdForRepo,
   startLogin
-} from "../chunk-RS3B7P4N.js";
+} from "../chunk-B2OV76P2.js";
 export {
   detectGitRemote,
   genPkce,

package/dist/cloud-cli.js

@@ -16,7 +16,7 @@ import {
   detectGitRemote,
   pickProjectIdForRepo,
   startLogin
-} from "./chunk-RS3B7P4N.js";
+} from "./chunk-B2OV76P2.js";
 
 // src/cloud-cli.ts
 import { hostname } from "os";
@@ -55,14 +55,14 @@ async function cmdLogin(argv) {
     );
     return 0;
   }
+  const mode = flags.has("device") ? "device" : flags.has("loopback") ? "loopback" : "auto";
   const auth = loadAuth();
   const host = resolveHost(auth);
   const projectDir = resolveProjectDir();
   const repo = detectGitRemote(projectDir.dir);
-  process.stdout.write("Opening your browser to sign in to InSitue\u2026\n");
   let flow;
   try {
-    flow = await startLogin({ host, label: hostname(), ...repo ? { repo } : {} });
+    flow = await startLogin({ host, label: hostname(), mode, ...repo ? { repo } : {} });
   } catch (err) {
     process.stderr.write(
       `error: could not start login: ${err.message}
@@ -70,20 +70,33 @@ async function cmdLogin(argv) {
     );
     return 1;
   }
-  process.stdout.write(
-    `
+  if (mode === "device" || mode === "auto" && flow.port === 0) {
+    process.stdout.write(
+      `
+Open this URL in any browser to approve:
+  ${flow.authorizeUrl}
+Confirm the code matches: ${flow.userCode}
+
+Waiting for approval\u2026
+`
+    );
+  } else {
+    process.stdout.write("Opening your browser to sign in to InSitue\u2026\n");
+    process.stdout.write(
+      `
   Browser URL: ${flow.authorizeUrl}
   Pairing code (confirm your browser shows this): ${flow.userCode}
 
 Waiting for approval\u2026
 `
-  );
+    );
+  }
   let result;
   try {
     result = await flow.wait();
   } catch (err) {
     const msg = err.message ?? String(err);
-    if (msg === "timeout") {
+    if (msg === "timeout" || msg.startsWith("timed out")) {
       process.stderr.write("error: timed out waiting for browser approval\n");
     } else {
       process.stderr.write(`error: ${msg}
@@ -91,9 +104,13 @@ Waiting for approval\u2026
     }
     return 1;
   }
-  saveAuth({ token: result.token, host: result.host, login: result.login });
+  saveAuth({ token: result.token, host: result.host, login: result.login, projectId: result.projectId });
   process.stdout.write(`Signed in as ${result.login}.
 `);
+  if (result.projectId) {
+    process.stdout.write(`Token scoped to project ${result.projectId}.
+`);
+  }
   const projectDir2 = resolveProjectDir();
   let linkedProjectId = result.projectId ?? null;
   if (!linkedProjectId && repo) {

package/dist/mcp-server.js

@@ -26,7 +26,7 @@ import {
   detectGitRemote,
   pickProjectIdForRepo,
   startLogin
-} from "./chunk-RS3B7P4N.js";
+} from "./chunk-B2OV76P2.js";
 
 // src/mcp-server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -826,10 +826,11 @@ server.registerTool(
   }
 );
 var pendingLoginFlow = null;
+var pendingLoginIsDevice = false;
 server.registerTool(
   "authenticate",
   {
-    description: "Start a browser-based InSitue sign-in (PKCE). Opens your browser to the InSitue consent page and returns a `userCode` to visually confirm. After approving in the browser, call `complete_authentication` to finish.",
+    description: "Start an InSitue sign-in (PKCE). Auto-detects the best method: on SSH or headless environments uses device-flow (returns a URL + code for you to open in any browser); on a local machine opens your browser directly. After approving in the browser, call `complete_authentication` to finish.",
     inputSchema: {}
   },
   async () => {
@@ -839,9 +840,26 @@ server.registerTool(
     const flow = await startLogin({
       host,
       label: hostname(),
+      mode: "auto",
       ...repo ? { repo } : {}
     });
     pendingLoginFlow = flow;
+    pendingLoginIsDevice = flow.port === 0;
+    if (pendingLoginIsDevice) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              status: "device",
+              verificationUrl: flow.authorizeUrl,
+              userCode: flow.userCode,
+              message: "Open the URL in any browser, confirm the code, then I'll finish."
+            })
+          }
+        ]
+      };
+    }
     return {
       content: [
         {
@@ -894,7 +912,7 @@ server.registerTool(
           ]
         };
       }
-      saveAuth({ token: result.token, host: result.host, login: result.login });
+      saveAuth({ token: result.token, host: result.host, login: result.login, projectId: result.projectId });
       let linkedProjectId = result.projectId ?? null;
       let linked = false;
       if (!linkedProjectId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@insitue/claude-plugin",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "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",