jupyterlab_ai_code_assistants_extension 1.2.18 → 1.2.27

package/README.md

@@ -8,7 +8,7 @@
 [![Brought To You By KOLOMOLO](https://img.shields.io/badge/Brought%20To%20You%20By-KOLOMOLO-00ffff?style=flat)](https://kolomolo.com)
 [![Donate PayPal](https://img.shields.io/badge/Donate-PayPal-blue?style=flat)](https://www.paypal.com/donate/?hosted_button_id=B4KPBJDLLXTSA)
 
-A full launcher and manager for every AI code assistant in JupyterLab - Claude Code, Codex, Kimi and Gemini. Start, resume, fork, switch, and clean up CLI sessions from a side panel per assistant - one click lands you in the right terminal with the assistant already running, no duplicate tabs, no UUID hunting. One install replaces the separate `jupyterlab_claude_code_extension`, `jupyterlab_codex_extension` and `jupyterlab_kimi_code_extension` packages and migrates their settings and favourites automatically.
+A full launcher and manager for every AI code assistant in JupyterLab - Claude Code, Codex, Kimi, Gemini and DeepSeek. Start, resume, fork, switch, and clean up CLI sessions from a side panel per assistant - one click lands you in the right terminal with the assistant already running, no duplicate tabs, no UUID hunting. One install replaces the separate `jupyterlab_claude_code_extension`, `jupyterlab_codex_extension` and `jupyterlab_kimi_code_extension` packages and migrates their settings and favourites automatically.
 
 ![Claude Code Sessions panel](.resources/screenshot.png)
 
@@ -25,17 +25,17 @@ Chat-panel extensions re-implement the agent loop and trail the real tool. This
 
 ## Features
 
-- **One install, every assistant** - Claude Code, Codex, Kimi and Gemini from a single package, each with its own right-side panel wearing its official mark
+- **One install, every assistant** - Claude Code, Codex, Kimi, Gemini and DeepSeek from a single package, each with its own right-side panel wearing its official mark
 - **Provider registry** - assistant-specific behaviour lives in one module per assistant behind capability flags; no core file names an assistant, and adding one touches no core file
 - **Joint settings page** - one settings section covering all assistants, with a per-assistant toggle (all on by default); toggling takes effect live, no JupyterLab reload
 - **Three-section side panel** - Favorites, Recent, and All projects, each scrolling independently
-- **One-click resume** - click a row to jump back into that session in a terminal; an open terminal for the project is reused instead of duplicated
+- **One-click resume** - click a row to jump back into that session in a terminal; an open terminal for the project is reused instead of duplicated. Exception: a Codex or Kimi conversation started with `+`, and a Codex fork, run without an id until the CLI writes one, so a click on that row meanwhile opens a second terminal
 - **Launcher tiles** - every enabled assistant has a tile in an "AI Assistants" section of the JupyterLab Launcher (after Other, under the extension's own robot-head icon); a click opens the assistant in the file browser's current folder, resuming the folder's conversation when one exists and starting a new one otherwise, through the companion `jupyterlab_basic_terminal_extension` (installed automatically). Disable an assistant and its tile goes; disable them all and the section goes with them
 - **Your terminal's `claude -c` follows the panel** (Claude) - switching to a conversation makes plain `claude -c` in that project resume that same conversation, including one that has been compacted, which Claude Code otherwise refuses to continue. Launching repairs a compacted conversation the same way, but only switching moves what `claude -c` picks
 - **Conversation switcher** - a right-click "Switch and Manage Sessions" submenu lists a project's other conversations by name and short id with last-activity time; "Manage Sessions..." opens a searchable popup over the full list with multi-select delete and per-row open and copy-id buttons
-- **Branch session** - fork the current conversation into a new named session via the right-click menu; each assistant forks its own way (Claude's native `--fork-session`, Codex's `codex fork`, server-side copies for Kimi and Gemini) behind the same menu item
+- **Branch session** - fork the current conversation into a new named session via the right-click menu; each assistant forks its own way (Claude's native `--fork-session`, Codex's `codex fork`, server-side copies for Kimi, Gemini and DeepSeek) behind the same menu item
 - **Launch modes under each assistant's own name** - Claude's skip-permissions, Codex's approval bypass, Kimi's `--yolo`, Gemini's YOLO; unsafe variants carry a shield glyph in the launch menus
-- **Coloured terminal tabs** - each session's colour tints its terminal tab via the companion `jupyterlab_colourful_tab_extension` (installed automatically). Claude's own `/color` supplies its default, Kimi derives a stable colour from the conversation id; Codex and Gemini have no colour of their own until you set one, and a branched session inherits its parent's colour, which it keeps even if the parent's colour later changes or is reset. Tinting needs the companion release that reports the colours you pick and lets another extension own a tab - against an older one this extension tints no tabs at all and says so once, and the companion's own right-click colours keep working as they always did
+- **Coloured terminal tabs** - each session's colour tints its terminal tab via the companion `jupyterlab_colourful_tab_extension` (installed automatically). Claude's own `/color` supplies its default, Kimi derives a stable colour from the conversation id; Codex, Gemini and DeepSeek have no colour of their own until you set one, and a branched session inherits its parent's colour, which it keeps even if the parent's colour later changes or is reset. Tinting needs the companion release that reports the colours you pick and lets another extension own a tab - against an older one this extension tints no tabs at all and says so once, and the companion's own right-click colours keep working as they always did
 - **Your own tab colour wins** - set a colour on a terminal tab and the extension remembers it for that conversation, overriding whatever the assistant chose. `Reset Tab Colour (n)` in the session's right-click menu hands back every colour you set by hand on that project's conversations, and appears once there is one to hand back. Clearing the colour on the tab itself releases it too, for the conversation that terminal is running; `Reset Tab Colour` is the way back for a conversation with no tab open. A Codex or Kimi conversation that has never been resumed cannot be tracked yet, so a colour set on its tab is not kept
 - **Favorites** - star projects you keep coming back to via the right-click menu; favourites from the standalone extensions are migrated on first run
 - **Remove and clean up** - drop a project's history or a project's extra parallel sessions from the right-click menu, confirmation dialog first; removed files honour JupyterLab's "move files to trash" setting
@@ -44,13 +44,14 @@ Chat-panel extensions re-implement the agent loop and trail the real tool. This
 - **Search** - fuzzy filter per panel, toggled by the funnel button
 - **Presentation modes** - label rows by session name or by path relative to the JupyterLab root
 - **Conflict-safe upgrade** - if a retired standalone extension is still installed, its panel wins and this extension stands down for that assistant instead of showing a duplicate
+- **DeepSeek in the browser** - the DeepSeek Harness has no terminal chat; its panel lists the projects under `~/.dsh/sessions` (or `$DSH_HOME`) and `Open Web UI` starts `dsh --profile web --no-open --port 0` in the project's terminal, which prints the URL to open. The conversation is then chosen in the harness's own browser UI; branching and deleting work from the panel as for every other assistant. The URL is on the machine running JupyterLab, so a remote server needs a port forward to reach it
 - **Auto-disabled when absent** - an assistant whose CLI is not on `PATH` does not show a panel
 
 ## Requirements
 
-- JupyterLab >= 4.0.0
+- JupyterLab >= 4.6.0
 - Python >= 3.10
-- At least one assistant CLI on `PATH`: `claude`, `codex`, `kimi`, or `gemini`
+- At least one assistant CLI on `PATH`: `claude`, `codex`, `kimi`, `gemini`, or `dsh` (the DeepSeek Harness)
 
 ## Install
 
@@ -60,6 +61,8 @@ Developers must install via the project `Makefile` (which orchestrates clean, bu
 make install
 ```
 
+The companion packages are version floors, so `make install` here pulls their published releases and replaces a locally built `jupyterlab_colourful_tab_extension` or `jupyterlab_basic_terminal_extension`. When verifying a change that spans this extension and a companion, install the companion last.
+
 End-users can install the published package from PyPI:
 
 ```bash

package/lib/core/labels.d.ts

@@ -0,0 +1,18 @@
+/** The distinguishing part of a conversation id: its first eight characters
+ * past `prefix`, the constant every id of the assistant carries
+ * (`IProviderDescriptor.sessionIdPrefix`). Front-sliced when there is no
+ * prefix, or when the id does not carry it. */
+export declare function shortSessionId(sessionId: string, prefix?: string): string;
+export declare const MENU_TITLE_COLUMNS = 60;
+/** Trim `text` to `maxColumns` display columns, appending an ellipsis when
+ * anything was cut. Iterates by CODE POINT, so an astral character is never
+ * split into a lone surrogate (which chromium paints as the replacement
+ * glyph). Returns `text` unchanged when it already fits. */
+export declare function truncateToColumns(text: string, maxColumns: number): string;
+/** Menu-item label for one branch: the conversation title trimmed to the
+ * column budget, followed by the short session id. Only the TITLE is trimmed -
+ * branches of one project share a path, so the id is what tells them apart and
+ * it must survive. The bracketed id is dropped when the title already IS the
+ * id (the server's last-resort fallback), which can never be truncated since a
+ * short id is at most 8 characters. */
+export declare function branchMenuLabel(label: string, shortId: string): string;

package/lib/core/labels.js

@@ -0,0 +1,68 @@
+// Label derivations of the panel: pure string functions, kept free of
+// JupyterLab imports so the unit tests load them without the panel's DOM.
+/** The distinguishing part of a conversation id: its first eight characters
+ * past `prefix`, the constant every id of the assistant carries
+ * (`IProviderDescriptor.sessionIdPrefix`). Front-sliced when there is no
+ * prefix, or when the id does not carry it. */
+export function shortSessionId(sessionId, prefix) {
+    const start = prefix && sessionId.startsWith(prefix) ? prefix.length : 0;
+    return sessionId.slice(start, start + 8);
+}
+// Lumino sets no `max-width` on `.lm-Menu-itemLabel`, so an uncapped
+// auto-generated conversation title stretches a submenu across the window.
+// Budget is in COLUMNS, not characters. Han, Kana, Hangul and emoji render at
+// roughly one em against Latin's half, so counting characters bounds nothing:
+// 60 Han glyphs measured 851-862px in a real Lumino submenu, at or above the
+// 850px that filed the defect in the first place. An assistant whose titles
+// are model-generated makes a wide-script title the expected case.
+export const MENU_TITLE_COLUMNS = 60;
+// East Asian Wide and Fullwidth ranges, plus emoji. Deliberately coarse: this
+// bounds a menu width, so a handful of mis-classified glyphs cost pixels, not
+// correctness. Anything outside these ranges counts as one column.
+const WIDE_RANGES = [
+    [0x1100, 0x115f], // Hangul Jamo
+    [0x2e80, 0x303e], // CJK radicals, Kangxi, CJK symbols and punctuation
+    [0x3041, 0x33ff], // Hiragana, Katakana, Bopomofo, Hangul Compat, CJK Compat
+    [0x3400, 0x4dbf], // CJK Unified Extension A
+    [0x4e00, 0x9fff], // CJK Unified Ideographs
+    [0xa000, 0xa4cf], // Yi
+    [0xac00, 0xd7a3], // Hangul syllables
+    [0xf900, 0xfaff], // CJK Compatibility Ideographs
+    [0xfe30, 0xfe6f], // CJK Compatibility Forms
+    [0xff00, 0xff60], // Fullwidth forms
+    [0xffe0, 0xffe6], // Fullwidth signs
+    [0x1f300, 0x1faff], // Emoji and pictographs
+    [0x20000, 0x3fffd] // CJK Unified Extensions B and beyond
+];
+function isWide(codePoint) {
+    return WIDE_RANGES.some(([lo, hi]) => codePoint >= lo && codePoint <= hi);
+}
+/** Trim `text` to `maxColumns` display columns, appending an ellipsis when
+ * anything was cut. Iterates by CODE POINT, so an astral character is never
+ * split into a lone surrogate (which chromium paints as the replacement
+ * glyph). Returns `text` unchanged when it already fits. */
+export function truncateToColumns(text, maxColumns) {
+    let columns = 0;
+    let kept = '';
+    for (const ch of text) {
+        const width = isWide(ch.codePointAt(0)) ? 2 : 1;
+        if (columns + width > maxColumns) {
+            // The cut can land just after a space; drop it so the ellipsis hugs the
+            // last word. `trimEnd` is ES2019 and this project targets ES2018.
+            return `${kept.replace(/\s+$/, '')}…`;
+        }
+        columns += width;
+        kept += ch;
+    }
+    return text;
+}
+/** Menu-item label for one branch: the conversation title trimmed to the
+ * column budget, followed by the short session id. Only the TITLE is trimmed -
+ * branches of one project share a path, so the id is what tells them apart and
+ * it must survive. The bracketed id is dropped when the title already IS the
+ * id (the server's last-resort fallback), which can never be truncated since a
+ * short id is at most 8 characters. */
+export function branchMenuLabel(label, shortId) {
+    const title = truncateToColumns(label, MENU_TITLE_COLUMNS);
+    return label === shortId ? title : `${title} (${shortId})`;
+}

package/lib/core/panel.d.ts

@@ -79,6 +79,10 @@ export declare class AssistantSessionsPanel extends Widget {
     private _logError;
     private _fetch;
     private _toggleFavourite;
+    /** The warning a permanent deletion earns and a trashed one does not - a
+     * trashed conversation is recoverable, and the popup one click away says
+     * so; the same sentence on both would be false half the time. */
+    private get _irreversibleNote();
     private get _disposalVerb();
     private _removeProject;
     private _cleanupParallel;
@@ -212,8 +216,7 @@ export declare class AssistantSessionsPanel extends Widget {
      * cannot give. */
     private _formatAbsoluteTime;
     /** Branch entry display: conversation name plus short session id. Branches
-     * share a project path, so the name and id are all that tell them apart. The
-     * suffix is dropped when the label already IS the short id. */
+     * share a project path, so the name and id are all that tell them apart. */
     private _branchDisplayName;
     /** Menu-item label for a branch: display name, relative time, and a trailing
      * marker when a live worker owns the conversation. The marker lives in the

package/lib/core/panel.js

@@ -5,6 +5,7 @@ import { CommandRegistry } from '@lumino/commands';
 import { UUID } from '@lumino/coreutils';
 import { Widget } from '@lumino/widgets';
 import { ColourStore } from './colour';
+import { branchMenuLabel, shortSessionId } from './labels';
 import { addIcon, branchIcon, cleanupIcon, filterIcon, providerIcon, refreshIcon, removeIcon, shieldIcon, starFilledIcon, statusDotIcon, switchIcon } from './icons';
 import { DEFAULT_RECENT_LIMIT, MAX_RECENT_LIMIT, MIN_RECENT_LIMIT } from './limits';
 import { resolveLaunchMode, resolvedLaunchModeEntry } from './modes';
@@ -586,6 +587,12 @@ export class AssistantSessionsPanel extends Widget {
             this._showActionError('Could not toggle favorite - try again.', err);
         }
     }
+    /** The warning a permanent deletion earns and a trashed one does not - a
+     * trashed conversation is recoverable, and the popup one click away says
+     * so; the same sentence on both would be false half the time. */
+    get _irreversibleNote() {
+        return this._deleteToTrash ? '' : ' This cannot be undone.';
+    }
     get _disposalVerb() {
         return this._deleteToTrash ? 'moved to trash' : 'deleted permanently';
     }
@@ -596,7 +603,7 @@ export class AssistantSessionsPanel extends Widget {
             title: `Remove from ${this._descriptor.label}`,
             body: `Remove "${name}" from ${this._descriptor.label}? This drops the ` +
                 `entire project history and every conversation it holds - ` +
-                `${this._disposalVerb}. This cannot be undone.`,
+                `${this._disposalVerb}.${this._irreversibleNote}`,
             buttons: [
                 Dialog.cancelButton(),
                 Dialog.warnButton({ label: this._trans.__('Remove') })
@@ -637,7 +644,7 @@ export class AssistantSessionsPanel extends Widget {
             title: this._trans.__('Clean Up Parallel Sessions'),
             body: `Remove ${extra} parallel session${extra === 1 ? '' : 's'} from ` +
                 `"${name}"? The current conversation is kept; the rest are ` +
-                `${this._disposalVerb}. This cannot be undone.`,
+                `${this._disposalVerb}.${this._irreversibleNote}`,
             buttons: [
                 Dialog.cancelButton(),
                 Dialog.warnButton({ label: this._trans.__('Remove') })
@@ -839,7 +846,7 @@ export class AssistantSessionsPanel extends Widget {
             if (row) {
                 // A terminal already holding that conversation IS the answer: a second
                 // process on one history is never what the click meant (ACC-LNCH-152).
-                const found = await this._terminals.findForSession(row.session_id);
+                const found = await this._terminals.findForSession(row.session_id, folder);
                 if (found) {
                     this._terminals.focus(found.widget);
                     return found.widget;
@@ -1194,6 +1201,7 @@ export class AssistantSessionsPanel extends Widget {
     }
     /** Make another conversation the row's current one. */
     async _switchBranch(session, sessionId) {
+        var _a;
         try {
             const result = await requestProvider(this._descriptor.id, 'switch', this._serverSettings, {
                 method: 'POST',
@@ -1205,6 +1213,15 @@ export class AssistantSessionsPanel extends Widget {
             if (result.current !== result.requested) {
                 Notification.warning('That conversation could not be made the current one.', { autoClose: 4000 });
             }
+            else {
+                // The re-render is the only other signal, and it can read as the
+                // opposite of success: the row now reports the conversation's true
+                // last activity, so switching to an old one dims the row and drops
+                // it out of Recent (DEF-PANE-181).
+                const target = this._lastBranches.find(b => b.session_id === sessionId);
+                const label = (_a = target === null || target === void 0 ? void 0 : target.label) !== null && _a !== void 0 ? _a : shortSessionId(sessionId, this._descriptor.sessionIdPrefix);
+                Notification.success(`${this._lookupName(session)}: switched to ${label}`, { autoClose: 3000 });
+            }
         }
         catch (err) {
             Notification.error(isResponseStatus(err, 404)
@@ -1486,17 +1503,6 @@ export class AssistantSessionsPanel extends Widget {
                 row.classList.add('jp-mod-stale');
             }
         }
-        const removing = this._removingPaths.has(session.encoded_path);
-        if (removing) {
-            row.classList.add('jp-mod-busy');
-            const spinner = document.createElement('span');
-            spinner.className = 'jp-AiAssistantsPanel-spinner';
-            spinner.title = this._trans.__('Removing...');
-            row.appendChild(spinner);
-        }
-        else {
-            row.appendChild(this._renderIndicator(session));
-        }
         const name = document.createElement('span');
         name.className = 'jp-AiAssistantsPanel-name';
         // The text ellipsises in a span of its own so the badges after it survive
@@ -1531,6 +1537,21 @@ export class AssistantSessionsPanel extends Widget {
             name.appendChild(bg);
         }
         row.appendChild(name);
+        // The status dot (or the removal spinner in its place) leads the row
+        // visually - CSS `order` puts it first - but follows the name in the DOM,
+        // so a screen reader announces the project before its status sentence
+        // rather than the same preamble ahead of every active row (DEF-PANE-183).
+        const removing = this._removingPaths.has(session.encoded_path);
+        if (removing) {
+            row.classList.add('jp-mod-busy');
+            const spinner = document.createElement('span');
+            spinner.className = 'jp-AiAssistantsPanel-spinner';
+            spinner.title = this._trans.__('Removing...');
+            row.appendChild(spinner);
+        }
+        else {
+            row.appendChild(this._renderIndicator(session));
+        }
         // No star in the Favorites section - every row there is one by definition.
         // The star sits before the time so the fixed-width time column stays the
         // rightmost alignment anchor across all rows.
@@ -1759,14 +1780,9 @@ export class AssistantSessionsPanel extends Widget {
             `${pad(d.getHours())}:${pad(d.getMinutes())}`);
     }
     /** Branch entry display: conversation name plus short session id. Branches
-     * share a project path, so the name and id are all that tell them apart. The
-     * suffix is dropped when the label already IS the short id. */
+     * share a project path, so the name and id are all that tell them apart. */
     _branchDisplayName(b) {
-        const shortId = b.session_id.slice(0, 8);
-        if (this._hooks.branchLabel) {
-            return this._hooks.branchLabel(b, shortId);
-        }
-        return b.label === shortId ? b.label : `${b.label} (${shortId})`;
+        return branchMenuLabel(b.label, shortSessionId(b.session_id, this._descriptor.sessionIdPrefix));
     }
     /** Menu-item label for a branch: display name, relative time, and a trailing
      * marker when a live worker owns the conversation. The marker lives in the
@@ -2186,10 +2202,14 @@ export class AssistantSessionsPanel extends Widget {
         add('reset-colour');
         this._contextMenu.addItem({ type: 'separator' });
         if (withBranches) {
-            this._contextMenu.addItem({
-                type: 'submenu',
-                submenu: this._openBranchSubmenu
-            });
+            // A project-scoped assistant has one terminal for every conversation,
+            // so opening a branch in its own terminal is not an action it has.
+            if (this._descriptor.terminalScope === 'conversation') {
+                this._contextMenu.addItem({
+                    type: 'submenu',
+                    submenu: this._openBranchSubmenu
+                });
+            }
             this._contextMenu.addItem({
                 type: 'submenu',
                 submenu: this._switchSubmenu
@@ -2351,11 +2371,12 @@ export class AssistantSessionsPanel extends Widget {
         if (!session) {
             return;
         }
+        const current = this._lastBranchesCurrent || session.session_id;
         showManageSessionsPopup({
             trans: this._trans,
             branches: this._lastBranches,
-            current: this._lastBranchesCurrent || session.session_id,
-            projectName: this._lookupName(session),
+            current,
+            currentName: `${this._lookupName(session)} (${shortSessionId(current, this._descriptor.sessionIdPrefix)})`,
             deleteToTrash: this._deleteToTrash,
             branchName: b => this._branchDisplayName(b),
             formatTime: ms => this._formatRelativeTime(ms),
@@ -2376,11 +2397,16 @@ export class AssistantSessionsPanel extends Widget {
      * is attached to and carries none. The row's own conversation is not in
      * `_lastBranches`, so it answers from the session. */
     _openBranchTitle(session, sessionId) {
-        var _a;
+        var _a, _b, _c, _d;
+        // One terminal serves a project-scoped assistant, so the button focuses
+        // or starts it, under the provider's own verb for that.
+        if (this._descriptor.terminalScope === 'project') {
+            return ((_c = (_b = (_a = this._hooks).resumeLabel) === null || _b === void 0 ? void 0 : _b.call(_a, session)) !== null && _c !== void 0 ? _c : "Open the project's terminal");
+        }
         const base = 'Open this conversation in its own terminal';
         const target = sessionId === session.session_id
             ? session
-            : ((_a = this._lastBranches.find(b => b.session_id === sessionId)) !== null && _a !== void 0 ? _a : null);
+            : ((_d = this._lastBranches.find(b => b.session_id === sessionId)) !== null && _d !== void 0 ? _d : null);
         const variant = this._resumeVariant(target);
         return variant ? `${base} (${variant.label})` : base;
     }

package/lib/core/popup.d.ts

@@ -18,8 +18,9 @@ export declare namespace ManageSessionsPopup {
         branches: IBranch[];
         /** The project's current conversation id, pinned at the top. */
         current: string;
-        /** Display name of the row this popup was opened from. */
-        projectName: string;
+        /** Display name of the current row: the project's name and the short id
+         * of `current`, derived by the panel with the same rule as `branchName`. */
+        currentName: string;
         /** Whether deletions move to trash - the popup says which it means. */
         deleteToTrash: boolean;
         /** Display name for one branch, `<label> (<short id>)` by default. */

package/lib/core/popup.js

@@ -158,7 +158,7 @@ export function showManageSessionsPopup(options) {
         // same structure the branch rows below use.
         const currentText = document.createElement('span');
         currentText.className = 'jp-AiAssistantsPanel-branchLabelText';
-        currentText.textContent = `${options.projectName} (${options.current.slice(0, 8)})`;
+        currentText.textContent = options.currentName;
         currentLabel.appendChild(currentText);
         currentRow.appendChild(currentLabel);
         const badge = document.createElement('span');
@@ -245,21 +245,9 @@ export function showManageSessionsPopup(options) {
             row.appendChild(time);
             row.appendChild(openButton(b.session_id));
             row.appendChild(copyButton(b.session_id, trans));
+            // A row click always switches, whatever is selected: the checkbox cell
+            // is the one select target, so a click has one meaning (DEF-PANE-209).
             const activate = () => {
-                // Selection mode: while anything is ticked, row clicks toggle
-                // selection - no accidental switch mid-selection.
-                if (selected.size > 0) {
-                    if (selected.has(b.session_id)) {
-                        selected.delete(b.session_id);
-                    }
-                    else {
-                        selected.add(b.session_id);
-                    }
-                    check.checked = selected.has(b.session_id);
-                    disarm();
-                    updateControls();
-                    return;
-                }
                 dialog.dispose();
                 options.onSwitch(b.session_id);
             };
@@ -303,7 +291,7 @@ export function showManageSessionsPopup(options) {
     });
     // Busy-lock the whole body during the async delete, so a slow backend cannot
     // be double-clicked into deleting the same set twice and a mid-flight
-    // selection cannot be silently discarded. The Dialog's Cancel button sits
+    // selection cannot be silently discarded. The Dialog's Close button sits
     // outside the body and stays usable.
     const setDeleting = (on) => {
         deleting = on;

package/lib/core/terminals.d.ts

@@ -46,6 +46,11 @@ export declare class TerminalManager {
      * Launch a terminal for one request and focus it. The returned widget is
      * tagged with `tagSessionId` in the microcache, so a later click on the row
      * that conversation now belongs to reuses this very terminal.
+     *
+     * For a project-scoped assistant the project's running terminal is the
+     * answer instead, whatever the request asked for: every caller - row click,
+     * `+`, fork, Launcher tile - lands here, so this one gate is what keeps a
+     * second server off the project.
      */
     launch(request: ILaunchRequest, tagSessionId?: string): Promise<any>;
     /**
@@ -63,11 +68,28 @@ export declare class TerminalManager {
      * too, not only launches that carry an argv id. An id is globally unique to
      * one conversation, so a terminal holding it IS the one to focus, whatever
      * cwd it reports - a process that changed directory, or whose project dir
-     * was recreated, must still be reused rather than duplicated. */
-    findForSession(wantedSessionId: string | undefined): Promise<{
+     * was recreated, must still be reused rather than duplicated.
+     *
+     * For a project-scoped assistant the id is not what a terminal holds; the
+     * project's running terminal (see `_projectTerminal`) is the answer, so the
+     * caller passes the project path. */
+    findForSession(wantedSessionId: string | undefined, projectPath?: string): Promise<{
         widget: any;
         runningId: string | null;
     } | null>;
+    /** The one terminal serving a project, for a project-scoped assistant, or
+     * null. The project's microcache entry whatever conversation it was tagged
+     * with, else the first live terminal the server confirms is running this
+     * assistant with its working directory inside the project - the same
+     * cwd-to-project rule the colour pass applies. The server's `running`
+     * answer is what keeps a plain shell opened at the project from matching.
+     *
+     * The cached terminal is asked too, so a server the user stopped in it does
+     * not hold every later open on a dead shell. Only a terminal the server has
+     * once confirmed is evicted on a `running: false` answer: a fresh launch
+     * answers that until its process is up, and evicting it then would start
+     * the second server this method exists to prevent. */
+    private _projectTerminal;
     /** Ask the server what a terminal is running. Null when the widget has no
      * session name yet, or the probe fails - a terminal can vanish between
      * enumeration and probe, which is a retry, not an error. */

package/lib/core/terminals.js

@@ -99,7 +99,8 @@ export class TerminalManager {
         // terminal is not painted, because painting is what destroys the pick.
         this._pendingChoices = new Map();
         // Most recent terminal per project, tagged with the conversation it runs so
-        // reuse can tell a project's branches apart.
+        // reuse can tell a project's branches apart. `confirmed` records that the
+        // server once answered `running: true` for it (project scope only).
         this._byProject = new Map();
         // In-flight launches keyed per CONVERSATION, so two branches of one project
         // open independently and concurrently.
@@ -177,6 +178,17 @@ export class TerminalManager {
     }
     async _doOpenSession(session, mode, wanted) {
         var _a;
+        // A project-scoped assistant has no per-conversation terminal to find:
+        // `launch` answers with the project's running one or starts it.
+        if (this._descriptor.terminalScope === 'project') {
+            await this.launch({
+                project_path: session.project_path,
+                encoded_path: session.encoded_path,
+                session_id: wanted,
+                mode
+            }, wanted);
+            return;
+        }
         // 1. Microcache - the most recent terminal of this project, reused only
         // when it carries the wanted conversation.
         const cached = this._byProject.get(session.project_path);
@@ -211,8 +223,26 @@ export class TerminalManager {
      * Launch a terminal for one request and focus it. The returned widget is
      * tagged with `tagSessionId` in the microcache, so a later click on the row
      * that conversation now belongs to reuses this very terminal.
+     *
+     * For a project-scoped assistant the project's running terminal is the
+     * answer instead, whatever the request asked for: every caller - row click,
+     * `+`, fork, Launcher tile - lands here, so this one gate is what keeps a
+     * second server off the project.
      */
     async launch(request, tagSessionId) {
+        if (this._descriptor.terminalScope === 'project') {
+            const running = await this._projectTerminal(request.project_path);
+            if (running) {
+                // A new conversation still settles the project's pin (DEF-9): the
+                // argv route runs the launch's validation and pin bookkeeping without
+                // spawning, and the argv it answers with is not needed here.
+                if (request.session_id === undefined && request.encoded_path) {
+                    await requestProvider(this._descriptor.id, 'launch-argv', this._serverSettings, { method: 'POST', body: JSON.stringify(request) });
+                }
+                this.focus(running);
+                return running;
+            }
+        }
         const spinner = showLaunchSpinner(`Opening ${this._descriptor.label}`, this._trans);
         try {
             const launched = await requestProvider(this._descriptor.id, 'launch', this._serverSettings, { method: 'POST', body: JSON.stringify(request) });
@@ -262,8 +292,18 @@ export class TerminalManager {
      * too, not only launches that carry an argv id. An id is globally unique to
      * one conversation, so a terminal holding it IS the one to focus, whatever
      * cwd it reports - a process that changed directory, or whose project dir
-     * was recreated, must still be reused rather than duplicated. */
-    async findForSession(wantedSessionId) {
+     * was recreated, must still be reused rather than duplicated.
+     *
+     * For a project-scoped assistant the id is not what a terminal holds; the
+     * project's running terminal (see `_projectTerminal`) is the answer, so the
+     * caller passes the project path. */
+    async findForSession(wantedSessionId, projectPath) {
+        if (this._descriptor.terminalScope === 'project') {
+            const widget = projectPath
+                ? await this._projectTerminal(projectPath)
+                : null;
+            return widget ? { widget, runningId: null } : null;
+        }
         if (!this._tracker || !wantedSessionId) {
             return null;
         }
@@ -275,6 +315,50 @@ export class TerminalManager {
         }
         return null;
     }
+    /** The one terminal serving a project, for a project-scoped assistant, or
+     * null. The project's microcache entry whatever conversation it was tagged
+     * with, else the first live terminal the server confirms is running this
+     * assistant with its working directory inside the project - the same
+     * cwd-to-project rule the colour pass applies. The server's `running`
+     * answer is what keeps a plain shell opened at the project from matching.
+     *
+     * The cached terminal is asked too, so a server the user stopped in it does
+     * not hold every later open on a dead shell. Only a terminal the server has
+     * once confirmed is evicted on a `running: false` answer: a fresh launch
+     * answers that until its process is up, and evicting it then would start
+     * the second server this method exists to prevent. */
+    async _projectTerminal(projectPath) {
+        var _a, _b;
+        const cached = this._byProject.get(projectPath);
+        if (cached && !cached.widget.isDisposed) {
+            const info = await this.probe(cached.widget);
+            if (info === null || info === void 0 ? void 0 : info.running) {
+                cached.confirmed = true;
+            }
+            if ((info === null || info === void 0 ? void 0 : info.running) !== false || !cached.confirmed) {
+                return cached.widget;
+            }
+            this._byProject.delete(projectPath);
+        }
+        if (!this._tracker) {
+            return null;
+        }
+        for (const widget of this._liveTerminals()) {
+            const info = await this.probe(widget);
+            if ((info === null || info === void 0 ? void 0 : info.running) &&
+                ((_b = sessionForCwds((_a = info.cwds) !== null && _a !== void 0 ? _a : [], this._sessions)) === null || _b === void 0 ? void 0 : _b.project_path) ===
+                    projectPath) {
+                this._byProject.set(projectPath, {
+                    widget,
+                    sessionId: undefined,
+                    confirmed: true
+                });
+                this._wireDisposal(projectPath, widget);
+                return widget;
+            }
+        }
+        return null;
+    }
     /** Ask the server what a terminal is running. Null when the widget has no
      * session name yet, or the probe fails - a terminal can vanish between
      * enumeration and probe, which is a retry, not an error. */

package/lib/core/types.d.ts

@@ -15,6 +15,8 @@
  * or read that value.
  */
 export type ForkStrategy = 'native-flag' | 'native-command' | 'server-copy';
+/** See `IProviderDescriptor.terminalScope`. */
+export type TerminalScope = 'conversation' | 'project';
 /** Where a conversation's DEFAULT tab tint comes from. A user-set colour in
  * the extension's own write-back store always wins over all three. */
 export type ColourSource = 'native' | 'derived' | 'none';
@@ -56,6 +58,14 @@ export interface IProviderDescriptor {
     cliBinary: string;
     forkStrategy: ForkStrategy;
     colourSource: ColourSource;
+    /** What one terminal of this assistant holds. `conversation`: the process
+     * runs exactly one conversation, so a terminal is reused only when the
+     * server reads the wanted id off it. `project`: the process serves every
+     * conversation of the project (a web UI chosen in the browser), so the
+     * project's one running terminal is the answer to every open - a row click,
+     * `+`, a fork, a Launcher tile - and a second process on the same project
+     * is always a duplicate. */
+    terminalScope: TerminalScope;
     /** Whether the branch flow asks the user to name the new conversation.
      * Where that name then GOES is `forkStrategy`'s job. */
     promptsForBranchName: boolean;
@@ -65,6 +75,12 @@ export interface IProviderDescriptor {
      * `forkStrategy` - an assistant can accept an id for a new session and still
      * have no fork verb at all. */
     mintsNewSessionId: boolean;
+    /** A constant prefix every conversation id of this assistant carries, e.g.
+     * `session_`. The short id shown beside a branch is sliced past it, since a
+     * front-slice of such an id would render the same eight characters for
+     * every conversation of a project - the exact thing the short id exists to
+     * tell apart. Absent for an assistant whose ids are bare uuids. */
+    sessionIdPrefix?: string;
     launchModes: ILaunchMode[];
     /** Sessions can be held under remote control - renders the indicator dot. */
     hasRemoteControl: boolean;
@@ -286,10 +302,6 @@ export interface IProviderHooks {
     resumeLabel?: (session: ISession | null) => string;
     /** Extra lines for the row tooltip. */
     tooltipLines?: (session: ISession) => string[];
-    /** Menu label for one branch. Defaults to `<label> (<short id>) - <time>`;
-     * a provider whose titles are written in wide scripts overrides it to bound
-     * the menu by display columns rather than by code units. */
-    branchLabel?: (branch: IBranch, shortId: string) => string;
 }
 /** What `providers/index.ts` registers: one descriptor, optionally with hooks. */
 export interface IProviderModule {

package/lib/providers/claude.js

@@ -42,6 +42,7 @@ export const descriptor = {
     // its transcript, so the assistant supplies the DEFAULT tint - a colour the
     // user then sets on the tab diverges from it deliberately and wins.
     colourSource: 'native',
+    terminalScope: 'conversation',
     // `-n <name>` at launch: Claude stamps the name itself and re-stamps it on
     // every turn, which is the only way a fork's name survives - a title written
     // after the fact loses to the parent title the fork inherits.

package/lib/providers/codex.js

@@ -38,6 +38,7 @@ export const descriptor = {
     forkStrategy: 'native-command',
     // No `/color` equivalent, and nothing in the thread store records one.
     colourSource: 'none',
+    terminalScope: 'conversation',
     // Forks are unnamed - Codex has no naming flag and no writable title field,
     // so the panel never asks for a name it could not stamp anywhere.
     promptsForBranchName: false,