jupyterlab_claude_code_extension 1.2.25 → 1.2.26

package/README.md

@@ -32,6 +32,7 @@ Chat-panel extensions re-implement the agent loop and trail the real tool. This
 - **Remove** - drop a project's Claude history from the panel via the right-click menu; a confirmation dialog names the project and warns it removes the whole project and all its conversations before anything is touched, then the history folder is moved to the trash (it honours JupyterLab's "move files to trash" setting), not deleted permanently
 - **Clean up parallel sessions** - when a project has accumulated extra sessions beyond the main one, a right-click menu item (showing the count in brackets) removes them all, keeping only the main session; a confirmation dialog naming the project and the count appears first, and removed files honour the same trash setting
 - **Conversation switcher** - a right-click "Switch and Manage Sessions" submenu lists a project's other conversations by name and short session id, e.g. `home (3f2a1b9c)`, with last-activity time; pick one and it becomes the row's current conversation - the next click resumes exactly that one. The submenu shows the 5 most recent; "Manage Sessions..." opens a searchable popup - a scrollable table over the full list with the current conversation pinned at the top and accented. Conversations can also be deleted here - select one, many, or all via checkboxes, then click Delete; they move to trash immediately (no confirmation, with an "N moved to trash" message; removed files honour the trash setting). Rows with multiple conversations show a branch icon with the count after the name
+- **Open branched conversation** - a separate right-click "Open Branched Conversation" submenu (and an "Open" button on every row of the Manage Sessions popup) opens any conversation directly in its own terminal, so several branches of one project can run side by side; clicking a row reuses an open terminal only when it is already running that exact conversation, so switching a branch and clicking lands you in the right one rather than the original
 - **Branch session** - fork the current conversation into a new named session via the right-click menu (normal or skip-permissions mode); uses Claude's native `--fork-session`, opens in a new terminal, the chosen name is stamped automatically, and the fork becomes the row's current conversation
 - **Copy session id** - a right-click "Copy Session ID" item copies the row's current conversation id to the clipboard; the Manage Sessions popup adds a copy button on every row, so any parallel conversation's id is one click away
 - **Activity at a glance** - each row shows its last activity (`now`, `5m ago`, `2h ago`, `3d ago`) in an aligned column, with the favourite star in its own column beside it; rows active within the last minute light up in the theme's brand colour (including the `now` label), rows idle for over a week dim slightly

package/lib/widget.d.ts

@@ -47,6 +47,21 @@ export declare class ClaudeCodeSessionsWidget extends Widget {
     private _remove;
     private _cleanupParallel;
     private _resumeInTerminal;
+    /**
+     * Reuse an open terminal only when it is running the conversation the
+     * caller wants; otherwise launch a fresh ``claude --resume <id>``.
+     *
+     * ``strict`` selects how a cwd-matching claude terminal whose conversation
+     * is UNKNOWN (started fresh, no ``--resume`` in its argv) is treated:
+     * - lenient (row resume): reuse it. A fresh session's id is not in its
+     *   argv, so this is the only way to refocus a just-started session, and
+     *   it avoids ``claude --resume`` erroring with "already in use".
+     * - strict (Open Branched Conversation): never reuse an unknown terminal -
+     *   the user picked a specific branch and must land in THAT conversation,
+     *   so a fresh/foreign terminal is left alone and a new one is launched.
+     * A terminal whose resume id is KNOWN and differs is never reused in
+     * either mode - that is the switch-then-click bug this fixes.
+     */
     private _doResumeInTerminal;
     /** Absolute path of the file browser's current folder; falls back to the
      * server root when no file browser is available. */
@@ -143,6 +158,24 @@ export declare class ClaudeCodeSessionsWidget extends Widget {
      * The backend touches the branch JSONL's mtime; a refresh then shows
      * the selected conversation as the row's current one. */
     private _switchBranch;
+    /** Open a specific conversation branch in its own terminal.
+     *
+     * Strict reuse: only a terminal already running THIS conversation is
+     * refocused; otherwise a fresh ``claude --resume <id>`` is launched. So
+     * several branches of one project can be open independently and side by
+     * side - opening branch B never disturbs branch A's terminal. Honours the
+     * global skip-permissions toggle like a normal resume. */
+    private _openBranch;
+    /** Poll fast for a freshly forked branch to materialise, then refresh.
+     *
+     * claude writes a forked session's JSONL lazily (on its first turn), so a
+     * just-requested branch does not exist at launch and would otherwise only
+     * surface on the next 30s poll. This watches the project's branch list
+     * every ``BRANCH_WATCH_INTERVAL_MS`` until ``forkId`` appears (as current
+     * or in the list) - then does one full refresh and stops - or until a
+     * bounded number of attempts elapses. The panel is never updated before
+     * the branch genuinely exists. */
+    private _watchForBranch;
     private _startPolling;
     private _stopPolling;
     private readonly _app;
@@ -157,6 +190,7 @@ export declare class ClaudeCodeSessionsWidget extends Widget {
     private _commands;
     private _contextMenu;
     private _branchSubmenu;
+    private _openBranchSubmenu;
     private _branchSessionMenu;
     private _lastBranches;
     private _lastBranchesCurrent;

package/lib/widget.js

@@ -7,6 +7,10 @@ import { Menu, Widget } from '@lumino/widgets';
 import { requestAPI } from './request';
 import { addIcon, branchIcon, switchIcon, claudeIcon, filterIcon, refreshIcon, removeIcon, shieldIcon, starFilledIcon } from './icons';
 const POLL_INTERVAL_MS = 30000;
+// After a fork is requested, watch for its lazily-written JSONL at this fast
+// cadence (bounded) so a new branch surfaces in seconds, not on the slow poll.
+const BRANCH_WATCH_INTERVAL_MS = 2000;
+const BRANCH_WATCH_MAX_ATTEMPTS = 90; // ~3 minutes
 const DEFAULT_RECENT_LIMIT = 10;
 const EXPANDED_STORAGE_KEY = 'jupyterlab_claude_code_extension:expanded';
 const DEFAULT_PRESENTATION_MODE = 'folder';
@@ -72,7 +76,11 @@ export class ClaudeCodeSessionsWidget extends Widget {
         this._activeRowEl = null;
         this._pollHandle = null;
         this._removingPaths = new Set();
+        // Microcache of the most-recent terminal per project, tagged with the
+        // conversation it is running so reuse can tell a project's branches apart.
         this._terminalsByPath = new Map();
+        // In-flight launches, keyed per CONVERSATION (path + session id) so two
+        // different branches of one project can open independently and concurrently.
         this._pendingByPath = new Map();
         this._presentationMode = DEFAULT_PRESENTATION_MODE;
         this._recentLimit = DEFAULT_RECENT_LIMIT;
@@ -441,44 +449,75 @@ export class ClaudeCodeSessionsWidget extends Widget {
         }
     }
     // -------------------------------------------------------------- terminal
-    async _resumeInTerminal(session, forceDangerous = false) {
-        // Coalesce concurrent clicks on the same row - subsequent clicks attach
-        // to the in-flight promise instead of creating their own terminal.
-        const inFlight = this._pendingByPath.get(session.project_path);
+    async _resumeInTerminal(session, forceDangerous = false, strict = false) {
+        var _a;
+        // Coalesce concurrent clicks on the SAME conversation - subsequent clicks
+        // attach to the in-flight promise instead of creating their own terminal.
+        // The key is per-conversation, so opening a different branch of the same
+        // project launches independently rather than coalescing onto this one.
+        const key = `${session.project_path}\n${(_a = session.session_id) !== null && _a !== void 0 ? _a : ''}`;
+        const inFlight = this._pendingByPath.get(key);
         if (inFlight) {
             return inFlight;
         }
-        const promise = this._doResumeInTerminal(session, forceDangerous).finally(() => {
-            this._pendingByPath.delete(session.project_path);
+        const promise = this._doResumeInTerminal(session, forceDangerous, strict).finally(() => {
+            this._pendingByPath.delete(key);
         });
-        this._pendingByPath.set(session.project_path, promise);
+        this._pendingByPath.set(key, promise);
         return promise;
     }
-    async _doResumeInTerminal(session, forceDangerous) {
+    /**
+     * Reuse an open terminal only when it is running the conversation the
+     * caller wants; otherwise launch a fresh ``claude --resume <id>``.
+     *
+     * ``strict`` selects how a cwd-matching claude terminal whose conversation
+     * is UNKNOWN (started fresh, no ``--resume`` in its argv) is treated:
+     * - lenient (row resume): reuse it. A fresh session's id is not in its
+     *   argv, so this is the only way to refocus a just-started session, and
+     *   it avoids ``claude --resume`` erroring with "already in use".
+     * - strict (Open Branched Conversation): never reuse an unknown terminal -
+     *   the user picked a specific branch and must land in THAT conversation,
+     *   so a fresh/foreign terminal is left alone and a new one is launched.
+     * A terminal whose resume id is KNOWN and differs is never reused in
+     * either mode - that is the switch-then-click bug this fixes.
+     */
+    async _doResumeInTerminal(session, forceDangerous, strict) {
+        var _a;
         try {
-            // Always prefer reusing an open terminal for this project. The
+            // Always prefer reusing an open terminal for this conversation. The
             // skip-permissions flag can only be applied to a fresh pty, never
             // retroactively. So if the user wants dangerous mode but an open
             // terminal already exists, show a modal asking them to close it
             // first - we won't auto-close, won't silently reuse the wrong mode.
-            // 1. In-memory microcache.
+            // 1. In-memory microcache (most-recent terminal for this project).
             const cached = this._terminalsByPath.get(session.project_path);
-            if (cached && !cached.isDisposed) {
-                if (forceDangerous) {
-                    await this._showCloseExistingDialog();
+            if (cached && !cached.widget.isDisposed) {
+                const sameConversation = cached.sessionId === session.session_id;
+                const unknownConversation = !cached.sessionId;
+                if (sameConversation || (!strict && unknownConversation)) {
+                    if (forceDangerous) {
+                        await this._showCloseExistingDialog();
+                    }
+                    this._focusTerminal(cached.widget);
+                    return;
                 }
-                this._focusTerminal(cached);
-                return;
             }
             // 2. Walk every live terminal widget JL knows about.
-            const found = await this._findTerminalForCwd(session.project_path);
+            const found = await this._findTerminalForCwd(session.project_path, session.session_id, strict);
             if (found) {
-                this._terminalsByPath.set(session.project_path, found);
-                this._wireTerminalDisposal(session.project_path, found);
+                // Tag the cache with the OBSERVED conversation (null when the reused
+                // terminal is a fresh no-resume one), not the wanted id - otherwise a
+                // later strict reuse would trust a fabricated tag and focus the wrong
+                // conversation.
+                this._terminalsByPath.set(session.project_path, {
+                    widget: found.widget,
+                    sessionId: (_a = found.runningId) !== null && _a !== void 0 ? _a : undefined
+                });
+                this._wireTerminalDisposal(session.project_path, found.widget);
                 if (forceDangerous) {
                     await this._showCloseExistingDialog();
                 }
-                this._focusTerminal(found);
+                this._focusTerminal(found.widget);
                 return;
             }
             // 3. No matching terminal - spawn a new one with `claude --resume <id>`
@@ -502,7 +541,10 @@ export class ClaudeCodeSessionsWidget extends Widget {
                     name: launched.terminal_name
                 });
                 if (widget === null || widget === void 0 ? void 0 : widget.id) {
-                    this._terminalsByPath.set(session.project_path, widget);
+                    this._terminalsByPath.set(session.project_path, {
+                        widget,
+                        sessionId: session.session_id
+                    });
                     this._wireTerminalDisposal(session.project_path, widget);
                     this._focusTerminal(widget);
                 }
@@ -552,7 +594,12 @@ export class ClaudeCodeSessionsWidget extends Widget {
                 name: launched.terminal_name
             });
             if (widget === null || widget === void 0 ? void 0 : widget.id) {
-                this._terminalsByPath.set(projectPath, widget);
+                // A fresh session's conversation id is not in its argv, so leave
+                // sessionId undefined - reuse treats it as the project's current.
+                this._terminalsByPath.set(projectPath, {
+                    widget,
+                    sessionId: undefined
+                });
                 this._wireTerminalDisposal(projectPath, widget);
                 this._focusTerminal(widget);
             }
@@ -592,8 +639,8 @@ export class ClaudeCodeSessionsWidget extends Widget {
             }
         });
     }
-    async _findTerminalForCwd(projectPath) {
-        var _a, _b;
+    async _findTerminalForCwd(projectPath, wantedSessionId, strict) {
+        var _a, _b, _c;
         if (!this._terminalTracker) {
             return null;
         }
@@ -617,10 +664,25 @@ export class ClaudeCodeSessionsWidget extends Widget {
                 if (!(data === null || data === void 0 ? void 0 : data.has_claude)) {
                     continue;
                 }
+                // Conversation gate: reuse only a terminal running the wanted
+                // conversation. A known, different resume id is never reused (the
+                // switch-then-click bug). An unknown id (fresh session, no --resume)
+                // is reused in lenient mode but skipped in strict mode, where the
+                // user picked a specific branch to open.
+                const runningId = (_c = data.session_id) !== null && _c !== void 0 ? _c : null;
+                const sameConversation = runningId === wantedSessionId;
+                const unknownConversation = runningId === null;
+                if (!(sameConversation || (!strict && unknownConversation))) {
+                    continue;
+                }
                 const cwds = Array.isArray(data === null || data === void 0 ? void 0 : data.cwds) ? data.cwds : [];
                 for (const cwd of cwds) {
                     if ((cwd || '').replace(/\/+$/, '') === target) {
-                        return widget;
+                        // Return the OBSERVED running id (may be null for a fresh
+                        // terminal), never the wanted id - the caller tags its cache
+                        // with this so a later strict reuse trusts the process, not a
+                        // wish.
+                        return { widget, runningId };
                     }
                 }
             }
@@ -667,7 +729,8 @@ export class ClaudeCodeSessionsWidget extends Widget {
             return;
         }
         widget.disposed.connect(() => {
-            if (this._terminalsByPath.get(projectPath) === widget) {
+            var _a;
+            if (((_a = this._terminalsByPath.get(projectPath)) === null || _a === void 0 ? void 0 : _a.widget) === widget) {
                 this._terminalsByPath.delete(projectPath);
             }
         });
@@ -1127,6 +1190,17 @@ export class ClaudeCodeSessionsWidget extends Widget {
                 void this._showBranchPopup(this._lastBranches, this._lastBranchesCurrent);
             }
         });
+        this._commands.addCommand('claude-code-sessions:open-branch', {
+            label: args => { var _a; return String((_a = args.label) !== null && _a !== void 0 ? _a : ''); },
+            icon: terminalIcon,
+            execute: args => {
+                var _a;
+                const sessionId = String((_a = args.session_id) !== null && _a !== void 0 ? _a : '');
+                if (sessionId) {
+                    void this._openBranch(sessionId);
+                }
+            }
+        });
         this._commands.addCommand('claude-code-sessions:branch-session', {
             label: 'Normal',
             execute: () => void this._branchSession(false)
@@ -1171,6 +1245,13 @@ export class ClaudeCodeSessionsWidget extends Widget {
         this._branchSubmenu.addClass('jp-ClaudeSessionsContextMenu');
         this._branchSubmenu.title.label = 'Switch and Manage Sessions';
         this._branchSubmenu.title.icon = switchIcon;
+        // Submenu that OPENS a conversation directly in its own terminal (vs the
+        // switch submenu, which only changes which branch the row points at).
+        // Several branches can be open at once, independently.
+        this._openBranchSubmenu = new Menu({ commands: this._commands });
+        this._openBranchSubmenu.addClass('jp-ClaudeSessionsContextMenu');
+        this._openBranchSubmenu.title.label = 'Open Branched Conversation';
+        this._openBranchSubmenu.title.icon = terminalIcon;
         // Submenu grouping the two branch-session launch modes.
         this._branchSessionMenu = new Menu({ commands: this._commands });
         this._branchSessionMenu.addClass('jp-ClaudeSessionsContextMenu');
@@ -1217,6 +1298,10 @@ export class ClaudeCodeSessionsWidget extends Widget {
         });
         this._contextMenu.addItem({ type: 'separator' });
         if (withBranches) {
+            this._contextMenu.addItem({
+                type: 'submenu',
+                submenu: this._openBranchSubmenu
+            });
             this._contextMenu.addItem({
                 type: 'submenu',
                 submenu: this._branchSubmenu
@@ -1259,6 +1344,24 @@ export class ClaudeCodeSessionsWidget extends Widget {
                 this._branchSubmenu.addItem({
                     command: 'claude-code-sessions:switch-branch-more'
                 });
+                // Open submenu: same top-5 branches, but each launches its own
+                // terminal directly. Falls through to the Manage Sessions popup for
+                // the full list (from which any conversation can also be opened).
+                this._openBranchSubmenu.clearItems();
+                this._openBranchSubmenu.title.label = `Open Branched Conversation (${data.branches.length})`;
+                for (const b of data.branches.slice(0, 5)) {
+                    this._openBranchSubmenu.addItem({
+                        command: 'claude-code-sessions:open-branch',
+                        args: {
+                            session_id: b.session_id,
+                            label: `${this._branchDisplayName(b)} - ${this._formatRelativeTime(b.file_mtime)}`
+                        }
+                    });
+                }
+                this._openBranchSubmenu.addItem({ type: 'separator' });
+                this._openBranchSubmenu.addItem({
+                    command: 'claude-code-sessions:switch-branch-more'
+                });
                 hasBranches = data.branches.length > 0;
             }
             catch (_a) {
@@ -1346,6 +1449,22 @@ export class ClaudeCodeSessionsWidget extends Widget {
             body: bodyWidget,
             buttons: [Dialog.cancelButton()]
         });
+        // Per-row "Open" launches that conversation in its own terminal (strict
+        // reuse via _openBranch) and closes the popup. stopPropagation keeps the
+        // click from toggling selection or switching the row.
+        const openButton = (sessionId) => {
+            const btn = document.createElement('button');
+            btn.type = 'button';
+            btn.className = 'jp-ClaudeSessionsPanel-branchOpen';
+            btn.textContent = 'Open';
+            btn.title = 'Open this conversation in its own terminal';
+            btn.addEventListener('click', e => {
+                e.stopPropagation();
+                dialog.dispose();
+                void this._openBranch(sessionId);
+            });
+            return btn;
+        };
         const visibleMatches = () => {
             const needle = search.value.trim().toLowerCase();
             return items.filter(b => !needle ||
@@ -1393,6 +1512,7 @@ export class ClaudeCodeSessionsWidget extends Widget {
             badge.className = 'jp-ClaudeSessionsPanel-branchCurrentBadge';
             badge.textContent = 'current';
             currentRow.appendChild(badge);
+            currentRow.appendChild(openButton(current));
             currentRow.appendChild(this._branchCopyButton(current));
             list.appendChild(currentRow);
             const matches = visibleMatches();
@@ -1450,6 +1570,7 @@ export class ClaudeCodeSessionsWidget extends Widget {
                 time.className = 'jp-ClaudeSessionsPanel-branchTime';
                 time.textContent = this._formatRelativeTime(b.file_mtime);
                 row.appendChild(time);
+                row.appendChild(openButton(b.session_id));
                 row.appendChild(this._branchCopyButton(b.session_id));
                 row.addEventListener('click', () => {
                     // Selection mode: while anything is ticked, row clicks toggle
@@ -1660,7 +1781,12 @@ export class ClaudeCodeSessionsWidget extends Widget {
                 name: launched.terminal_name
             });
             if (widget === null || widget === void 0 ? void 0 : widget.id) {
-                this._terminalsByPath.set(session.project_path, widget);
+                // The terminal runs the FORK (forkId), so tag it with that id - a
+                // later click on the now-current forked row reuses this terminal.
+                this._terminalsByPath.set(session.project_path, {
+                    widget,
+                    sessionId: forkId
+                });
                 this._wireTerminalDisposal(session.project_path, widget);
                 this._focusTerminal(widget);
             }
@@ -1673,8 +1799,10 @@ export class ClaudeCodeSessionsWidget extends Widget {
             spinner.dispose();
         }
         // No post-hoc title write: claude owns the name via ``-n`` and stamps it
-        // on the fork's first turn. The branch surfaces on the next poll once
-        // claude materialises its JSONL.
+        // on the fork's first turn. claude materialises the fork's JSONL lazily,
+        // so watch for it at a fast cadence and refresh the moment it appears -
+        // the branch surfaces in seconds instead of on the next slow poll.
+        this._watchForBranch(session.encoded_path, forkId);
     }
     /** Switch the active row's project to another conversation branch.
      * The backend touches the branch JSONL's mtime; a refresh then shows
@@ -1709,6 +1837,60 @@ export class ClaudeCodeSessionsWidget extends Widget {
             await this._fetch();
         }
     }
+    /** Open a specific conversation branch in its own terminal.
+     *
+     * Strict reuse: only a terminal already running THIS conversation is
+     * refocused; otherwise a fresh ``claude --resume <id>`` is launched. So
+     * several branches of one project can be open independently and side by
+     * side - opening branch B never disturbs branch A's terminal. Honours the
+     * global skip-permissions toggle like a normal resume. */
+    async _openBranch(sessionId) {
+        const active = this._activeSession;
+        if (!active || !sessionId) {
+            return;
+        }
+        // Opening the row's CURRENT conversation behaves like a normal row resume
+        // (lenient): a fresh terminal already running it is reused, avoiding a
+        // `claude --resume` "already in use" collision. Opening a DIFFERENT branch
+        // is strict so the user lands in that specific conversation, even if some
+        // other (fresh) terminal sits at the same cwd.
+        const strict = sessionId !== active.session_id;
+        await this._resumeInTerminal({ ...active, session_id: sessionId }, false, strict);
+    }
+    /** Poll fast for a freshly forked branch to materialise, then refresh.
+     *
+     * claude writes a forked session's JSONL lazily (on its first turn), so a
+     * just-requested branch does not exist at launch and would otherwise only
+     * surface on the next 30s poll. This watches the project's branch list
+     * every ``BRANCH_WATCH_INTERVAL_MS`` until ``forkId`` appears (as current
+     * or in the list) - then does one full refresh and stops - or until a
+     * bounded number of attempts elapses. The panel is never updated before
+     * the branch genuinely exists. */
+    _watchForBranch(encodedPath, forkId) {
+        let attempts = 0;
+        const tick = async () => {
+            if (this.isDisposed) {
+                return;
+            }
+            attempts += 1;
+            try {
+                const data = await requestAPI(`sessions/branches?encoded_path=${encodeURIComponent(encodedPath)}`, this._serverSettings, { cache: 'no-store' });
+                const appeared = data.current === forkId ||
+                    data.branches.some(b => b.session_id === forkId);
+                if (appeared) {
+                    await this._fetch();
+                    return;
+                }
+            }
+            catch (_a) {
+                // Transient failure - keep watching until the attempt budget runs out.
+            }
+            if (attempts < BRANCH_WATCH_MAX_ATTEMPTS) {
+                window.setTimeout(() => void tick(), BRANCH_WATCH_INTERVAL_MS);
+            }
+        };
+        window.setTimeout(() => void tick(), BRANCH_WATCH_INTERVAL_MS);
+    }
     // --------------------------------------------------------------- polling
     _startPolling() {
         if (this._pollHandle !== null) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "jupyterlab_claude_code_extension",
-    "version": "1.2.25",
+    "version": "1.2.26",
     "description": "Browse, resume, and manage your Claude Code CLI sessions from a JupyterLab side panel. One click reactivates the right terminal - no duplicate tabs, live remote-control indicator, and favourites for the projects you keep coming back to.",
     "keywords": [
         "jupyter",

package/src/__tests__/jupyterlab_claude_code_extension.spec.ts

@@ -506,6 +506,141 @@ describe('launch spinner dismiss contract', () => {
     });
   });
 
+  /**
+   * Contract for conversation-aware terminal reuse and the Open Branched
+   * Conversation feature. The reuse path must refuse to focus a terminal
+   * running a DIFFERENT known conversation (the switch-then-click bug), and
+   * opening a specific branch must launch its own terminal (strict) so
+   * several branches stay open independently.
+   */
+  describe('conversation-aware reuse + open-branch contract', () => {
+    const findTerm = (widgetSrc.match(
+      /private async _findTerminalForCwd[\s\S]*?\n  \}/
+    ) ?? [''])[0];
+    const doResume = (widgetSrc.match(
+      /private async _doResumeInTerminal[\s\S]*?\n  \}/
+    ) ?? [''])[0];
+    const resume = (widgetSrc.match(
+      /private async _resumeInTerminal[\s\S]*?\n  \}/
+    ) ?? [''])[0];
+    const openBranch = (widgetSrc.match(
+      /private async _openBranch[\s\S]*?\n  \}/
+    ) ?? [''])[0];
+    const watch = (widgetSrc.match(/private _watchForBranch[\s\S]*?\n  \}/) ?? [
+      ''
+    ])[0];
+
+    it('terminal-cwd response carries the running conversation id', () => {
+      const iface = (widgetSrc.match(
+        /interface ITerminalCwdResponse \{[\s\S]*?\}/
+      ) ?? [''])[0];
+      expect(iface).toMatch(/session_id\?: string \| null/);
+    });
+
+    it('_findTerminalForCwd takes the wanted id and a strict flag', () => {
+      expect(findTerm).toMatch(
+        /_findTerminalForCwd\(\s*projectPath: string,\s*wantedSessionId: string \| undefined,\s*strict: boolean/
+      );
+    });
+
+    it('reuse rejects a terminal running a known different conversation', () => {
+      // Same conversation, or unknown (fresh) only in lenient mode, may reuse.
+      expect(findTerm).toMatch(/const runningId = data\.session_id \?\? null/);
+      expect(findTerm).toMatch(
+        /sameConversation = runningId === wantedSessionId/
+      );
+      expect(findTerm).toMatch(/unknownConversation = runningId === null/);
+      expect(findTerm).toMatch(
+        /if \(!\(sameConversation \|\| \(!strict && unknownConversation\)\)\) \{\s*continue;/
+      );
+    });
+
+    it('microcache reuse is gated on the conversation id', () => {
+      expect(doResume).toMatch(/cached\.sessionId === session\.session_id/);
+      expect(doResume).toMatch(/!strict && unknownConversation/);
+    });
+
+    it('microcache is tagged with the OBSERVED running id, not the wanted one', () => {
+      // Storing the wanted id would let a later strict reuse trust a
+      // fabricated tag and focus the wrong conversation (review finding 1).
+      expect(doResume).toMatch(
+        /widget: found\.widget,\s*sessionId: found\.runningId \?\? undefined/
+      );
+      expect(findTerm).toMatch(/return \{ widget, runningId \}/);
+    });
+
+    it('in-flight launches are keyed per conversation, not per project', () => {
+      expect(resume).toMatch(
+        /const key = `\$\{session\.project_path\}\\n\$\{session\.session_id \?\? ''\}`/
+      );
+      expect(resume).toMatch(/this\._pendingByPath\.(get|set)\(key/);
+    });
+
+    it('_openBranch is strict for a different branch, lenient for the current', () => {
+      // Strict on a non-current branch lands the user in THAT conversation;
+      // lenient on the current avoids a `claude --resume` "already in use"
+      // collision with a fresh terminal already running it (review finding 2).
+      expect(openBranch).toMatch(
+        /const strict = sessionId !== active\.session_id/
+      );
+      expect(openBranch).toMatch(
+        /this\._resumeInTerminal\(\s*\{ \.\.\.active, session_id: sessionId \},\s*false,\s*strict\s*\)/
+      );
+    });
+
+    it('open-branch command and submenu are wired up', () => {
+      expect(widgetSrc).toMatch(/'claude-code-sessions:open-branch'/);
+      expect(widgetSrc).toMatch(
+        /this\._openBranchSubmenu\.title\.label = 'Open Branched Conversation'/
+      );
+      // Top 5 branches populate the open submenu, each via the open command.
+      const populate = (widgetSrc.match(
+        /this\._openBranchSubmenu\.clearItems[\s\S]*?switch-branch-more'\s*\}\);/
+      ) ?? [''])[0];
+      expect(populate).toMatch(/data\.branches\.slice\(0, 5\)/);
+      expect(populate).toMatch(/command: 'claude-code-sessions:open-branch'/);
+      // The context menu shows the open submenu when the row has branches.
+      const rebuild = (widgetSrc.match(
+        /private _rebuildContextMenu[\s\S]*?\n  \}/
+      ) ?? [''])[0];
+      expect(rebuild).toMatch(/submenu: this\._openBranchSubmenu/);
+    });
+
+    it('popup rows carry an Open button that launches the branch', () => {
+      const popup = (widgetSrc.match(
+        /private _showBranchPopup[\s\S]*?\n  \}\n/
+      ) ?? [''])[0];
+      expect(popup).toMatch(/jp-ClaudeSessionsPanel-branchOpen/);
+      expect(popup).toMatch(/void this\._openBranch\(sessionId\)/);
+      // Open appears on both the current row and each branch row.
+      expect(popup).toMatch(/openButton\(current\)/);
+      expect(popup).toMatch(/openButton\(b\.session_id\)/);
+    });
+
+    it('a new branch is watched for and surfaces fast, not on the slow poll', () => {
+      expect(watch).toMatch(/data\.current === forkId/);
+      expect(watch).toMatch(/b\.session_id === forkId/);
+      expect(watch).toMatch(/await this\._fetch\(\)/);
+      expect(watch).toMatch(/BRANCH_WATCH_MAX_ATTEMPTS/);
+      // Fork launch arms the watcher.
+      const fork = (widgetSrc.match(
+        /private async _branchSession[\s\S]*?\n  \}/
+      ) ?? [''])[0];
+      expect(fork).toMatch(
+        /this\._watchForBranch\(session\.encoded_path, forkId\)/
+      );
+      expect(widgetSrc).toMatch(/BRANCH_WATCH_INTERVAL_MS = 2_000/);
+    });
+
+    it('the Open button is styled in base.css', () => {
+      const css: string = fs.readFileSync(
+        path.join(__dirname, '..', '..', 'style', 'base.css'),
+        'utf-8'
+      );
+      expect(css).toMatch(/\.jp-ClaudeSessionsPanel-branchOpen \{/);
+    });
+  });
+
   it('_doResumeInTerminal dismisses spinner via dispose(), not resolve()', () => {
     expect(widgetSrc).toMatch(/spinner\.dispose\(\)/);
     expect(widgetSrc).not.toMatch(/spinner\.resolve\(\)/);

package/src/widget.ts

@@ -41,6 +41,10 @@ import {
 } from './types';
 
 const POLL_INTERVAL_MS = 30_000;
+// After a fork is requested, watch for its lazily-written JSONL at this fast
+// cadence (bounded) so a new branch surfaces in seconds, not on the slow poll.
+const BRANCH_WATCH_INTERVAL_MS = 2_000;
+const BRANCH_WATCH_MAX_ATTEMPTS = 90; // ~3 minutes
 const DEFAULT_RECENT_LIMIT = 10;
 const EXPANDED_STORAGE_KEY = 'jupyterlab_claude_code_extension:expanded';
 
@@ -97,6 +101,9 @@ interface ITerminalCwdResponse {
   terminal_name: string;
   cwds: string[];
   has_claude: boolean;
+  // Conversation id the running claude is resuming, or null for a fresh
+  // (non-resumed) session. Lets reuse tell branches of one project apart.
+  session_id?: string | null;
 }
 
 // Drop any pre-v0.6.18 localStorage entries from previous schemes - they
@@ -544,53 +551,90 @@ export class ClaudeCodeSessionsWidget extends Widget {
 
   private async _resumeInTerminal(
     session: ISession,
-    forceDangerous: boolean = false
+    forceDangerous: boolean = false,
+    strict: boolean = false
   ): Promise<void> {
-    // Coalesce concurrent clicks on the same row - subsequent clicks attach
-    // to the in-flight promise instead of creating their own terminal.
-    const inFlight = this._pendingByPath.get(session.project_path);
+    // Coalesce concurrent clicks on the SAME conversation - subsequent clicks
+    // attach to the in-flight promise instead of creating their own terminal.
+    // The key is per-conversation, so opening a different branch of the same
+    // project launches independently rather than coalescing onto this one.
+    const key = `${session.project_path}\n${session.session_id ?? ''}`;
+    const inFlight = this._pendingByPath.get(key);
     if (inFlight) {
       return inFlight;
     }
-    const promise = this._doResumeInTerminal(session, forceDangerous).finally(
-      () => {
-        this._pendingByPath.delete(session.project_path);
-      }
-    );
-    this._pendingByPath.set(session.project_path, promise);
+    const promise = this._doResumeInTerminal(
+      session,
+      forceDangerous,
+      strict
+    ).finally(() => {
+      this._pendingByPath.delete(key);
+    });
+    this._pendingByPath.set(key, promise);
     return promise;
   }
 
+  /**
+   * Reuse an open terminal only when it is running the conversation the
+   * caller wants; otherwise launch a fresh ``claude --resume <id>``.
+   *
+   * ``strict`` selects how a cwd-matching claude terminal whose conversation
+   * is UNKNOWN (started fresh, no ``--resume`` in its argv) is treated:
+   * - lenient (row resume): reuse it. A fresh session's id is not in its
+   *   argv, so this is the only way to refocus a just-started session, and
+   *   it avoids ``claude --resume`` erroring with "already in use".
+   * - strict (Open Branched Conversation): never reuse an unknown terminal -
+   *   the user picked a specific branch and must land in THAT conversation,
+   *   so a fresh/foreign terminal is left alone and a new one is launched.
+   * A terminal whose resume id is KNOWN and differs is never reused in
+   * either mode - that is the switch-then-click bug this fixes.
+   */
   private async _doResumeInTerminal(
     session: ISession,
-    forceDangerous: boolean
+    forceDangerous: boolean,
+    strict: boolean
   ): Promise<void> {
     try {
-      // Always prefer reusing an open terminal for this project. The
+      // Always prefer reusing an open terminal for this conversation. The
       // skip-permissions flag can only be applied to a fresh pty, never
       // retroactively. So if the user wants dangerous mode but an open
       // terminal already exists, show a modal asking them to close it
       // first - we won't auto-close, won't silently reuse the wrong mode.
 
-      // 1. In-memory microcache.
+      // 1. In-memory microcache (most-recent terminal for this project).
       const cached = this._terminalsByPath.get(session.project_path);
-      if (cached && !cached.isDisposed) {
-        if (forceDangerous) {
-          await this._showCloseExistingDialog();
+      if (cached && !cached.widget.isDisposed) {
+        const sameConversation = cached.sessionId === session.session_id;
+        const unknownConversation = !cached.sessionId;
+        if (sameConversation || (!strict && unknownConversation)) {
+          if (forceDangerous) {
+            await this._showCloseExistingDialog();
+          }
+          this._focusTerminal(cached.widget);
+          return;
         }
-        this._focusTerminal(cached);
-        return;
       }
 
       // 2. Walk every live terminal widget JL knows about.
-      const found = await this._findTerminalForCwd(session.project_path);
+      const found = await this._findTerminalForCwd(
+        session.project_path,
+        session.session_id,
+        strict
+      );
       if (found) {
-        this._terminalsByPath.set(session.project_path, found);
-        this._wireTerminalDisposal(session.project_path, found);
+        // Tag the cache with the OBSERVED conversation (null when the reused
+        // terminal is a fresh no-resume one), not the wanted id - otherwise a
+        // later strict reuse would trust a fabricated tag and focus the wrong
+        // conversation.
+        this._terminalsByPath.set(session.project_path, {
+          widget: found.widget,
+          sessionId: found.runningId ?? undefined
+        });
+        this._wireTerminalDisposal(session.project_path, found.widget);
         if (forceDangerous) {
           await this._showCloseExistingDialog();
         }
-        this._focusTerminal(found);
+        this._focusTerminal(found.widget);
         return;
       }
 
@@ -620,7 +664,10 @@ export class ClaudeCodeSessionsWidget extends Widget {
           name: launched.terminal_name
         });
         if (widget?.id) {
-          this._terminalsByPath.set(session.project_path, widget);
+          this._terminalsByPath.set(session.project_path, {
+            widget,
+            sessionId: session.session_id
+          });
           this._wireTerminalDisposal(session.project_path, widget);
           this._focusTerminal(widget);
         }
@@ -673,7 +720,12 @@ export class ClaudeCodeSessionsWidget extends Widget {
         name: launched.terminal_name
       });
       if (widget?.id) {
-        this._terminalsByPath.set(projectPath, widget);
+        // A fresh session's conversation id is not in its argv, so leave
+        // sessionId undefined - reuse treats it as the project's current.
+        this._terminalsByPath.set(projectPath, {
+          widget,
+          sessionId: undefined
+        });
         this._wireTerminalDisposal(projectPath, widget);
         this._focusTerminal(widget);
       }
@@ -711,7 +763,11 @@ export class ClaudeCodeSessionsWidget extends Widget {
     });
   }
 
-  private async _findTerminalForCwd(projectPath: string): Promise<any | null> {
+  private async _findTerminalForCwd(
+    projectPath: string,
+    wantedSessionId: string | undefined,
+    strict: boolean
+  ): Promise<{ widget: any; runningId: string | null } | null> {
     if (!this._terminalTracker) {
       return null;
     }
@@ -738,10 +794,25 @@ export class ClaudeCodeSessionsWidget extends Widget {
         if (!data?.has_claude) {
           continue;
         }
+        // Conversation gate: reuse only a terminal running the wanted
+        // conversation. A known, different resume id is never reused (the
+        // switch-then-click bug). An unknown id (fresh session, no --resume)
+        // is reused in lenient mode but skipped in strict mode, where the
+        // user picked a specific branch to open.
+        const runningId = data.session_id ?? null;
+        const sameConversation = runningId === wantedSessionId;
+        const unknownConversation = runningId === null;
+        if (!(sameConversation || (!strict && unknownConversation))) {
+          continue;
+        }
         const cwds = Array.isArray(data?.cwds) ? data.cwds : [];
         for (const cwd of cwds) {
           if ((cwd || '').replace(/\/+$/, '') === target) {
-            return widget;
+            // Return the OBSERVED running id (may be null for a fresh
+            // terminal), never the wanted id - the caller tags its cache
+            // with this so a later strict reuse trusts the process, not a
+            // wish.
+            return { widget, runningId };
           }
         }
       } catch (_err) {
@@ -792,7 +863,7 @@ export class ClaudeCodeSessionsWidget extends Widget {
       return;
     }
     widget.disposed.connect(() => {
-      if (this._terminalsByPath.get(projectPath) === widget) {
+      if (this._terminalsByPath.get(projectPath)?.widget === widget) {
         this._terminalsByPath.delete(projectPath);
       }
     });
@@ -1311,6 +1382,17 @@ export class ClaudeCodeSessionsWidget extends Widget {
       }
     });
 
+    this._commands.addCommand('claude-code-sessions:open-branch', {
+      label: args => String(args.label ?? ''),
+      icon: terminalIcon,
+      execute: args => {
+        const sessionId = String(args.session_id ?? '');
+        if (sessionId) {
+          void this._openBranch(sessionId);
+        }
+      }
+    });
+
     this._commands.addCommand('claude-code-sessions:branch-session', {
       label: 'Normal',
       execute: () => void this._branchSession(false)
@@ -1362,6 +1444,14 @@ export class ClaudeCodeSessionsWidget extends Widget {
     this._branchSubmenu.title.label = 'Switch and Manage Sessions';
     this._branchSubmenu.title.icon = switchIcon;
 
+    // Submenu that OPENS a conversation directly in its own terminal (vs the
+    // switch submenu, which only changes which branch the row points at).
+    // Several branches can be open at once, independently.
+    this._openBranchSubmenu = new Menu({ commands: this._commands });
+    this._openBranchSubmenu.addClass('jp-ClaudeSessionsContextMenu');
+    this._openBranchSubmenu.title.label = 'Open Branched Conversation';
+    this._openBranchSubmenu.title.icon = terminalIcon;
+
     // Submenu grouping the two branch-session launch modes.
     this._branchSessionMenu = new Menu({ commands: this._commands });
     this._branchSessionMenu.addClass('jp-ClaudeSessionsContextMenu');
@@ -1411,6 +1501,10 @@ export class ClaudeCodeSessionsWidget extends Widget {
     });
     this._contextMenu.addItem({ type: 'separator' });
     if (withBranches) {
+      this._contextMenu.addItem({
+        type: 'submenu',
+        submenu: this._openBranchSubmenu
+      });
       this._contextMenu.addItem({
         type: 'submenu',
         submenu: this._branchSubmenu
@@ -1462,6 +1556,25 @@ export class ClaudeCodeSessionsWidget extends Widget {
         this._branchSubmenu.addItem({
           command: 'claude-code-sessions:switch-branch-more'
         });
+
+        // Open submenu: same top-5 branches, but each launches its own
+        // terminal directly. Falls through to the Manage Sessions popup for
+        // the full list (from which any conversation can also be opened).
+        this._openBranchSubmenu.clearItems();
+        this._openBranchSubmenu.title.label = `Open Branched Conversation (${data.branches.length})`;
+        for (const b of data.branches.slice(0, 5)) {
+          this._openBranchSubmenu.addItem({
+            command: 'claude-code-sessions:open-branch',
+            args: {
+              session_id: b.session_id,
+              label: `${this._branchDisplayName(b)} - ${this._formatRelativeTime(b.file_mtime)}`
+            }
+          });
+        }
+        this._openBranchSubmenu.addItem({ type: 'separator' });
+        this._openBranchSubmenu.addItem({
+          command: 'claude-code-sessions:switch-branch-more'
+        });
         hasBranches = data.branches.length > 0;
       } catch {
         hasBranches = false;
@@ -1558,6 +1671,23 @@ export class ClaudeCodeSessionsWidget extends Widget {
       buttons: [Dialog.cancelButton()]
     });
 
+    // Per-row "Open" launches that conversation in its own terminal (strict
+    // reuse via _openBranch) and closes the popup. stopPropagation keeps the
+    // click from toggling selection or switching the row.
+    const openButton = (sessionId: string): HTMLButtonElement => {
+      const btn = document.createElement('button');
+      btn.type = 'button';
+      btn.className = 'jp-ClaudeSessionsPanel-branchOpen';
+      btn.textContent = 'Open';
+      btn.title = 'Open this conversation in its own terminal';
+      btn.addEventListener('click', e => {
+        e.stopPropagation();
+        dialog.dispose();
+        void this._openBranch(sessionId);
+      });
+      return btn;
+    };
+
     const visibleMatches = (): IBranch[] => {
       const needle = search.value.trim().toLowerCase();
       return items.filter(
@@ -1613,6 +1743,7 @@ export class ClaudeCodeSessionsWidget extends Widget {
       badge.className = 'jp-ClaudeSessionsPanel-branchCurrentBadge';
       badge.textContent = 'current';
       currentRow.appendChild(badge);
+      currentRow.appendChild(openButton(current));
       currentRow.appendChild(this._branchCopyButton(current));
       list.appendChild(currentRow);
 
@@ -1677,6 +1808,7 @@ export class ClaudeCodeSessionsWidget extends Widget {
         time.textContent = this._formatRelativeTime(b.file_mtime);
         row.appendChild(time);
 
+        row.appendChild(openButton(b.session_id));
         row.appendChild(this._branchCopyButton(b.session_id));
 
         row.addEventListener('click', () => {
@@ -1902,7 +2034,12 @@ export class ClaudeCodeSessionsWidget extends Widget {
         name: launched.terminal_name
       });
       if (widget?.id) {
-        this._terminalsByPath.set(session.project_path, widget);
+        // The terminal runs the FORK (forkId), so tag it with that id - a
+        // later click on the now-current forked row reuses this terminal.
+        this._terminalsByPath.set(session.project_path, {
+          widget,
+          sessionId: forkId
+        });
         this._wireTerminalDisposal(session.project_path, widget);
         this._focusTerminal(widget);
       }
@@ -1913,8 +2050,10 @@ export class ClaudeCodeSessionsWidget extends Widget {
       spinner.dispose();
     }
     // No post-hoc title write: claude owns the name via ``-n`` and stamps it
-    // on the fork's first turn. The branch surfaces on the next poll once
-    // claude materialises its JSONL.
+    // on the fork's first turn. claude materialises the fork's JSONL lazily,
+    // so watch for it at a fast cadence and refresh the moment it appears -
+    // the branch surfaces in seconds instead of on the next slow poll.
+    this._watchForBranch(session.encoded_path, forkId);
   }
 
   /** Switch the active row's project to another conversation branch.
@@ -1960,6 +2099,70 @@ export class ClaudeCodeSessionsWidget extends Widget {
     }
   }
 
+  /** Open a specific conversation branch in its own terminal.
+   *
+   * Strict reuse: only a terminal already running THIS conversation is
+   * refocused; otherwise a fresh ``claude --resume <id>`` is launched. So
+   * several branches of one project can be open independently and side by
+   * side - opening branch B never disturbs branch A's terminal. Honours the
+   * global skip-permissions toggle like a normal resume. */
+  private async _openBranch(sessionId: string): Promise<void> {
+    const active = this._activeSession;
+    if (!active || !sessionId) {
+      return;
+    }
+    // Opening the row's CURRENT conversation behaves like a normal row resume
+    // (lenient): a fresh terminal already running it is reused, avoiding a
+    // `claude --resume` "already in use" collision. Opening a DIFFERENT branch
+    // is strict so the user lands in that specific conversation, even if some
+    // other (fresh) terminal sits at the same cwd.
+    const strict = sessionId !== active.session_id;
+    await this._resumeInTerminal(
+      { ...active, session_id: sessionId },
+      false,
+      strict
+    );
+  }
+
+  /** Poll fast for a freshly forked branch to materialise, then refresh.
+   *
+   * claude writes a forked session's JSONL lazily (on its first turn), so a
+   * just-requested branch does not exist at launch and would otherwise only
+   * surface on the next 30s poll. This watches the project's branch list
+   * every ``BRANCH_WATCH_INTERVAL_MS`` until ``forkId`` appears (as current
+   * or in the list) - then does one full refresh and stops - or until a
+   * bounded number of attempts elapses. The panel is never updated before
+   * the branch genuinely exists. */
+  private _watchForBranch(encodedPath: string, forkId: string): void {
+    let attempts = 0;
+    const tick = async (): Promise<void> => {
+      if (this.isDisposed) {
+        return;
+      }
+      attempts += 1;
+      try {
+        const data = await requestAPI<IBranchesResponse>(
+          `sessions/branches?encoded_path=${encodeURIComponent(encodedPath)}`,
+          this._serverSettings,
+          { cache: 'no-store' }
+        );
+        const appeared =
+          data.current === forkId ||
+          data.branches.some(b => b.session_id === forkId);
+        if (appeared) {
+          await this._fetch();
+          return;
+        }
+      } catch {
+        // Transient failure - keep watching until the attempt budget runs out.
+      }
+      if (attempts < BRANCH_WATCH_MAX_ATTEMPTS) {
+        window.setTimeout(() => void tick(), BRANCH_WATCH_INTERVAL_MS);
+      }
+    };
+    window.setTimeout(() => void tick(), BRANCH_WATCH_INTERVAL_MS);
+  }
+
   // --------------------------------------------------------------- polling
 
   private _startPolling(): void {
@@ -1994,6 +2197,7 @@ export class ClaudeCodeSessionsWidget extends Widget {
   private _commands!: CommandRegistry;
   private _contextMenu!: Menu;
   private _branchSubmenu!: Menu;
+  private _openBranchSubmenu!: Menu;
   private _branchSessionMenu!: Menu;
   private _lastBranches: IBranch[] = [];
   private _lastBranchesCurrent = '';
@@ -2004,7 +2208,14 @@ export class ClaudeCodeSessionsWidget extends Widget {
   private readonly _removingPaths: Set<string> = new Set();
   private readonly _terminalTracker: ITerminalTracker | null;
   private readonly _fileBrowser: IDefaultFileBrowser | null;
-  private readonly _terminalsByPath: Map<string, any> = new Map();
+  // Microcache of the most-recent terminal per project, tagged with the
+  // conversation it is running so reuse can tell a project's branches apart.
+  private readonly _terminalsByPath: Map<
+    string,
+    { widget: any; sessionId?: string }
+  > = new Map();
+  // In-flight launches, keyed per CONVERSATION (path + session id) so two
+  // different branches of one project can open independently and concurrently.
   private readonly _pendingByPath: Map<string, Promise<void>> = new Map();
   private readonly _rootDir: string;
   private _presentationMode: PresentationMode = DEFAULT_PRESENTATION_MODE;

package/style/base.css

@@ -463,6 +463,25 @@
   color: var(--jp-ui-font-color1);
 }
 
+/* Per-row "Open" launches the conversation in its own terminal. Compact
+   brand-outlined button matching the popup design language (2px radius). */
+.jp-ClaudeSessionsPanel-branchOpen {
+  flex: none;
+  padding: 0 8px;
+  border: 1px solid var(--jp-brand-color1);
+  border-radius: 2px;
+  background: transparent;
+  color: var(--jp-brand-color1);
+  font-size: var(--jp-ui-font-size0);
+  cursor: pointer;
+  transition: background 120ms ease;
+}
+
+.jp-ClaudeSessionsPanel-branchOpen:hover {
+  background: var(--jp-brand-color1);
+  color: var(--jp-ui-inverse-font-color1);
+}
+
 .jp-ClaudeSessionsPanel-branchTime {
   flex: none;
   width: 4em;