jupyterlab_ai_code_assistants_extension 1.0.32 → 1.0.41

package/lib/core/panel.d.ts

@@ -85,6 +85,18 @@ export declare class AssistantSessionsPanel extends Widget {
      * `resolveLaunchMode` for the precedence rule. */
     private _launchMode;
     private _openSession;
+    /** The server root every path is shown and resolved against, plus
+     * JupyterLab's move-to-trash setting. Settable because a panel docked before
+     * the server has answered its first status probe is built without either
+     * (DEF-132); the action paths read them lazily, so a late value applies on
+     * the next click, and a root arriving after rows were drawn redraws them
+     * once (DEF-136).
+     *
+     * Trailing slashes go, but never the root itself: serving JupyterLab at
+     * `/` used to normalise to the empty string, which reads as "no root" -
+     * the + button then did nothing at all, and Open Terminal and Show in File
+     * Browser answered "outside the JupyterLab root" for every row inside it. */
+    setRoot(rootDir: string, deleteToTrash: boolean): void;
     /** Absolute path of the file browser's current folder; the server root when
      * no file browser is available. */
     private _currentFolder;
@@ -271,8 +283,8 @@ export declare class AssistantSessionsPanel extends Widget {
     private readonly _descriptor;
     private readonly _hooks;
     private readonly _serverSettings;
-    private readonly _rootDir;
-    private readonly _deleteToTrash;
+    private _rootDir;
+    private _deleteToTrash;
     private readonly _fileBrowser;
     private readonly _colours;
     private readonly _terminals;

package/lib/core/panel.js

@@ -94,6 +94,8 @@ export class AssistantSessionsPanel extends Widget {
     constructor(options) {
         var _a, _b, _c, _d;
         super();
+        this._rootDir = '';
+        this._deleteToTrash = true;
         this._removingPaths = new Set();
         this._loadingEl = null;
         this._errorEl = null;
@@ -132,13 +134,7 @@ export class AssistantSessionsPanel extends Widget {
         this._descriptor = options.descriptor;
         this._hooks = (_a = options.hooks) !== null && _a !== void 0 ? _a : {};
         this._serverSettings = options.app.serviceManager.serverSettings;
-        // Trailing slashes go, but never the root itself: serving JupyterLab at
-        // `/` used to normalise to the empty string, which reads as "no root" -
-        // the + button then did nothing at all, and Open Terminal and Show in File
-        // Browser answered "outside the JupyterLab root" for every row inside it.
-        const root = (options.rootDir || '').replace(/\/+$/, '');
-        this._rootDir = root || (options.rootDir ? '/' : '');
-        this._deleteToTrash = options.deleteToTrash !== false;
+        this.setRoot(options.rootDir, options.deleteToTrash !== false);
         this._fileBrowser = (_b = options.fileBrowser) !== null && _b !== void 0 ? _b : null;
         this._expandedKey = `jupyterlab_ai_code_assistants_extension:${this._descriptor.id}:expanded`;
         this._expanded = loadExpanded(this._expandedKey);
@@ -259,8 +255,15 @@ export class AssistantSessionsPanel extends Widget {
         // and this button LAUNCHES on click instead of dropping a menu, so without
         // the suffix the one surface that starts an approval-free session is the
         // only one that never says so (DEF-36, DEF-113, DEF-114).
+        // Disabled, not silent, while the server root is unknown (a panel docked
+        // before the first status roster, DEF-132): a healthy-looking button that
+        // does nothing on click cannot be diagnosed by the user. `setRoot` re-runs
+        // this once the root lands, so the state is data-driven, not timed.
         const nameNewButton = () => {
-            newBtn.title = `New session in current folder${this._variantSuffix()}`;
+            newBtn.disabled = !this._rootDir;
+            newBtn.title = this._rootDir
+                ? `New session in current folder${this._variantSuffix()}`
+                : 'Waiting for the server root';
         };
         // Focus as well as hover, or the icon-only button's accessible name is the
         // generic one for everybody not using a mouse.
@@ -505,6 +508,18 @@ export class AssistantSessionsPanel extends Widget {
     _showError(err) {
         const message = err instanceof Error ? err.message : String(err);
         this._logError(message);
+        // DEF-138: the server ANSWERED, and its answer is that this assistant's
+        // binary is not on the PATH the Jupyter server runs with. Blaming the
+        // server names the wrong cause - the panel is docked only because no
+        // roster has arrived yet, and the roster is what removes it (DEF-132).
+        // The error code is matched as well as the status, because a 503 raised
+        // by a proxy or a stopped single-user server is NOT this: its body never
+        // parses to `{"error": "cli_not_found"}`, so it keeps the copy below.
+        if (isResponseStatus(err, 503) && message === 'cli_not_found') {
+            this._setInlineError(`\`${this._descriptor.cliBinary}\` was not found on the Jupyter ` +
+                `server's PATH.`);
+            return;
+        }
         const copy = isRequestTimeout(err)
             ? 'The server is not answering - retrying.'
             : 'Could not reach the server - retrying.';
@@ -707,10 +722,44 @@ export class AssistantSessionsPanel extends Widget {
             void this._fetch().catch(() => undefined);
         }
     }
+    /** The server root every path is shown and resolved against, plus
+     * JupyterLab's move-to-trash setting. Settable because a panel docked before
+     * the server has answered its first status probe is built without either
+     * (DEF-132); the action paths read them lazily, so a late value applies on
+     * the next click, and a root arriving after rows were drawn redraws them
+     * once (DEF-136).
+     *
+     * Trailing slashes go, but never the root itself: serving JupyterLab at
+     * `/` used to normalise to the empty string, which reads as "no root" -
+     * the + button then did nothing at all, and Open Terminal and Show in File
+     * Browser answered "outside the JupyterLab root" for every row inside it. */
+    setRoot(rootDir, deleteToTrash) {
+        var _a;
+        const root = (rootDir || '').replace(/\/+$/, '');
+        const next = root || (rootDir ? '/' : '');
+        const changed = next !== this._rootDir;
+        this._rootDir = next;
+        this._deleteToTrash = deleteToTrash;
+        (_a = this._renameNewButton) === null || _a === void 0 ? void 0 : _a.call(this);
+        // Guarded on the VALUE, not on the call: `reconcile` re-sends the same
+        // root every status tick, so a changed-guard redraws exactly once, on the
+        // '' -> root transition. `_sessions` stands in for "the shell is built and
+        // rows are on screen" - it is null until the first `_fetch` answers, which
+        // is what keeps the constructor's own `setRoot` from reaching `_render`
+        // before `_buildShell` has created `_bodyEl`.
+        if (changed && this._sessions !== null) {
+            this._render();
+        }
+    }
     /** Absolute path of the file browser's current folder; the server root when
      * no file browser is available. */
     _currentFolder() {
         var _a, _b, _c;
+        // No roster yet (DEF-132): a relative folder joined to an empty root
+        // would be an absolute path at the filesystem root.
+        if (!this._rootDir) {
+            return '';
+        }
         const rel = ((_c = (_b = (_a = this._fileBrowser) === null || _a === void 0 ? void 0 : _a.model) === null || _b === void 0 ? void 0 : _b.path) !== null && _c !== void 0 ? _c : '').replace(/^\/+/, '');
         if (!rel) {
             return this._rootDir;
@@ -1744,7 +1793,11 @@ export class AssistantSessionsPanel extends Widget {
                 // absolute filesystem path, so it goes through _pathUnderRoot.
                 const rel = this._pathUnderRoot(s.project_path);
                 if (rel === null) {
-                    Notification.warning('Folder is outside the JupyterLab root - cannot open a terminal there.', { autoClose: 4000 });
+                    // A root the server has not sent yet is not a folder outside it
+                    // (DEF-134).
+                    Notification.warning(this._rootDir
+                        ? 'Folder is outside the JupyterLab root - cannot open a terminal there.'
+                        : 'Waiting for the server root - cannot open a terminal yet.', { autoClose: 4000 });
                     return;
                 }
                 this._app.commands
@@ -1762,7 +1815,11 @@ export class AssistantSessionsPanel extends Widget {
                 }
                 const rel = this._pathUnderRoot(s.project_path);
                 if (rel === null) {
-                    Notification.warning('Folder is outside the JupyterLab root - the file browser cannot show it.', { autoClose: 4000 });
+                    // A root the server has not sent yet is not a folder outside it
+                    // (DEF-134).
+                    Notification.warning(this._rootDir
+                        ? 'Folder is outside the JupyterLab root - the file browser cannot show it.'
+                        : 'Waiting for the server root - the file browser cannot show it yet.', { autoClose: 4000 });
                     return;
                 }
                 this._app.commands

package/lib/core/request.d.ts

@@ -56,6 +56,7 @@ export declare function isRequestTimeout(err: unknown): boolean;
  * @returns The response body interpreted as JSON
  * @throws RequestTimeoutError when the deadline passes before the server
  *   answers
+ * @throws Error when a 200 carries a body this helper cannot parse
  */
 export declare function requestAPI<T>(endPoint: string, serverSettings: ServerConnection.ISettings, init?: RequestInit): Promise<T>;
 /** Build a provider-scoped path: `providers/<id>/<path>`. The id is encoded so

package/lib/core/request.js

@@ -63,6 +63,7 @@ export function isRequestTimeout(err) {
  * @returns The response body interpreted as JSON
  * @throws RequestTimeoutError when the deadline passes before the server
  *   answers
+ * @throws Error when a 200 carries a body this helper cannot parse
  */
 export async function requestAPI(endPoint, serverSettings, init = {}) {
     var _a, _b;
@@ -111,7 +112,24 @@ export async function requestAPI(endPoint, serverSettings, init = {}) {
             data = JSON.parse(data);
         }
         catch (_c) {
-            console.log(`${LOG_PREFIX} Not a JSON response body.`, response);
+            if (response.ok) {
+                // DEF-118: every handler in `core/routes.py` finishes `json.dumps`, so
+                // a 200 this helper cannot parse did not come from this server - it is
+                // an SSO or proxy interstitial served in its place. Returning the raw
+                // string let every caller read `undefined` off it: `probeStatus` wrote
+                // a roster with no `providers` and `reconcile` undocked all four
+                // panels, `_fetch` rendered an empty session list, and
+                // `ColourStore.load` replaced the cache with an empty map. Refusing it
+                // makes the probe FAIL, and a failed probe writes nothing (DEF-132),
+                // so the last known roster stands.
+                throw new Error(`Response to ${endPoint} was not JSON (HTTP ${response.status})`);
+            }
+            // Not ok: the `ResponseError` below carries this body as its message, so
+            // this side is no longer a silent path and a proxy's error page here is
+            // noise (DEF-116). This is the conditional DEF-118 recorded - `debug`
+            // only on the refusal side; the 200 side is now louder than the `warn`
+            // it asked for.
+            console.debug(`${LOG_PREFIX} Not a JSON response body.`, response);
         }
     }
     if (!response.ok) {

package/lib/index.js

@@ -64,34 +64,27 @@ const plugin = {
         let status = null;
         let settings = null;
         let sidebar = DEFAULT_SIDEBAR;
-        let probeGeneration = 0;
         /** Ask the server which providers exist and which of their binaries are on
-         * PATH. An unsuperseded failure leaves the extension activated with no
-         * panels until a later probe succeeds - never a dialog, never a thrown
-         * activation.
+         * PATH.
          *
-         * Probes overlap: a probe can outlive one issued after it, so verdicts do
-         * not arrive in the order they were asked for. A ROSTER is always written,
-         * whichever settles last - both are answers from the same server, and the
-         * loser is at worst one client deadline stale (DEF-125). A FAILURE is not an answer, so it
-         * is written only while no newer probe has been issued; otherwise a
-         * timeout could discard a roster the server has since confirmed, undocking
-         * every panel while it is healthy (DEF-121). No request is suppressed. */
+         * `status` is the last roster the server gave, and null means it has never
+         * given one - two different facts that used to share one value. A probe
+         * that FAILS writes nothing: not answering is not an answer, and reading it
+         * as "no assistant is installed" is what emptied the sidebar on every
+         * reload whose first request landed before the server was listening
+         * (DEF-132), and on every wake whose probe fired before the network was
+         * back (DEF-119). No request is suppressed, and a failure never needs
+         * ordering against a success, because it has nothing to write. */
         const probeStatus = async () => {
-            const mine = ++probeGeneration;
             try {
                 status = await requestAPI('status', serverSettings, {
                     cache: 'no-store'
                 });
             }
             catch (err) {
-                // No cadence named here: this also prints from the activation probe,
-                // and neither the interval nor the wake listeners are armed until
-                // after `await migrate()` below (DEF-122).
-                console.warn(`${LOG_PREFIX} status probe failed; panels dock again once a later probe succeeds.`, err);
-                if (mine === probeGeneration) {
-                    status = null;
-                }
+                // No cadence named: this also prints from the activation probe, before
+                // the interval and the wake listeners are armed (DEF-122).
+                console.warn(`${LOG_PREFIX} status probe failed; the last known roster stands (every enabled assistant, when there is none yet) until a later probe answers.`, err);
             }
         };
         const statusFor = (id) => { var _a, _b; return (_b = (_a = status === null || status === void 0 ? void 0 : status.providers) === null || _a === void 0 ? void 0 : _a.find(p => p.id === id)) !== null && _b !== void 0 ? _b : null; };
@@ -153,7 +146,10 @@ const plugin = {
                     descriptor: module.descriptor,
                     hooks: module.hooks,
                     rootDir: (_a = status === null || status === void 0 ? void 0 : status.root_dir) !== null && _a !== void 0 ? _a : '',
-                    deleteToTrash: (status === null || status === void 0 ? void 0 : status.delete_to_trash) !== false,
+                    // Unknown reads as "not trash": the popup then arms its Delete
+                    // button before it executes, which is the only confirmation a
+                    // permanent bulk delete has (DEF-135).
+                    deleteToTrash: status ? status.delete_to_trash !== false : false,
                     terminalTracker,
                     fileBrowser,
                     colourfulTabs
@@ -188,7 +184,7 @@ const plugin = {
         /** Bring the docked panels in line with settings and CLI availability.
          * Both must hold for a panel to be present. */
         const reconcile = () => {
-            var _a, _b, _c, _d;
+            var _a, _b, _c, _d, _e;
             for (const descriptor of registry.descriptors) {
                 const id = descriptor.id;
                 if (suppressed.has(id)) {
@@ -196,16 +192,22 @@ const plugin = {
                 }
                 const enabled = setting(`providers.${id}.enabled`, true) !== false;
                 const probe = statusFor(id);
-                const available = probe ? probe.available !== false : false;
+                // Unknown is not absent. With no roster yet, an enabled assistant is
+                // docked: JupyterLab restores the sidebar tab it had open only if that
+                // tab exists when activation ends, and it waits for activation but
+                // not for a later probe - so a panel that arrives a minute late is one
+                // the layout has already given up on (DEF-132). Once a roster exists
+                // the server's word on each binary is final.
+                const roster = status;
+                const available = roster === null ? true : probe !== null && probe.available !== false;
                 // Enabled but binary absent must not be a silent state: the user sees
                 // a missing panel with no clue that PATH under the Jupyter server
                 // differs from their shell. Once per id, not per reconcile.
                 // Only when the probe SUCCEEDED and this provider is the one missing.
-                // A failed probe sets every provider unavailable, and blaming PATH for
-                // a server the frontend never reached names the wrong cause; and every
-                // provider defaults to enabled, so a machine with one assistant
-                // installed would otherwise raise three toasts about assistants the
-                // user has never heard of. The console line stays for that case.
+                // Blaming PATH for a server the frontend never reached names the wrong
+                // cause; and every provider defaults to enabled, so a machine with one
+                // assistant installed would otherwise raise three toasts about assistants
+                // the user has never heard of. The console line stays for that case.
                 const chosen = (settings === null || settings === void 0 ? void 0 : settings.get(`providers.${id}.enabled`).user) !== undefined;
                 if (probe !== null &&
                     probe.available === false &&
@@ -224,9 +226,26 @@ const plugin = {
                     // gets a notification, so the COMMON failure was the quiet one.
                     Notification.warning(`${label} is enabled but \`${binary}\` was not found on the Jupyter server's PATH, so its panel is not shown.`, { autoClose: 8000 });
                 }
+                // The latch is per ABSENCE, not per page load. Once the server reports
+                // the binary present again, a later disappearance gets its own warning:
+                // without this, one transient absence - a CLI upgrade unlinking the
+                // binary for a moment, or an obsolete roster from an overlapping probe -
+                // permanently suppresses the real one (DEF-125). It cannot make the
+                // warning repeat while the state is unchanged, which is what the
+                // once-per-id latch above exists to prevent: the two conditions are
+                // mutually exclusive.
+                if (probe !== null && probe.available !== false) {
+                    warnedUnavailable.delete(id);
+                }
                 if (enabled && available) {
                     if (live.has(id)) {
-                        applySharedSettings(live.get(id).panel);
+                        const panel = live.get(id).panel;
+                        applySharedSettings(panel);
+                        // A panel docked before the first roster was built without the
+                        // server root, and cannot resolve paths until it has one.
+                        if (roster !== null) {
+                            panel.setRoot((_e = roster.root_dir) !== null && _e !== void 0 ? _e : '', roster.delete_to_trash !== false);
+                        }
                     }
                     else {
                         start(id);
@@ -323,8 +342,8 @@ const plugin = {
             void probeStatus().then(reconcile);
         }, STATUS_INTERVAL_MS);
         // A suspended network stack - laptop asleep, tab backgrounded - is exactly
-        // when the probe fails, and the slow cadence above would leave the sidebar
-        // panel-less for up to a minute after the machine comes back. A wake fires
+        // when the probe fails, and the slow cadence above would leave the roster
+        // stale for up to a minute after the machine comes back. A wake fires
         // both events, so it costs two probes; deliberately, because a guard that
         // let the second join the first answered the wake with a request issued
         // before it, and starved the interval above of its own tick (DEF-117).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "jupyterlab_ai_code_assistants_extension",
-    "version": "1.0.32",
+    "version": "1.0.41",
     "description": "Jupyterlab extension to replace individual jupyterlab_*_code_extension and integrate into one, that offers joint capability, joint settings page and individual right toolbar panels per code assistant, with the ability in settings to decide which code assistant support is on (default - all are enabled)",
     "keywords": [
         "jupyter",

package/src/__tests__/index.spec.ts

@@ -0,0 +1,127 @@
+/**
+ * The plugin's own activation path - the only tier that reaches it.
+ *
+ * `src/index.ts` carried no Jest coverage at all (0 of 151 lines), and the
+ * Galata DEF-132 spec stops at the panels docking, before the first probe ever
+ * answers. The branch below is what makes a panel docked without a roster
+ * usable once one arrives: `reconcile` pushes the late `root_dir` and trash
+ * flag into the already-live panel (DEF-GUARD-139).
+ *
+ * Nothing here waits on a timer. The activation probe fails, the roster is
+ * delivered by dispatching `online`, and the promise chain is drained through
+ * the microtask queue.
+ */
+
+// `@jupyterlab/apputils`' barrel reaches two ESM-only packages the repo jest
+// config's `esModules` allowlist does not carry - the same two `panel.spec.ts`
+// stubs, for the same reason.
+jest.mock('@jupyter/react-components', () => ({}));
+jest.mock('@jupyter/web-components', () => ({
+  addJupyterLabThemeChangeListener: () => undefined,
+  applyJupyterTheme: () => undefined,
+  jpButton: () => undefined,
+  jpToolbar: () => undefined,
+  provideJupyterDesignSystem: () => ({ register: () => undefined })
+}));
+// Both tokens are named in the plugin's `optional:` list, so both packages
+// load for real; `@jupyterlab/terminal` pulls the ESM-only `color` package and
+// the tab extension ships untransformed ESM. Neither token is used here.
+jest.mock('@jupyterlab/terminal', () => ({ ITerminalTracker: {} }));
+jest.mock('jupyterlab_colourful_tab_extension', () => ({ IColourfulTabs: {} }));
+// No route in this spec reaches the server.
+jest.mock('../core/request', () => ({
+  requestAPI: jest.fn(),
+  requestProvider: jest.fn(() => Promise.resolve({})),
+  isRequestTimeout: () => false,
+  isResponseStatus: () => false,
+  withQuery: (path: string) => path
+}));
+
+import { CommandRegistry } from '@lumino/commands';
+import { Signal } from '@lumino/signaling';
+
+import { AssistantSessionsPanel } from '../core/panel';
+import { requestAPI } from '../core/request';
+import plugin from '../index';
+
+const request = requestAPI as jest.Mock;
+
+/** Drain the microtask queue - `probeStatus().then(reconcile)` and nothing
+ * longer-lived, so no timer is involved. */
+async function flush(turns = 8): Promise<void> {
+  for (let i = 0; i < turns; i += 1) {
+    await Promise.resolve();
+  }
+}
+
+describe('DEF-GUARD-139 - reconcile hands a late roster to a docked panel', () => {
+  it('a panel docked before the first roster gains the root and the trash flag', async () => {
+    let roster: unknown = null;
+    request.mockImplementation((path: string) =>
+      path === 'status' && roster
+        ? Promise.resolve(roster)
+        : Promise.reject(new Error('server down'))
+    );
+
+    const docked: AssistantSessionsPanel[] = [];
+    const labShell = {
+      add: (w: AssistantSessionsPanel) => {
+        docked.push(w);
+      }
+    } as any;
+    const app = {
+      serviceManager: { serverSettings: {} },
+      commands: new CommandRegistry(),
+      hasPlugin: () => false
+    } as any;
+    const settings = {
+      composite: {},
+      get: () => ({ composite: undefined, user: undefined }),
+      set: async () => undefined,
+      changed: new Signal<unknown, void>({})
+    };
+    const settingRegistry = { load: async () => settings } as any;
+    const fileBrowser = { model: { path: 'data/raw' } } as any;
+
+    await (plugin.activate as any)(
+      app,
+      labShell,
+      null,
+      settingRegistry,
+      null,
+      fileBrowser,
+      null
+    );
+
+    // The activation probe failed, so every enabled assistant docked with no
+    // root and, with the roster unknown, with trash treated as unavailable.
+    const panel = docked.find(w => w.node.dataset.provider === 'claude')!;
+    expect(panel).toBeDefined();
+    expect((panel as any)._rootDir).toBe('');
+    expect((panel as any)._deleteToTrash).toBe(false);
+
+    // A later probe answers. The panel is already live, so `start` is not the
+    // path that carries the root to it - `reconcile` is.
+    roster = {
+      providers: [
+        { id: 'claude', available: true },
+        { id: 'codex', available: true },
+        { id: 'kimi', available: true },
+        { id: 'gemini', available: true }
+      ],
+      root_dir: '/srv/lab',
+      delete_to_trash: true
+    };
+    window.dispatchEvent(new Event('online'));
+    await flush();
+
+    // How this fails: drop the `panel.setRoot(...)` call in `reconcile` and
+    // the root stays empty forever - the + button never arms and every path
+    // resolution answers "outside the JupyterLab root".
+    expect((panel as any)._rootDir).toBe('/srv/lab');
+    expect((panel as any)._deleteToTrash).toBe(true);
+    expect((panel as any)._currentFolder()).toBe('/srv/lab/data/raw');
+
+    docked.forEach(w => w.dispose());
+  });
+});

package/src/__tests__/panel.spec.ts

@@ -37,10 +37,15 @@ jest.mock('@jupyter/web-components', () => ({
 // before each act rather than asserted from construction.
 jest.mock('../core/request', () => ({
   requestProvider: jest.fn(() => Promise.resolve({})),
-  isResponseStatus: () => false,
+  // Shape-based rather than `instanceof`, so a test can hand the panel the
+  // refusal a route answers with without building a real `Response`.
+  isRequestTimeout: (err: any) => err?.name === 'RequestTimeoutError',
+  isResponseStatus: (err: any, status: number) =>
+    err?.response?.status === status,
   withQuery: (path: string) => path
 }));
 
+import { Notification } from '@jupyterlab/apputils';
 import { TAB_COLOUR_IDS, fnv1aColour } from '../core/colour';
 import { addIcon, branchIcon, cleanupIcon, shieldIcon } from '../core/icons';
 import { AssistantSessionsPanel, commandId } from '../core/panel';
@@ -622,3 +627,167 @@ describe('DEF-46 - the row tooltip names only a mode the row launches with', ()
     expect(text).not.toContain('Launch mode');
   });
 });
+
+describe('DEF-132 - a panel docked before the first roster has no root', () => {
+  function rootless(): AssistantSessionsPanel {
+    return new AssistantSessionsPanel({
+      app: {
+        serviceManager: { serverSettings: {} },
+        commands: { execute: jest.fn() }
+      } as any,
+      descriptor: { ...DESCRIPTOR, iconName: 'testbed-rootless-panel-spec' },
+      rootDir: '',
+      fileBrowser: { model: { path: 'data/raw' } } as any
+    });
+  }
+
+  it('the + button is inert until setRoot supplies the root', async () => {
+    const p = rootless();
+    await flush();
+    request.mockClear();
+
+    // Without the guard this is `/data/raw` - a folder at the filesystem
+    // root, which the server accepts whenever it happens to exist.
+    expect((p as any)._currentFolder()).toBe('');
+    await (p as any)._newSession();
+    expect(request).not.toHaveBeenCalled();
+    // And the button says so, rather than looking live and doing nothing.
+    const newBtn = p.node.querySelector<HTMLButtonElement>(
+      '.jp-AiAssistantsPanel-iconButton'
+    )!;
+    expect(newBtn.disabled).toBe(true);
+    expect(newBtn.title).toBe('Waiting for the server root');
+
+    p.setRoot('/srv/lab/', true);
+    expect((p as any)._currentFolder()).toBe('/srv/lab/data/raw');
+    expect(newBtn.disabled).toBe(false);
+    expect(newBtn.title).toMatch(/^New session in current folder/);
+    p.setRoot('/', true);
+    expect((p as any)._currentFolder()).toBe('/data/raw');
+    p.dispose();
+  });
+
+  it('the path actions name the missing root, not a folder outside it', async () => {
+    const p = rootless();
+    await flush();
+    const warn = jest.spyOn(Notification, 'warning').mockReturnValue('' as any);
+
+    // The folder is INSIDE the root the server has not sent yet, so blaming
+    // the root is the one diagnosis that cannot be acted on (DEF-134).
+    (p as any)._activeSession = session({ project_path: '/srv/lab/proj' });
+    await (p as any)._commands.execute(commandId('testbed', 'open-terminal'));
+    await (p as any)._commands.execute(
+      commandId('testbed', 'show-in-filebrowser')
+    );
+    expect(warn.mock.calls.map(c => String(c[0]))).toEqual([
+      'Waiting for the server root - cannot open a terminal yet.',
+      'Waiting for the server root - the file browser cannot show it yet.'
+    ]);
+
+    // And the outside case is still named, rather than deleted with it.
+    warn.mockClear();
+    p.setRoot('/srv/lab', true);
+    (p as any)._activeSession = session({ project_path: '/elsewhere/proj' });
+    await (p as any)._commands.execute(commandId('testbed', 'open-terminal'));
+    expect(String(warn.mock.calls[0][0])).toContain(
+      'outside the JupyterLab root'
+    );
+    p.dispose();
+  });
+
+  // DEF-136 - the root can land after the rows are already on screen.
+
+  it('a root arriving after the rows redraws their tooltips', async () => {
+    const p = rootless();
+    await flush();
+    render(p, [session()]);
+
+    // Pre-roster the absolute path is the honest fallback.
+    const row = p.node.querySelector<HTMLElement>('.jp-AiAssistantsPanel-row')!;
+    expect(row.title).toContain('Path: /home/user/proj');
+
+    p.setRoot('/home/user', true);
+    expect(
+      p.node.querySelector<HTMLElement>('.jp-AiAssistantsPanel-row')!.title
+    ).toContain('Path: proj');
+    p.dispose();
+  });
+
+  it('a root arriving after the rows redraws their labels in path mode', async () => {
+    const p = rootless();
+    await flush();
+    p.setPresentationMode('path');
+    render(p, [session()]);
+    expect(
+      p.node.querySelector('.jp-AiAssistantsPanel-nameText')!.textContent
+    ).toBe('/home/user/proj');
+
+    p.setRoot('/home/user', true);
+    expect(
+      p.node.querySelector('.jp-AiAssistantsPanel-nameText')!.textContent
+    ).toBe('proj');
+    p.dispose();
+  });
+
+  it('an unchanged root does not redraw - the reconcile tick repeats it', async () => {
+    const p = rootless();
+    await flush();
+    render(p, [session()]);
+    p.setRoot('/home/user', true);
+
+    const spy = jest.spyOn(p as any, '_render');
+    p.setRoot('/home/user', true);
+    p.setRoot('/home/user/', true);
+    expect(spy).not.toHaveBeenCalled();
+    p.dispose();
+  });
+});
+
+// --------------------------------------------------------------- DEF-138
+
+describe('DEF-138 - a refused listing names the missing binary', () => {
+  const banner = (): string =>
+    panel.node.querySelector<HTMLElement>('.jp-AiAssistantsPanel-error')!
+      .textContent ?? '';
+
+  beforeEach(() => {
+    jest.spyOn(console, 'error').mockImplementation(() => undefined);
+  });
+
+  /** What `requestAPI` throws for the server's `{"error": "cli_not_found"}` -
+   * the only 503 a listing can be refused with. */
+  const cliNotFound = (): Error =>
+    Object.assign(new Error('cli_not_found'), {
+      name: 'ResponseError',
+      response: { status: 503 }
+    });
+
+  it('names the binary instead of blaming the server', () => {
+    (panel as any)._showError(cliNotFound());
+    expect(banner()).toContain('`testbed` was not found');
+    expect(banner()).not.toContain('Could not reach the server');
+  });
+
+  it("leaves a 503 that is not this extension's own alone", () => {
+    // What a hub proxy or a stopped single-user server answers: a 503 whose
+    // body is HTML, so `requestAPI` hands the raw text through as the message.
+    (panel as any)._showError(
+      Object.assign(new Error('<html>503 Service Unavailable</html>'), {
+        name: 'ResponseError',
+        response: { status: 503 }
+      })
+    );
+    expect(banner()).toContain('Could not reach the server');
+    expect(banner()).not.toContain('was not found');
+  });
+
+  it('leaves the two unanswered-server verdicts alone', () => {
+    (panel as any)._showError(
+      Object.assign(new Error('timed out'), { name: 'RequestTimeoutError' })
+    );
+    expect(banner()).toContain('The server is not answering');
+
+    (panel as any)._showError(new TypeError('Failed to fetch'));
+    expect(banner()).toContain('Could not reach the server');
+  });
+});

package/src/__tests__/request.spec.ts

@@ -195,3 +195,50 @@ describe('requestAPI with a caller-supplied signal', () => {
     ).resolves.toEqual({ ok: true });
   });
 });
+
+describe('requestAPI on a body it cannot parse', () => {
+  it('refuses a 200 that is not JSON instead of returning the raw string', async () => {
+    // DEF-118: every handler in `core/routes.py` finishes `json.dumps`, so a
+    // 200 this helper cannot parse came from something in front of the server.
+    // Returned as data, `status.providers` read `undefined` and every panel
+    // undocked; thrown, the probe FAILS and the last roster stands (DEF-132).
+    makeRequest.mockResolvedValue({
+      ok: true,
+      status: 200,
+      text: async () =>
+        '<!doctype html><html><head><title>Sign in</title></head><body>SSO</body></html>'
+    } as unknown as Response);
+
+    await expect(requestAPI('status', SETTINGS)).rejects.toThrow(
+      /was not JSON/
+    );
+  });
+
+  it('still resolves an empty 200 body to the empty string', async () => {
+    // The `data.length > 0` guard is untouched: a 204-shaped answer is not a
+    // parse failure and must not become one.
+    makeRequest.mockResolvedValue({
+      ok: true,
+      status: 200,
+      text: async () => ''
+    } as unknown as Response);
+
+    await expect(requestAPI('status', SETTINGS)).resolves.toBe('');
+  });
+
+  it('keeps a refused non-JSON body a ResponseError', async () => {
+    // The refusal side is the DEF-116 case - a proxy error page - and it must
+    // keep carrying the body as the `ResponseError` message rather than
+    // becoming the new error.
+    makeRequest.mockResolvedValue({
+      ok: false,
+      status: 502,
+      text: async () => '<html>bad gateway</html>'
+    } as unknown as Response);
+
+    const error = await capture(requestAPI('status', SETTINGS));
+
+    expect(error).toBeInstanceOf(ServerConnection.ResponseError);
+    expect((error as Error).message).toContain('bad gateway');
+  });
+});

package/src/core/panel.ts

@@ -171,13 +171,7 @@ export class AssistantSessionsPanel extends Widget {
     this._descriptor = options.descriptor;
     this._hooks = options.hooks ?? {};
     this._serverSettings = options.app.serviceManager.serverSettings;
-    // Trailing slashes go, but never the root itself: serving JupyterLab at
-    // `/` used to normalise to the empty string, which reads as "no root" -
-    // the + button then did nothing at all, and Open Terminal and Show in File
-    // Browser answered "outside the JupyterLab root" for every row inside it.
-    const root = (options.rootDir || '').replace(/\/+$/, '');
-    this._rootDir = root || (options.rootDir ? '/' : '');
-    this._deleteToTrash = options.deleteToTrash !== false;
+    this.setRoot(options.rootDir, options.deleteToTrash !== false);
     this._fileBrowser = options.fileBrowser ?? null;
     this._expandedKey = `jupyterlab_ai_code_assistants_extension:${this._descriptor.id}:expanded`;
     this._expanded = loadExpanded(this._expandedKey);
@@ -323,8 +317,15 @@ export class AssistantSessionsPanel extends Widget {
     // and this button LAUNCHES on click instead of dropping a menu, so without
     // the suffix the one surface that starts an approval-free session is the
     // only one that never says so (DEF-36, DEF-113, DEF-114).
+    // Disabled, not silent, while the server root is unknown (a panel docked
+    // before the first status roster, DEF-132): a healthy-looking button that
+    // does nothing on click cannot be diagnosed by the user. `setRoot` re-runs
+    // this once the root lands, so the state is data-driven, not timed.
     const nameNewButton = (): void => {
-      newBtn.title = `New session in current folder${this._variantSuffix()}`;
+      newBtn.disabled = !this._rootDir;
+      newBtn.title = this._rootDir
+        ? `New session in current folder${this._variantSuffix()}`
+        : 'Waiting for the server root';
     };
     // Focus as well as hover, or the icon-only button's accessible name is the
     // generic one for everybody not using a mouse.
@@ -589,6 +590,22 @@ export class AssistantSessionsPanel extends Widget {
   private _showError(err: unknown): void {
     const message = err instanceof Error ? err.message : String(err);
     this._logError(message);
+
+    // DEF-138: the server ANSWERED, and its answer is that this assistant's
+    // binary is not on the PATH the Jupyter server runs with. Blaming the
+    // server names the wrong cause - the panel is docked only because no
+    // roster has arrived yet, and the roster is what removes it (DEF-132).
+    // The error code is matched as well as the status, because a 503 raised
+    // by a proxy or a stopped single-user server is NOT this: its body never
+    // parses to `{"error": "cli_not_found"}`, so it keeps the copy below.
+    if (isResponseStatus(err, 503) && message === 'cli_not_found') {
+      this._setInlineError(
+        `\`${this._descriptor.cliBinary}\` was not found on the Jupyter ` +
+          `server's PATH.`
+      );
+      return;
+    }
+
     const copy = isRequestTimeout(err)
       ? 'The server is not answering - retrying.'
       : 'Could not reach the server - retrying.';
@@ -841,9 +858,43 @@ export class AssistantSessionsPanel extends Widget {
     }
   }
 
+  /** The server root every path is shown and resolved against, plus
+   * JupyterLab's move-to-trash setting. Settable because a panel docked before
+   * the server has answered its first status probe is built without either
+   * (DEF-132); the action paths read them lazily, so a late value applies on
+   * the next click, and a root arriving after rows were drawn redraws them
+   * once (DEF-136).
+   *
+   * Trailing slashes go, but never the root itself: serving JupyterLab at
+   * `/` used to normalise to the empty string, which reads as "no root" -
+   * the + button then did nothing at all, and Open Terminal and Show in File
+   * Browser answered "outside the JupyterLab root" for every row inside it. */
+  setRoot(rootDir: string, deleteToTrash: boolean): void {
+    const root = (rootDir || '').replace(/\/+$/, '');
+    const next = root || (rootDir ? '/' : '');
+    const changed = next !== this._rootDir;
+    this._rootDir = next;
+    this._deleteToTrash = deleteToTrash;
+    this._renameNewButton?.();
+    // Guarded on the VALUE, not on the call: `reconcile` re-sends the same
+    // root every status tick, so a changed-guard redraws exactly once, on the
+    // '' -> root transition. `_sessions` stands in for "the shell is built and
+    // rows are on screen" - it is null until the first `_fetch` answers, which
+    // is what keeps the constructor's own `setRoot` from reaching `_render`
+    // before `_buildShell` has created `_bodyEl`.
+    if (changed && this._sessions !== null) {
+      this._render();
+    }
+  }
+
   /** Absolute path of the file browser's current folder; the server root when
    * no file browser is available. */
   private _currentFolder(): string {
+    // No roster yet (DEF-132): a relative folder joined to an empty root
+    // would be an absolute path at the filesystem root.
+    if (!this._rootDir) {
+      return '';
+    }
     const rel = (this._fileBrowser?.model?.path ?? '').replace(/^\/+/, '');
     if (!rel) {
       return this._rootDir;
@@ -2054,8 +2105,12 @@ export class AssistantSessionsPanel extends Widget {
         // absolute filesystem path, so it goes through _pathUnderRoot.
         const rel = this._pathUnderRoot(s.project_path);
         if (rel === null) {
+          // A root the server has not sent yet is not a folder outside it
+          // (DEF-134).
           Notification.warning(
-            'Folder is outside the JupyterLab root - cannot open a terminal there.',
+            this._rootDir
+              ? 'Folder is outside the JupyterLab root - cannot open a terminal there.'
+              : 'Waiting for the server root - cannot open a terminal yet.',
             { autoClose: 4000 }
           );
           return;
@@ -2081,8 +2136,12 @@ export class AssistantSessionsPanel extends Widget {
         }
         const rel = this._pathUnderRoot(s.project_path);
         if (rel === null) {
+          // A root the server has not sent yet is not a folder outside it
+          // (DEF-134).
           Notification.warning(
-            'Folder is outside the JupyterLab root - the file browser cannot show it.',
+            this._rootDir
+              ? 'Folder is outside the JupyterLab root - the file browser cannot show it.'
+              : 'Waiting for the server root - the file browser cannot show it yet.',
             { autoClose: 4000 }
           );
           return;
@@ -2603,8 +2662,8 @@ export class AssistantSessionsPanel extends Widget {
   private readonly _descriptor: IProviderDescriptor;
   private readonly _hooks: IProviderHooks;
   private readonly _serverSettings: ServerConnection.ISettings;
-  private readonly _rootDir: string;
-  private readonly _deleteToTrash: boolean;
+  private _rootDir = '';
+  private _deleteToTrash = true;
   private readonly _fileBrowser: IDefaultFileBrowser | null;
   private readonly _colours: ColourStore;
   private readonly _terminals: TerminalManager;

package/src/core/request.ts

@@ -71,6 +71,7 @@ export function isRequestTimeout(err: unknown): boolean {
  * @returns The response body interpreted as JSON
  * @throws RequestTimeoutError when the deadline passes before the server
  *   answers
+ * @throws Error when a 200 carries a body this helper cannot parse
  */
 export async function requestAPI<T>(
   endPoint: string,
@@ -129,7 +130,26 @@ export async function requestAPI<T>(
     try {
       data = JSON.parse(data);
     } catch {
-      console.log(`${LOG_PREFIX} Not a JSON response body.`, response);
+      if (response.ok) {
+        // DEF-118: every handler in `core/routes.py` finishes `json.dumps`, so
+        // a 200 this helper cannot parse did not come from this server - it is
+        // an SSO or proxy interstitial served in its place. Returning the raw
+        // string let every caller read `undefined` off it: `probeStatus` wrote
+        // a roster with no `providers` and `reconcile` undocked all four
+        // panels, `_fetch` rendered an empty session list, and
+        // `ColourStore.load` replaced the cache with an empty map. Refusing it
+        // makes the probe FAIL, and a failed probe writes nothing (DEF-132),
+        // so the last known roster stands.
+        throw new Error(
+          `Response to ${endPoint} was not JSON (HTTP ${response.status})`
+        );
+      }
+      // Not ok: the `ResponseError` below carries this body as its message, so
+      // this side is no longer a silent path and a proxy's error page here is
+      // noise (DEF-116). This is the conditional DEF-118 recorded - `debug`
+      // only on the refusal side; the 200 side is now louder than the `warn`
+      // it asked for.
+      console.debug(`${LOG_PREFIX} Not a JSON response body.`, response);
     }
   }
 

package/src/index.ts

@@ -116,37 +116,29 @@ const plugin: JupyterFrontEndPlugin<void> = {
     let settings: ISettingRegistry.ISettings | null = null;
     let sidebar: Sidebar = DEFAULT_SIDEBAR;
 
-    let probeGeneration = 0;
-
     /** Ask the server which providers exist and which of their binaries are on
-     * PATH. An unsuperseded failure leaves the extension activated with no
-     * panels until a later probe succeeds - never a dialog, never a thrown
-     * activation.
+     * PATH.
      *
-     * Probes overlap: a probe can outlive one issued after it, so verdicts do
-     * not arrive in the order they were asked for. A ROSTER is always written,
-     * whichever settles last - both are answers from the same server, and the
-     * loser is at worst one client deadline stale (DEF-125). A FAILURE is not an answer, so it
-     * is written only while no newer probe has been issued; otherwise a
-     * timeout could discard a roster the server has since confirmed, undocking
-     * every panel while it is healthy (DEF-121). No request is suppressed. */
+     * `status` is the last roster the server gave, and null means it has never
+     * given one - two different facts that used to share one value. A probe
+     * that FAILS writes nothing: not answering is not an answer, and reading it
+     * as "no assistant is installed" is what emptied the sidebar on every
+     * reload whose first request landed before the server was listening
+     * (DEF-132), and on every wake whose probe fired before the network was
+     * back (DEF-119). No request is suppressed, and a failure never needs
+     * ordering against a success, because it has nothing to write. */
     const probeStatus = async (): Promise<void> => {
-      const mine = ++probeGeneration;
       try {
         status = await requestAPI<IStatusResponse>('status', serverSettings, {
           cache: 'no-store'
         });
       } catch (err) {
-        // No cadence named here: this also prints from the activation probe,
-        // and neither the interval nor the wake listeners are armed until
-        // after `await migrate()` below (DEF-122).
+        // No cadence named: this also prints from the activation probe, before
+        // the interval and the wake listeners are armed (DEF-122).
         console.warn(
-          `${LOG_PREFIX} status probe failed; panels dock again once a later probe succeeds.`,
+          `${LOG_PREFIX} status probe failed; the last known roster stands (every enabled assistant, when there is none yet) until a later probe answers.`,
           err
         );
-        if (mine === probeGeneration) {
-          status = null;
-        }
       }
     };
 
@@ -214,7 +206,10 @@ const plugin: JupyterFrontEndPlugin<void> = {
           descriptor: module.descriptor,
           hooks: module.hooks,
           rootDir: status?.root_dir ?? '',
-          deleteToTrash: status?.delete_to_trash !== false,
+          // Unknown reads as "not trash": the popup then arms its Delete
+          // button before it executes, which is the only confirmation a
+          // permanent bulk delete has (DEF-135).
+          deleteToTrash: status ? status.delete_to_trash !== false : false,
           terminalTracker,
           fileBrowser,
           colourfulTabs
@@ -258,16 +253,23 @@ const plugin: JupyterFrontEndPlugin<void> = {
         const enabled =
           setting<boolean>(`providers.${id}.enabled`, true) !== false;
         const probe = statusFor(id);
-        const available = probe ? probe.available !== false : false;
+        // Unknown is not absent. With no roster yet, an enabled assistant is
+        // docked: JupyterLab restores the sidebar tab it had open only if that
+        // tab exists when activation ends, and it waits for activation but
+        // not for a later probe - so a panel that arrives a minute late is one
+        // the layout has already given up on (DEF-132). Once a roster exists
+        // the server's word on each binary is final.
+        const roster = status;
+        const available =
+          roster === null ? true : probe !== null && probe.available !== false;
         // Enabled but binary absent must not be a silent state: the user sees
         // a missing panel with no clue that PATH under the Jupyter server
         // differs from their shell. Once per id, not per reconcile.
         // Only when the probe SUCCEEDED and this provider is the one missing.
-        // A failed probe sets every provider unavailable, and blaming PATH for
-        // a server the frontend never reached names the wrong cause; and every
-        // provider defaults to enabled, so a machine with one assistant
-        // installed would otherwise raise three toasts about assistants the
-        // user has never heard of. The console line stays for that case.
+        // Blaming PATH for a server the frontend never reached names the wrong
+        // cause; and every provider defaults to enabled, so a machine with one
+        // assistant installed would otherwise raise three toasts about assistants
+        // the user has never heard of. The console line stays for that case.
         const chosen =
           settings?.get(`providers.${id}.enabled`).user !== undefined;
         if (
@@ -294,9 +296,29 @@ const plugin: JupyterFrontEndPlugin<void> = {
             { autoClose: 8000 }
           );
         }
+        // The latch is per ABSENCE, not per page load. Once the server reports
+        // the binary present again, a later disappearance gets its own warning:
+        // without this, one transient absence - a CLI upgrade unlinking the
+        // binary for a moment, or an obsolete roster from an overlapping probe -
+        // permanently suppresses the real one (DEF-125). It cannot make the
+        // warning repeat while the state is unchanged, which is what the
+        // once-per-id latch above exists to prevent: the two conditions are
+        // mutually exclusive.
+        if (probe !== null && probe.available !== false) {
+          warnedUnavailable.delete(id);
+        }
         if (enabled && available) {
           if (live.has(id)) {
-            applySharedSettings(live.get(id)!.panel);
+            const panel = live.get(id)!.panel;
+            applySharedSettings(panel);
+            // A panel docked before the first roster was built without the
+            // server root, and cannot resolve paths until it has one.
+            if (roster !== null) {
+              panel.setRoot(
+                roster.root_dir ?? '',
+                roster.delete_to_trash !== false
+              );
+            }
           } else {
             start(id);
           }
@@ -410,8 +432,8 @@ const plugin: JupyterFrontEndPlugin<void> = {
     }, STATUS_INTERVAL_MS);
 
     // A suspended network stack - laptop asleep, tab backgrounded - is exactly
-    // when the probe fails, and the slow cadence above would leave the sidebar
-    // panel-less for up to a minute after the machine comes back. A wake fires
+    // when the probe fails, and the slow cadence above would leave the roster
+    // stale for up to a minute after the machine comes back. A wake fires
     // both events, so it costs two probes; deliberately, because a guard that
     // let the second join the first answered the wake with a request issued
     // before it, and starved the interval above of its own tick (DEF-117).

package/style/base.css

@@ -61,7 +61,14 @@
   color: var(--jp-ui-font-color2);
 }
 
-.jp-AiAssistantsPanel-iconButton:hover {
+/* The + button while the server root is unknown (DEF-132): the glyph is an
+   icon fill, not `color`, so the UA's disabled styling never reaches it. */
+.jp-AiAssistantsPanel-iconButton:disabled {
+  cursor: default;
+  opacity: 0.4;
+}
+
+.jp-AiAssistantsPanel-iconButton:hover:not(:disabled) {
   background: var(--jp-layout-color3);
   color: var(--jp-ui-font-color1);
 }