@tiens.nguyen/gu-cli 1.0.834 → 1.0.836

package/README.md

@@ -57,7 +57,7 @@ server. After picking, `gu doctor` shows the URL and model that are actually in
 | `/model`, `/agent-model`, `/embed-model` | switch models (see above) |
 | `/context-window [tokens\|auto]` | tell gu how big the coding model's context is (hosted models cannot be probed) |
 | `/doctor` | check every configured model answers, especially the embedder |
-| `/browser` | the gu Chrome extension the agent uses to open, see and click web pages (UI tests): is it connected, and how to install it (Load unpacked from `~/.gonext/browser-extension`); setup and Chrome Web Store publishing: [browser-extension/README.md](browser-extension/README.md) |
+| `/browser [allow\|forget\|install\|cleanup]` | the agent's web browser (UI tests): it asks before first use, then works in your Chrome through the gu extension or, with nothing installed, in gu's own Chrome window; `allow`/`forget` stop or restart the question for this folder; guide: [browser-extension/README.md](browser-extension/README.md) |
 | `/tokens` | break down the last prompt sent to the coding model — how much of it was RAG |
 | `/prices [update]` | price and cache tables, and what the last turn and this session cost |
 | `/rag` | where this folder's RAG knowledge base lives: local, cloud, or both |

package/browser-bridge.mjs

@@ -17,6 +17,7 @@ import { mkdirSync, writeFileSync, readFileSync, realpathSync, unlinkSync } from
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { OwnChrome } from "./browser-chrome.mjs";
 
 export const DEFAULT_PORT = 4127;
 const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
@@ -27,7 +28,7 @@ export function statePath() {
 
 // ── WebSocket frames ────────────────────────────────────────────────────────────────────────
 export function encodeFrame(text, opcode = 1) {
-  const payload = Buffer.from(text);
+  const payload = Buffer.isBuffer(text) ? text : Buffer.from(text);
   const n = payload.length;
   const head = n < 126 ? Buffer.alloc(2) : n < 65536 ? Buffer.alloc(4) : Buffer.alloc(10);
   head[0] = 0x80 | opcode;
@@ -73,12 +74,22 @@ export function decodeFrames(buf) {
 }
 
 // ── the bridge ──────────────────────────────────────────────────────────────────────────────
-export function startBridge({ port = DEFAULT_PORT, token = randomBytes(24).toString("hex"), idleMs = 4 * 3600e3, log = () => {} } = {}) {
+const extId = (origin) => String(origin || "").replace(/^chrome-extension:\/\//, "").replace(/\/$/, "");
+
+// A refused second copy is told why with a close code it backs off on (background.js).
+export const CLOSE_OTHER_COPY = 4001;
+
+export function startBridge({ port = DEFAULT_PORT, token = randomBytes(24).toString("hex"), idleMs = 4 * 3600e3, log = () => {}, ownChrome = null } = {}) {
   let ext = null; // { socket, version }
+  // gu's own Chrome window (#150): used when the extension is not connected AND the command asks
+  // for it (backend "auto" — the agent sends that only after the user allowed the browser).
+  let own = ownChrome;
   let nextId = 1;
   const pending = new Map(); // id → { resolve, timer }
   const waiters = new Set(); // resolve() when the extension connects
   let lastUse = Date.now();
+  const refused = new Map(); // extension id → when a second copy was turned away (#148)
+  const sockets = new Set(); // every upgraded socket, so close() can end them all
 
   const hostOk = (h) => /^(127\.0\.0\.1|localhost)(:\d+)?$/i.test(String(h || ""));
 
@@ -105,6 +116,23 @@ export function startBridge({ port = DEFAULT_PORT, token = randomBytes(24).toStr
     });
   }
 
+  async function runOwn(cmd, timeoutMs) {
+    own ??= new OwnChrome({ log });
+    let timer;
+    try {
+      const result = await Promise.race([
+        own.run(cmd),
+        new Promise((_, reject) => (timer = setTimeout(() => reject(new Error(`gu's Chrome window did not answer in ${Math.round(timeoutMs / 1000)}s`)), timeoutMs))),
+      ]);
+      return { ok: true, result, backend: "chrome" };
+    } catch (e) {
+      const error = String(e?.message || e);
+      return { ok: false, error, backend: "chrome", ...(/no Chrome, Chromium/.test(error) ? { noChrome: true } : {}) };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
   function waitConnected(ms) {
     if (ext || ms <= 0) return Promise.resolve(Boolean(ext));
     return new Promise((resolve) => {
@@ -130,7 +158,16 @@ export function startBridge({ port = DEFAULT_PORT, token = randomBytes(24).toStr
     if (req.method === "GET" && url.pathname === "/status") {
       const waitMs = Math.min(Number(url.searchParams.get("wait_ms")) || 0, 60000);
       await waitConnected(waitMs);
-      return json(200, { connected: Boolean(ext), version: ext?.version || null, pid: process.pid });
+      const since = Date.now() - 5 * 60e3;
+      return json(200, {
+        connected: Boolean(ext),
+        version: ext?.version || null,
+        id: ext ? extId(ext.origin) : null,
+        installType: ext?.installType || null,
+        ownChrome: Boolean(own?.running),
+        refused: [...refused].filter(([, at]) => at > since).map(([id, at]) => ({ id, at })),
+        pid: process.pid,
+      });
     }
     if (req.method === "POST" && url.pathname === "/cmd") {
       let body = "";
@@ -142,9 +179,14 @@ export function startBridge({ port = DEFAULT_PORT, token = randomBytes(24).toStr
         return json(400, { error: "bad json" });
       }
       const timeoutMs = Math.min(Math.max(Number(cmd.timeout_ms) || 60000, 1000), 120000);
+      const backend = cmd.backend || "extension";
       delete cmd.timeout_ms;
-      const r = await send(cmd, timeoutMs);
-      return json(r.notConnected ? 503 : 200, r);
+      delete cmd.backend;
+      if (ext || backend !== "auto" || ["status", "uninstall_self"].includes(cmd.action)) {
+        const r = await send(cmd, timeoutMs);
+        return json(r.notConnected ? 503 : 200, { ...r, backend: "extension" });
+      }
+      return json(200, await runOwn(cmd, timeoutMs));
     }
     json(404, { error: "not found" });
   });
@@ -156,11 +198,26 @@ export function startBridge({ port = DEFAULT_PORT, token = randomBytes(24).toStr
       socket.end("HTTP/1.1 403 Forbidden\r\n\r\n");
       return;
     }
+    socket.setNoDelay(true);
+    sockets.add(socket);
+    socket.on("close", () => sockets.delete(socket));
     const accept = createHash("sha1").update(key + WS_GUID).digest("base64");
     socket.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n\r\n`);
-    socket.setNoDelay(true);
-    if (ext) ext.socket.destroy(); // the newest extension wins (Chrome restarted it)
-    ext = { socket, version: null, origin };
+    // ONE EXTENSION AT A TIME (#148). The same one reconnecting (Chrome restarted its worker)
+    // replaces the old socket. A DIFFERENT one — a developer copy next to the store copy — is
+    // turned away: with "newest wins" the two took the connection from each other every 3 s.
+    if (ext && !ext.socket.destroyed && ext.origin !== origin) {
+      refused.set(extId(origin), Date.now());
+      log(`refused a second gu extension (${extId(origin)}) — ${extId(ext.origin)} is connected`);
+      const reason = Buffer.from("another gu extension is connected");
+      const code = Buffer.alloc(2);
+      code.writeUInt16BE(CLOSE_OTHER_COPY);
+      socket.end(encodeFrame(Buffer.concat([code, reason]), 8));
+      setTimeout(() => socket.destroy(), 1000).unref();
+      return;
+    }
+    if (ext) ext.socket.destroy();
+    ext = { socket, version: null, installType: null, origin };
     log(`extension connected (${origin})`);
     let buf = Buffer.alloc(0);
     let parts = [];
@@ -189,7 +246,10 @@ export function startBridge({ port = DEFAULT_PORT, token = randomBytes(24).toStr
           continue;
         }
         if (msg.type === "hello") {
-          if (ext?.socket === socket) ext.version = msg.version || "?";
+          if (ext?.socket === socket) {
+            ext.version = msg.version || "?";
+            ext.installType = msg.installType || null;
+          }
           for (const w of [...waiters]) w(true);
         } else if (msg.id !== undefined && pending.has(msg.id)) {
           const p = pending.get(msg.id);
@@ -208,7 +268,7 @@ export function startBridge({ port = DEFAULT_PORT, token = randomBytes(24).toStr
       log("idle — exiting");
       server.close();
       clearInterval(idle);
-      if (ext) ext.socket.destroy();
+      for (const so of sockets) so.destroy();
       server.emit("idle-exit");
     }
   }, Math.min(idleMs, 60000));
@@ -224,7 +284,8 @@ export function startBridge({ port = DEFAULT_PORT, token = randomBytes(24).toStr
         connected: () => Boolean(ext),
         close: () => {
           clearInterval(idle);
-          if (ext) ext.socket.destroy();
+          for (const so of sockets) so.destroy();
+          server.closeAllConnections?.();
           return new Promise((r) => server.close(() => r()));
         },
       });

package/browser-command.mjs

@@ -4,14 +4,15 @@
 // package: an update moves the package and Chrome would lose an unpacked extension loaded there.
 // The files are copied there (again after an update) every time this runs, as the agent does.
 import { spawn } from "node:child_process";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, openSync, closeSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, openSync, closeSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { sameProcess } from "./proc-identity.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 export const EXT_SRC = join(HERE, "browser-extension");
-export const EXT_FILES = ["manifest.json", "background.js", "popup.html", "popup.js", "icons/icon16.png", "icons/icon48.png", "icons/icon128.png"];
+export const EXT_FILES = ["manifest.json", "background.js", "actions.js", "popup.html", "popup.js", "icons/icon16.png", "icons/icon48.png", "icons/icon128.png"];
 
 const dataDir = () => join(homedir(), ".gonext");
 export const extensionDir = () => process.env.GU_BROWSER_EXT_DIR || join(dataDir(), "browser-extension");
@@ -72,45 +73,238 @@ export async function bridgeStatus({ start = true, waitMs = 1500 } = {}) {
   return { running: false, connected: false };
 }
 
-export function browserReport({ connected, version, running }, folder, platform = process.platform) {
+// The Chrome Web Store page of the gu extension, once published (#149/#150). Empty until then.
+export const STORE_URL = process.env.GU_BROWSER_STORE_URL || "";
+
+// "Always allow the browser in this folder" (#150) — the agent reads the same file
+// (gu_browser.allowed_in) before it asks.
+const allowPath = () => join(dirname(statePath()), "browser-allow.json");
+const real = (p) => {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+};
+export function allowedIn(folder) {
+  try {
+    return (JSON.parse(readFileSync(allowPath(), "utf8")).folders || []).includes(real(folder));
+  } catch {
+    return false;
+  }
+}
+export function allowIn(folder, allow = true) {
+  let folders = [];
+  try {
+    folders = JSON.parse(readFileSync(allowPath(), "utf8")).folders || [];
+  } catch {
+    /* none yet */
+  }
+  const f = real(folder);
+  folders = [...folders.filter((x) => x !== f), ...(allow ? [f] : [])];
+  mkdirSync(dirname(allowPath()), { recursive: true });
+  writeFileSync(allowPath(), JSON.stringify({ folders }, null, 2));
+}
+
+export function browserReport({ connected, version, installType, refused = [] }, { allowed = false } = {}) {
+  // Two copies installed (the store one next to a developer one): the bridge kept one (#148).
+  const twoCopies = refused.length
+    ? [`⚠ A second gu extension (${refused.map((r) => r.id).join(", ")}) tried to connect and was`,
+      "⚠ turned away — two copies are installed. Keep one: /browser cleanup removes",
+      "⚠ the developer (unpacked) copy."]
+    : [];
+  const here = allowed
+    ? "In this folder it may, without asking (/browser forget to undo)."
+    : "In this folder it asks first (/browser allow to stop asking).";
   if (connected) {
+    const kind = installType === "development" ? ", developer — loaded unpacked" : installType === "normal" ? ", Chrome Web Store" : "";
     return [
-      `✓ The gu Chrome extension is connected (v${version}).`,
-      "The agent can open and use web pages in its own tabs (the \"gu\" tab",
-      "group) to test a UI, click through a flow or fill a form.",
-      "Your other tabs are never touched.",
+      `✓ The gu Chrome extension is connected (v${version}${kind}).`,
+      "The agent uses your Chrome, in its own tabs (the \"gu\" tab group) and tabs",
+      "you share from the extension's icon → Let gu use this tab.",
+      here,
+      ...twoCopies,
     ];
   }
+  return [
+    "Nothing to install. When the agent needs a browser it asks you first, then",
+    "opens gu's own Chrome window (a separate profile — not signed in to your",
+    "accounts) and works in it with a real mouse and keyboard.",
+    STORE_URL
+      ? `To let it use YOUR Chrome (your logins, a tab you share): ${STORE_URL}`
+      : "To let it use YOUR Chrome (your logins, a tab you share): /browser install",
+    here,
+    ...twoCopies,
+  ];
+}
+
+// /browser install — the extension, for the user's own Chrome. The store page when there is one;
+// until then the developer way (Developer mode → Load unpacked).
+export function installSteps(folder, platform = process.platform) {
+  if (STORE_URL) {
+    return [`Open ${STORE_URL} in Chrome and click "Add to Chrome".`, "Then type /browser — it should say connected."];
+  }
   const pick = platform === "darwin"
     ? ["     In the file dialog press ⌘⇧G, paste the folder (it is on your", "     clipboard) and press Enter."]
     : ["     In the file dialog type or paste the folder (it starts with a dot,", "     so it is hidden)."];
   return [
-    running ? "The gu Chrome extension is not connected." : "The gu browser bridge could not start (is node working?).",
-    "The agent uses it to open, see and click web pages like a person.",
-    "To install it:",
+    "The gu extension is not on the Chrome Web Store yet, so it is added the",
+    "developer way (you do not need it — gu's own window works without):",
     "  1. Open Chrome and go to chrome://extensions",
     "  2. Turn on Developer mode (top right)",
     "  3. Click \"Load unpacked\" and choose this folder:",
     `       ${folder}`,
     ...pick,
-    "  4. Type /browser again — it should say connected.",
-    "Already installed? Open Chrome: it reconnects within 30 seconds",
-    "(or click the extension's icon → Connect now).",
+    "  4. Type /browser — it should say connected.",
   ];
 }
 
+// macOS: open Chrome's extensions page. → whether it was opened.
+export function openExtensionsPage(platform = process.platform) {
+  // GU_NO_OPEN_APPS: the terminal tests, which must not open the real Chrome of whoever runs them.
+  if (platform !== "darwin" || process.env.GU_NO_OPEN_APPS || !existsSync("/Applications/Google Chrome.app")) return false;
+  try {
+    spawn("open", ["-a", "Google Chrome", "chrome://extensions"], { stdio: "ignore", detached: true }).unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // macOS: put the folder on the clipboard and open the extensions page, so step 3 is a paste.
 export function helpInstall(folder, platform = process.platform) {
-  if (platform !== "darwin") return false;
+  if (platform !== "darwin" || process.env.GU_NO_OPEN_APPS) return false;
   try {
     const cp = spawn("pbcopy", [], { stdio: ["pipe", "ignore", "ignore"] });
     cp.stdin.end(folder);
-    if (existsSync("/Applications/Google Chrome.app")) {
-      spawn("open", ["-a", "Google Chrome", "chrome://extensions"], { stdio: "ignore", detached: true }).unref();
-      return true;
-    }
   } catch {
     /* best effort */
   }
-  return false;
+  return openExtensionsPage(platform);
+}
+
+// ── the developer install, and cleaning it up (#145: #146 detect, #147 /browser cleanup) ──────
+const seenPath = () => join(dirname(statePath()), "browser-extension-seen");
+const logPath = () => join(dataDir(), "browser-bridge.log");
+
+// Where each Chromium browser keeps its profiles. Read only — gu never writes a browser's files.
+export function browserRoots(home = homedir(), platform = process.platform, env = process.env) {
+  const named = (list) => list.map(([browser, dir]) => ({ browser, dir }));
+  if (platform === "darwin") {
+    const a = join(home, "Library", "Application Support");
+    return named([["Chrome", join(a, "Google", "Chrome")], ["Chrome Beta", join(a, "Google", "Chrome Beta")],
+      ["Chrome Canary", join(a, "Google", "Chrome Canary")], ["Chromium", join(a, "Chromium")],
+      ["Edge", join(a, "Microsoft Edge")], ["Brave", join(a, "BraveSoftware", "Brave-Browser")]]);
+  }
+  if (platform === "win32") {
+    const l = env.LOCALAPPDATA || join(home, "AppData", "Local");
+    return named([["Chrome", join(l, "Google", "Chrome", "User Data")], ["Chrome Beta", join(l, "Google", "Chrome Beta", "User Data")],
+      ["Chrome Canary", join(l, "Google", "Chrome SxS", "User Data")], ["Chromium", join(l, "Chromium", "User Data")],
+      ["Edge", join(l, "Microsoft", "Edge", "User Data")], ["Brave", join(l, "BraveSoftware", "Brave-Browser", "User Data")]]);
+  }
+  const c = env.XDG_CONFIG_HOME || join(home, ".config");
+  return named([["Chrome", join(c, "google-chrome")], ["Chrome Beta", join(c, "google-chrome-beta")],
+    ["Chromium", join(c, "chromium")], ["Edge", join(c, "microsoft-edge")], ["Brave", join(c, "BraveSoftware", "Brave-Browser")]]);
+}
+
+const UNPACKED = new Set([4, 8]); // Chrome's Manifest::Location: UNPACKED (Load unpacked), COMMAND_LINE (--load-extension)
+
+function isGuExtension(path, entry, extDir) {
+  if (entry?.manifest?.name === "gu browser") return true;
+  if (path === extDir) return true; // the folder may already be deleted
+  try {
+    if (realpathSync(path) === realpathSync(extDir)) return true;
+  } catch {
+    /* one of them is gone */
+  }
+  try {
+    return JSON.parse(readFileSync(join(path, "manifest.json"), "utf8")).name === "gu browser";
+  } catch {
+    return false;
+  }
+}
+
+// → [{browser, profile, id, path}] for every profile with gu's extension loaded UNPACKED. A store
+// install is not listed — that is the one to keep.
+export function findDevInstalls({ roots = browserRoots(), extDir = extensionDir() } = {}) {
+  const found = [];
+  for (const { browser, dir } of roots) {
+    let profiles = [];
+    try {
+      profiles = readdirSync(dir).filter((p) => p === "Default" || /^Profile \d+$/.test(p));
+    } catch {
+      continue;
+    }
+    for (const profile of profiles) {
+      const seen = new Set();
+      for (const file of ["Secure Preferences", "Preferences"]) {
+        let settings;
+        try {
+          settings = JSON.parse(readFileSync(join(dir, profile, file), "utf8"))?.extensions?.settings || {};
+        } catch {
+          continue;
+        }
+        for (const [id, e] of Object.entries(settings)) {
+          if (seen.has(id) || !e || !UNPACKED.has(e.location) || typeof e.path !== "string") continue;
+          const path = isAbsolute(e.path) ? e.path : join(dir, profile, "Extensions", e.path);
+          if (!isGuExtension(path, e, extDir)) continue;
+          seen.add(id);
+          found.push({ browser, profile, id, path });
+        }
+      }
+    }
+  }
+  return found;
+}
+
+// gu's own leftovers of the developer install, in ~/.gonext.
+export function localLeftovers() {
+  return [extensionDir(), statePath(), seenPath(), logPath()].filter((p) => existsSync(p));
+}
+
+export async function bridgeCommand(cmd, timeoutMs = 15000) {
+  const st = readState();
+  if (!st) return { ok: false, error: "the bridge is not running" };
+  try {
+    const r = await fetch(`http://127.0.0.1:${st.port}/cmd`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${st.token}`, "content-type": "application/json" },
+      body: JSON.stringify({ ...cmd, timeout_ms: timeoutMs }),
+      signal: AbortSignal.timeout(timeoutMs + 3000),
+    });
+    return await r.json();
+  } catch (e) {
+    return { ok: false, error: String(e.message || e) };
+  }
+}
+
+/**
+ * Stop the bridge the state file names — only while that pid is still the bridge (#373, GitHub #154).
+ * The state outlives a bridge that crashed or a reboot; its pid may be someone else's by then. The
+ * bridge records `started` once it listens, so its process began at most a minute before that.
+ */
+export function stopBridge({ startOf } = {}) {
+  const st = readState();
+  if (!st?.pid) return false;
+  if (sameProcess(st.pid, st.started, { before: 60, after: 2, ...(startOf ? { startOf } : {}) }) !== "same") return false;
+  try {
+    process.kill(st.pid, "SIGTERM");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Deletes gu's files of the developer install. → the paths removed.
+export function removeLocalFiles() {
+  const gone = [];
+  for (const p of localLeftovers()) {
+    try {
+      rmSync(p, { recursive: true, force: true });
+      gone.push(p);
+    } catch {
+      /* reported by the rescan */
+    }
+  }
+  return gone;
 }

package/browser-extension/README.md

@@ -1,43 +1,75 @@
-# gu browser — Chrome extension
+# gu browser — the agent's browser
 
-The agent's `browser(...)` tool works through this extension. With it, the agent opens a web page, sees it, and clicks and types with a real mouse and keyboard, to test a UI flow or click through an app. It follows the same idea as Claude in Chrome. The task is #363 (GitHub #144).
+The agent's `browser(...)` tool opens a web page, sees it, and clicks and types with a real mouse and keyboard, to test a UI flow or click through an app. It follows the same idea as Claude in Chrome. The tasks are #363 (GitHub #144) and #369 (GitHub #150).
+
+**Nothing has to be installed.** The first time a turn uses the browser, gu asks you. After you allow it, the agent works in one of two places:
+
+- **Your own Chrome**, through this extension, if the extension is installed. The agent works in its own tabs (the "gu" tab group) and in any tab you share, and it has your logins.
+- **gu's own Chrome window**, if the extension is not installed. The bridge starts a Chrome of its own: a visible window on a separate profile (`~/.gonext/browser-profile`), started with its DevTools port open. It is not signed in to your accounts; sign in there once if a test needs it, and the profile keeps it.
 
 ```
-agent turn (python, a new process each turn)
+agent turn (python, a new process each turn) — asks you first (#150)
    │  HTTP + token        ~/.gonext/browser-bridge.json (0600)
    ▼
 browser-bridge.mjs        127.0.0.1:4127, started on demand, outlives the turn
-   │  WebSocket           only from a chrome-extension:// origin
-   ▼
-this extension            chrome.debugger → real Input.dispatchMouseEvent / insertText / key events
-   │
-   ▼
-gu's own tabs only        the tab group "gu" and the popups those tabs open
+   │                      the extension when it is connected, else gu's own window
+   ├─ WebSocket (only a chrome-extension:// origin) → this extension → chrome.debugger
+   └─ DevTools WebSocket → gu's own Chrome window (browser-chrome.mjs)
+        both run the same actions.js: real Input.dispatchMouseEvent / insertText / key events
 ```
 
-## Set up (a user)
+## Use it (a user)
+
+- **Ask gu to check a page.** The first browser call of a turn shows:
+
+  ```
+  🌐 Allow gu to use a web browser?
+    It wants to: open http://localhost:5173
+    In your Chrome if the gu extension is there, else in gu's own Chrome window.
+     ▸ Yes, this time
+       Yes, always in this folder
+       No
+  ```
+
+  "Always" adds the folder to `~/.gonext/browser-allow.json`. A "No" holds for the rest of the turn, and the model carries on without the browser.
+- **`/browser`** shows where the agent works and whether it asks in this folder.
+- **`/browser allow` / `/browser forget`** stop or restart the question for this folder.
+- **Share a tab** (extension only): click the gu icon on a tab, then **Let gu use this tab**. The tab joins the "gu" group and the agent can use it. **Stop sharing this tab** takes it back.
+- **Turning it off:** `GU_BROWSER=0` in the worker's environment removes the tool.
+
+### The extension, to use your own Chrome (optional)
+
+Chrome lets no program turn on Developer mode or load an unpacked extension, which is why the default is gu's own window.
 
-1. Install or update gu. The extension ships inside the npm package.
-2. Type `/browser` in the gu terminal. It copies the extension to `~/.gonext/browser-extension`, starts the bridge and shows whether the extension is connected. On a Mac it also opens `chrome://extensions` and puts the folder path on the clipboard.
-3. In Chrome open `chrome://extensions` and turn on **Developer mode** (top right).
-4. Click **Load unpacked** and choose `~/.gonext/browser-extension`.
-   - **Mac:** in the file dialog press ⌘⇧G and paste the path. The folder starts with a dot, so it is hidden.
-   - **Linux / Windows:** type or paste the path.
-5. Type `/browser` again. It should say `✓ The gu Chrome extension is connected`.
+- **Once the extension is on the Chrome Web Store:** `/browser install` opens its page; click **Add to Chrome**. No toggle is involved. Set `GU_BROWSER_STORE_URL`, then put the link in `STORE_URL` once it is published.
+- **Until then, the developer way** (`/browser install` shows it and copies the folder): turn on **Developer mode** in `chrome://extensions`, click **Load unpacked**, and choose `~/.gonext/browser-extension` (on a Mac, ⌘⇧G and paste). `/browser` should then say connected.
 
 Some notes:
 
-- **Why a fixed folder:** the extension is loaded from `~/.gonext/browser-extension`, not from the npm package, because an update moves the package and Chrome would lose an extension loaded from there.
-- **After a gu update:** gu copies the new files into that folder. Click the reload icon on the extension's card in `chrome://extensions`, or restart Chrome.
-- **Chrome closed or asleep:** the extension reconnects within 30 seconds of Chrome starting. The extension's icon has a **Connect now** button, and it shows a purple `on` badge while connected.
-- **When it is not connected:** the agent's tool answers `BROWSER NOT AVAILABLE` with these steps. The prompt tells the model to stop and ask you, not to work around it.
+- **Why a fixed folder:** the extension is loaded from `~/.gonext/browser-extension`, not from the npm package, because an update moves the package and Chrome would lose an extension loaded from there. After a gu update, click reload on the extension's card.
+- **Chrome closed or asleep:** the extension reconnects within 30 seconds of Chrome starting, or immediately with its icon's **Connect now** button. It shows a purple `on` badge while connected. Meanwhile the agent uses gu's own window.
 - **The "debugging this browser" bar:** Chrome shows "gu browser started debugging this browser" while the agent works. That is the `chrome.debugger` permission, which is what makes a click a real, trusted click.
-- **Other Chromium browsers** (Edge, Brave, Arc, Chromium) load it the same way from their own extensions page.
+- **Other Chromium browsers** (Edge, Brave, Arc, Chromium) load it the same way. gu's own window uses the first of Chrome, Chromium, Edge or Brave it finds; set `GU_BROWSER_CHROME` to choose.
 
-Turning it off:
+## Switch from the developer install to the store one
 
-- `GU_BROWSER=0` in the worker's environment removes the tool.
-- Removing the extension in `chrome://extensions` disconnects it.
+Run this before installing the Chrome Web Store copy (#145):
+
+```
+/browser cleanup
+```
+
+1. **It lists what it found:**
+   - every Chrome, Chrome Beta/Canary, Chromium, Edge and Brave profile with "gu browser" loaded unpacked. It reads each profile's `Preferences` and `Secure Preferences` and never writes them;
+   - the connected copy;
+   - gu's files in `~/.gonext`: `browser-extension/`, `browser-bridge.json`, `browser-extension-seen`, `browser-bridge.log`.
+2. **On "Clean up", the connected developer copy removes itself** with `chrome.management.uninstallSelf`, which needs no extra permission. A store copy is never removed this way.
+3. **Copies in other profiles need your click.** Chrome signs its profile settings, so no other program can uninstall an extension. gu opens `chrome://extensions` (on a Mac) and waits while you click Remove on "gu browser" in each one.
+4. **Then it stops the bridge, deletes gu's files, scans again,** and says either `✓ The developer install is gone` or what is still there.
+
+Once the store copy is installed, `/browser` shows `(… Chrome Web Store)` and does not copy the developer folder back. The agent's not-connected answer then says "open Chrome", not "Load unpacked".
+
+If both copies stay installed, the bridge keeps the one that connected first and turns the other away with close code 4001, and the refused copy retries every 30 s instead of every 3 s. `/browser` warns `⚠ A second gu extension … — /browser cleanup removes the developer copy`.
 
 ## Develop
 
@@ -46,7 +78,8 @@ Turning it off:
 | Bridge (frames, origin/host/token checks) | `node --test tests/browser-bridge.test.mjs` |
 | `/browser` text and file copy | `node --test tests/browser-command.test.mjs` |
 | Python client and agent turns, with a stand-in extension | `python3 -m unittest tests.test_browser` |
-| **Real Chrome**, this extension unpacked (15 checks; the click must be trusted) | see below |
+| **Real Chrome**, two copies of this extension unpacked (20 checks: the click must be trusted; one copy refused; the developer copy removes itself) | see below |
+| **Real Chrome, gu's own window** (no extension; 16 checks) | the same script with `--own` |
 
 The real-Chrome check needs **Chrome for Testing** or Chromium. Branded Chrome has ignored `--load-extension` since version 137.
 
@@ -58,7 +91,7 @@ GU_E2E_CHROME="cft/chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS
   python3 scripts/browser-e2e.py
 ```
 
-The check uses port 4127, so stop any other gu bridge first.
+The check runs on a free port, with copies of the extension pointed at that port, so a gu running on 4127 with your own Chrome is left alone.
 
 To work on the extension in your own Chrome:
 
@@ -75,6 +108,13 @@ Which files make the extension is listed in two places, and both must change tog
 
 ## Publish to the Chrome Web Store
 
+**The quick way (steps 1–2):** in the deploy app (`electric-app-deploy`), choose patch / minor / major next to **Build Chrome extension** and press it. The button:
+- raises the version in `manifest.json`;
+- checks that the scripts parse, that every file the manifest names is there, and that the bridge and `/browser` tests pass;
+- writes `release/chrome-extension/gu-browser-<version>.zip` (git-ignored) and its `.sha256` at the repo root.
+
+If any step fails, the old version is put back. The panel has **Show zip in Finder** and **Open store dashboard**. Nothing is uploaded or committed: upload the zip, then commit `manifest.json`.
+
 Publishing is optional; Load unpacked works without it. Once published, a user installs with one click, and Chrome updates the extension by itself.
 
 1. **Bump the version.** Raise `"version"` in `manifest.json`. The store refuses a version it has seen.