feat: gate sidebar chat behind --chat flag

$B connect (default): headed Chromium + extension with Activity + Refs
tabs only. No separate agent spawned. Clean, no confusion.

$B connect --chat: same + Chat tab with standalone claude -p agent.
Shows experimental banner: "Standalone mode — this is a separate
agent from your workspace."

Implementation:
- cli.ts: parse --chat, set BROWSE_SIDEBAR_CHAT env, conditionally
  spawn sidebar-agent
- server.ts: gate /sidebar-* routes behind chatEnabled, return 403
  when disabled, include chatEnabled in /health response
- sidepanel.js: applyChatEnabled() hides/shows Chat tab + banner
- background.js: forward chatEnabled from health response
- sidepanel.html/css: experimental banner with amber styling

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.agents/skills/gstack-browse/SKILL.md

@@ -469,9 +469,9 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`.
 ### Server
 | Command | Description |
 |---------|-------------|
-| `connect [browser] [--port N]` | Connect to real Chrome/Comet browser via CDP |
-| `disconnect` | Disconnect from real browser, return to headless mode |
-| `focus [@ref]` | Bring connected browser window to foreground (macOS) |
+| `connect` | Launch headed Chromium with Chrome extension |
+| `disconnect` | Disconnect headed browser, return to headless mode |
+| `focus [@ref]` | Bring headed browser window to foreground (macOS) |
 | `handoff [message]` | Open visible Chrome at current page for user takeover |
 | `restart` | Restart server |
 | `resume` | Re-snapshot after user takeover, return control to AI |

.agents/skills/gstack/SKILL.md

@@ -597,9 +597,9 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`.
 ### Server
 | Command | Description |
 |---------|-------------|
-| `connect [browser] [--port N]` | Connect to real Chrome/Comet browser via CDP |
-| `disconnect` | Disconnect from real browser, return to headless mode |
-| `focus [@ref]` | Bring connected browser window to foreground (macOS) |
+| `connect` | Launch headed Chromium with Chrome extension |
+| `disconnect` | Disconnect headed browser, return to headless mode |
+| `focus [@ref]` | Bring headed browser window to foreground (macOS) |
 | `handoff [message]` | Open visible Chrome at current page for user takeover |
 | `restart` | Restart server |
 | `resume` | Re-snapshot after user takeover, return control to AI |

browse/src/cli.ts

@@ -391,14 +391,19 @@ Refs:           After 'snapshot', use @e1, @e2... as selectors:
     // Delete stale state file
     try { fs.unlinkSync(config.stateFile); } catch {}
 
-    console.log('Launching headed Chromium with extension...');
+    const chatMode = commandArgs.includes('--chat');
+    console.log(chatMode
+      ? 'Launching headed Chromium with extension + standalone chat (experimental)...'
+      : 'Launching headed Chromium with extension...');
     try {
       // Start server in headed mode with extension auto-loaded
       // Use a well-known port so the Chrome extension auto-connects
-      const newState = await startServer({
+      const serverEnv: Record<string, string> = {
         BROWSE_HEADED: '1',
         BROWSE_PORT: '34567',
-      });
+      };
+      if (chatMode) serverEnv.BROWSE_SIDEBAR_CHAT = '1';
+      const newState = await startServer(serverEnv);
 
       // Print connected status
       const resp = await fetch(`http://127.0.0.1:${newState.port}/command`, {
@@ -413,29 +418,31 @@ Refs:           After 'snapshot', use @e1, @e2... as selectors:
       const status = await resp.text();
       console.log(`Connected to real Chrome\n${status}`);
 
-      // Auto-start sidebar agent (non-compiled bun process)
-      const agentScript = path.resolve(__dirname, 'sidebar-agent.ts');
-      const agentLogFile = path.join(process.env.HOME || '/tmp', '.gstack', 'sidebar-agent.log');
-      try {
-        // Clear old agent queue
-        const agentQueue = path.join(process.env.HOME || '/tmp', '.gstack', 'sidebar-agent-queue.jsonl');
-        try { fs.writeFileSync(agentQueue, ''); } catch {}
+      // Auto-start sidebar agent only when --chat is enabled
+      if (chatMode) {
+        const agentScript = path.resolve(__dirname, 'sidebar-agent.ts');
+        const agentLogFile = path.join(process.env.HOME || '/tmp', '.gstack', 'sidebar-agent.log');
+        try {
+          // Clear old agent queue
+          const agentQueue = path.join(process.env.HOME || '/tmp', '.gstack', 'sidebar-agent-queue.jsonl');
+          try { fs.writeFileSync(agentQueue, ''); } catch {}
 
-        const agentProc = Bun.spawn(['bun', 'run', agentScript], {
-          cwd: config.projectDir,
-          env: {
-            ...process.env,
-            BROWSE_BIN: path.resolve(__dirname, '..', 'dist', 'browse'),
-            BROWSE_STATE_FILE: config.stateFile,
-            BROWSE_SERVER_PORT: String(newState.port),
-          },
-          stdio: ['ignore', 'ignore', 'ignore'],
-        });
-        agentProc.unref();
-        console.log(`[browse] Sidebar agent started (PID: ${agentProc.pid})`);
-      } catch (err: any) {
-        console.error(`[browse] Sidebar agent failed to start: ${err.message}`);
-        console.error(`[browse] Run manually: bun run ${agentScript}`);
+          const agentProc = Bun.spawn(['bun', 'run', agentScript], {
+            cwd: config.projectDir,
+            env: {
+              ...process.env,
+              BROWSE_BIN: path.resolve(__dirname, '..', 'dist', 'browse'),
+              BROWSE_STATE_FILE: config.stateFile,
+              BROWSE_SERVER_PORT: String(newState.port),
+            },
+            stdio: ['ignore', 'ignore', 'ignore'],
+          });
+          agentProc.unref();
+          console.log(`[browse] Sidebar agent started (PID: ${agentProc.pid})`);
+        } catch (err: any) {
+          console.error(`[browse] Sidebar agent failed to start: ${err.message}`);
+          console.error(`[browse] Run manually: bun run ${agentScript}`);
+        }
       }
     } catch (err: any) {
       console.error(`[browse] Connect failed: ${err.message}`);

browse/src/server.ts

@@ -36,6 +36,7 @@ ensureStateDir(config);
 const AUTH_TOKEN = crypto.randomUUID();
 const BROWSE_PORT = parseInt(process.env.BROWSE_PORT || '0', 10);
 const IDLE_TIMEOUT_MS = parseInt(process.env.BROWSE_IDLE_TIMEOUT || '1800000', 10); // 30 min
+const chatEnabled = process.env.BROWSE_SIDEBAR_CHAT === '1';
 
 function validateAuth(req: Request): boolean {
   const header = req.headers.get('authorization');
@@ -775,6 +776,7 @@ async function start() {
           tabs: browserManager.getTabCount(),
           currentUrl: browserManager.getCurrentUrl(),
           token: AUTH_TOKEN,  // Extension uses this for Bearer auth
+          chatEnabled,
           agent: {
             status: agentStatus,
             runningFor: agentStartTime ? Date.now() - agentStartTime : null,
@@ -873,6 +875,14 @@ async function start() {
 
       // ─── Sidebar endpoints (auth required — token from /health) ────
 
+      // Gate all sidebar/chat routes behind --chat flag
+      if (!chatEnabled && url.pathname.startsWith('/sidebar')) {
+        return new Response(JSON.stringify({ error: 'Chat not enabled. Use: $B connect --chat' }), {
+          status: 403,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+
       // Sidebar chat history — read from in-memory buffer
       if (url.pathname === '/sidebar-chat') {
         if (!validateAuth(req)) {

extension/background.js

@@ -46,7 +46,8 @@ async function checkHealth() {
     if (data.status === 'healthy') {
       // Capture auth token from health response
       if (data.token) authToken = data.token;
-      setConnected(data);
+      // Forward chatEnabled so sidepanel can show/hide chat tab
+      setConnected({ ...data, chatEnabled: !!data.chatEnabled });
     } else {
       setDisconnected();
     }

extension/sidepanel.css

@@ -684,6 +684,19 @@ footer {
 }
 .port-input:focus { border-color: var(--amber-500); }
 
+/* ─── Experimental Banner ─────────────────────────────── */
+.experimental-banner {
+  background: rgba(245, 158, 11, 0.15);
+  border: 1px solid rgba(245, 158, 11, 0.3);
+  color: #F59E0B;
+  padding: 8px 12px;
+  border-radius: 6px;
+  font-size: 12px;
+  margin: 8px 12px;
+  text-align: center;
+  flex-shrink: 0;
+}
+
 /* ─── Accessibility ───────────────────────────────────── */
 :focus-visible {
   outline: 2px solid var(--amber-500);

extension/sidepanel.html

@@ -48,6 +48,11 @@
     <div class="refs-footer" id="refs-footer"></div>
   </main>
 
+  <!-- Experimental chat banner (shown when chatEnabled) -->
+  <div id="experimental-banner" class="experimental-banner" style="display: none;">
+    &#x26A0; Standalone mode &mdash; this is a separate agent from your workspace
+  </div>
+
   <!-- Command Bar -->
   <div class="command-bar">
     <input type="text" class="command-input" id="command-input" placeholder="Message Claude Code..." autocomplete="off" spellcheck="false">

extension/sidepanel.js

@@ -612,6 +612,7 @@ chrome.runtime.onMessage.addListener((msg) => {
     if (msg.data) {
       const url = `http://127.0.0.1:${msg.data.port || 34567}`;
       updateConnection(url, msg.data.token);
+      applyChatEnabled(!!msg.data.chatEnabled);
     } else {
       updateConnection(null);
     }
@@ -622,3 +623,39 @@ chrome.runtime.onMessage.addListener((msg) => {
     }
   }
 });
+
+// ─── Chat Gate ──────────────────────────────────────────────────
+// Show/hide Chat tab + command bar based on chatEnabled from server
+
+function applyChatEnabled(enabled) {
+  const commandBar = document.querySelector('.command-bar');
+  const chatTab = document.getElementById('tab-chat');
+  const banner = document.getElementById('experimental-banner');
+  const clearBtn = document.getElementById('clear-chat');
+
+  if (enabled) {
+    // Chat is enabled: show command bar, chat tab, experimental banner
+    if (commandBar) commandBar.style.display = '';
+    if (chatTab) chatTab.style.display = '';
+    if (banner) banner.style.display = '';
+    if (clearBtn) clearBtn.style.display = '';
+  } else {
+    // Chat disabled: hide command bar, chat content, clear button
+    if (commandBar) commandBar.style.display = 'none';
+    if (banner) banner.style.display = 'none';
+    if (clearBtn) clearBtn.style.display = 'none';
+    // If currently on chat tab, switch to activity
+    if (chatTab && chatTab.classList.contains('active')) {
+      chatTab.classList.remove('active');
+      // Open debug tabs and show activity
+      const debugToggle = document.getElementById('debug-toggle');
+      const debugTabs = document.getElementById('debug-tabs');
+      if (debugToggle) debugToggle.classList.add('active');
+      if (debugTabs) debugTabs.style.display = 'flex';
+      const activityTab = document.getElementById('tab-activity');
+      if (activityTab) activityTab.classList.add('active');
+      const activityBtn = document.querySelector('.tab[data-tab="activity"]');
+      if (activityBtn) activityBtn.classList.add('active');
+    }
+  }
+}