@kabmo-labs/kabmo 0.3.1 → 0.4.0

package/src/server/routes/waiting/index.ts

@@ -0,0 +1,123 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `/api/waiting` — prompts held until another session finishes.
+ *
+ * The list is also served over the `waiting` realtime topic, which is what the
+ * sidebar and the composer read; these routes exist for the create/cancel
+ * actions and as the read path for a client whose socket is down.
+ *
+ * Validation is the last gate before the row. In particular the dependency must
+ * look UNFINISHED at creation: a dropdown that went stale (the session finished
+ * while the user was typing) would otherwise create a prompt that is released on
+ * the very next sweep — a prompt the user believed they had deferred. The client
+ * re-checks and sends normally instead; this is the server's own refusal for a
+ * client that did not.
+ */
+
+import { isAbsolute } from 'path';
+import { json } from '@/server/lib/remix-compat';
+import type { ActionFunctionArgs, LoaderFunctionArgs } from '@/server/lib/remix-compat';
+import { methodNotAllowed } from '@/server/lib/route-adapter';
+import { emitRealtimeSignal } from '@/server/lib/realtime/signals.server';
+import { isDependencySettled } from '@/server/lib/waiting/runtime.server';
+import {
+  cancelWaitingPrompt,
+  createWaitingPrompt,
+  getWaitingPrompt,
+  listWaitingPrompts,
+} from '@/server/lib/waiting/store.server';
+import { attachmentHasPayload } from '@/shared/lib/chat/attachments';
+import { parseModeSelection } from '@/server/lib/omp/mode/request';
+import { isSinglePathSegment } from '@/server/lib/fs/path-segment';
+import { isMockMode } from '@/server/mock.server';
+
+/** GET — every prompt a client may still need (waiting + recent outcomes). */
+export async function loader(_args: LoaderFunctionArgs) {
+  return json({ prompts: await listWaitingPrompts() });
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+}
+
+/** POST — hold a prompt until `dependsOn` finishes. */
+async function createPrompt(request: Request) {
+  // A demo install spawns no omp child, so a held prompt could never be sent.
+  // Refused with the reason instead of creating a row that waits forever.
+  if (isMockMode()) {
+    return json(
+      { error: 'Held prompts need a real omp session — this console is running on demo data.', code: 'mock_mode' },
+      { status: 409 },
+    );
+  }
+  const body = asRecord(await request.json().catch(() => null));
+  const dependsOn = typeof body.dependsOn === 'string' ? body.dependsOn.trim() : '';
+  if (!dependsOn || !isSinglePathSegment(dependsOn)) {
+    return json({ error: 'A session to wait for is required', code: 'depends_on_required' }, { status: 400 });
+  }
+  const prompt = typeof body.prompt === 'string' ? body.prompt : '';
+  const attachments = Array.isArray(body.attachments) ? body.attachments : [];
+  // Same rule the composer's own send guard applies: an empty prompt is not a
+  // prompt. Without it a row would be created, spawn a session, and deliver
+  // nothing to it.
+  if (!prompt.trim() && !attachments.some((attachment) => attachmentHasPayload(attachment as never))) {
+    return json({ error: 'The prompt is empty', code: 'prompt_required' }, { status: 400 });
+  }
+  const cwd = typeof body.cwd === 'string' ? body.cwd.trim() : '';
+  // `isAbsolute`, not `startsWith('/')`: a Windows workspace names its directory
+  // `C:\…`, and the POSIX-only test refused every hold there with
+  // `cwd_required` — the prompt was sent immediately instead of being held
+  // (measured on the Windows CI leg of `waiting-prompt.e2e.ts`).
+  if (!isAbsolute(cwd)) {
+    return json({ error: 'An absolute working directory is required', code: 'cwd_required' }, { status: 400 });
+  }
+  if (await isDependencySettled(dependsOn)) {
+    return json(
+      { error: 'That session has already finished — send the prompt without waiting.', code: 'dependency_idle' },
+      { status: 409 },
+    );
+  }
+
+  const created = await createWaitingPrompt({
+    pendingId: typeof body.pendingId === 'string' ? body.pendingId : null,
+    dependsOn,
+    dependsOnTitle: typeof body.dependsOnTitle === 'string' ? body.dependsOnTitle : null,
+    prompt,
+    attachments,
+    model: body.model,
+    modes: body.modes === undefined ? null : parseModeSelection(asRecord(body.modes)),
+    cwd,
+    folderId: typeof body.folderId === 'number' ? body.folderId : null,
+  });
+  emitRealtimeSignal('waiting-changed');
+  return json({ prompt: created });
+}
+
+/** DELETE `?id=` — cancel a prompt that has not been dispatched yet. */
+async function cancelPrompt(request: Request) {
+  const id = new URL(request.url).searchParams.get('id') ?? '';
+  if (!id) return json({ error: 'id is required', code: 'id_required' }, { status: 400 });
+  const existing = await getWaitingPrompt(id);
+  if (!existing) return json({ error: 'Waiting prompt not found' }, { status: 404 });
+  if (existing.status === 'dispatched') {
+    // The prompt has already become a session: Stop that session instead. Saying
+    // so is the difference between "cancel did nothing" and a next step.
+    return json(
+      { error: 'That prompt has already been sent — stop its session instead.', code: 'already_dispatched' },
+      { status: 409 },
+    );
+  }
+  const cancelled = await cancelWaitingPrompt(id);
+  if (cancelled) emitRealtimeSignal('waiting-changed');
+  return json({ cancelled, prompt: await getWaitingPrompt(id) });
+}
+
+export async function action({ request }: ActionFunctionArgs) {
+  if (request.method === 'POST') return createPrompt(request);
+  if (request.method === 'DELETE') return cancelPrompt(request);
+  return methodNotAllowed({ request, params: {} });
+}

package/src/server/routes/waiting/routes.test.ts

@@ -0,0 +1,121 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `/api/waiting` POST — the refusals that guard the row.
+ *
+ * The case worth pinning is the WORKING DIRECTORY, because it is the one that
+ * only fails on a platform the author does not run: the route tested
+ * `cwd.startsWith('/')`, so every hold from a Windows workspace (`C:\…`) was
+ * refused with `cwd_required` and the prompt was sent immediately instead of
+ * being deferred — measured on the Windows CI leg of
+ * `waiting-prompt.e2e.ts`, where the browser showed the toast and the row was
+ * never created. The fix is `path.isAbsolute`, which is what this asserts on
+ * both platform shapes rather than only the one this run happens to be on.
+ *
+ * Everything else here is the validation order a stale client can reach: a
+ * missing dependency, an empty prompt, a mock install.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { isolateDb, releaseDb } from '@/test-support/isolated-db';
+import { action } from '@/server/routes/waiting/index';
+import { listWaitingPrompts } from '@/server/lib/waiting/store.server';
+
+const ROOT = path.join(os.tmpdir(), `kabmo-waiting-routes-${process.pid}`);
+
+function post(body: unknown): Request {
+  return new Request('http://localhost/api/waiting', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+}
+
+async function call(body: unknown): Promise<{ status: number; body: Record<string, unknown> }> {
+  const res = (await action({ request: post(body), params: {} } as never)) as Response;
+  return { status: res.status, body: (await res.json()) as Record<string, unknown> };
+}
+
+beforeAll(async () => {
+  fs.mkdirSync(ROOT, { recursive: true });
+  isolateDb();
+});
+
+afterAll(async () => {
+  releaseDb();
+  fs.rmSync(ROOT, { recursive: true, force: true });
+});
+
+describe('/api/waiting — working directory', () => {
+  // The rule is the SERVER's own platform rule (`path.isAbsolute`), because a
+  // hold's cwd is a directory on the machine that will spawn the session — the
+  // client sends the folder's stored `project_path`, which the server resolved.
+  //
+  // This table is derived from `path.isAbsolute` rather than written out, so it
+  // is a real regression net on BOTH legs: on Windows it feeds `C:\…`, which
+  // the old `startsWith('/')` refused, and on POSIX it feeds `/…`. Hardcoding
+  // either spelling would assert the platform this run happens to be on.
+  //
+  // The dependency must look UNFINISHED for a create to reach the store, and a
+  // session id nothing has ever streamed is settled by definition — so these
+  // cases assert the CWD verdict, which is decided BEFORE that read.
+  const shapes = [
+    path.join(ROOT, 'projects', 'kabmo'),
+    '/home/dev/projects/kabmo',
+    'C:\\Users\\dev\\projects\\kabmo',
+    '\\\\server\\share\\kabmo',
+    'projects/kabmo',
+    'C:relative',
+    '',
+  ];
+
+  for (const cwd of shapes) {
+    const absolute = path.isAbsolute(cwd);
+    test(`${JSON.stringify(cwd)} is ${absolute ? 'accepted' : 'refused as relative'}`, async () => {
+      const res = await call({ dependsOn: 'sess-anything', prompt: 'held', cwd });
+      if (absolute) {
+        // `dependency_idle` is the next gate: the cwd passed.
+        expect(res.body.code).not.toBe('cwd_required');
+      } else {
+        expect(res.status).toBe(400);
+        expect(res.body.code).toBe('cwd_required');
+      }
+    });
+  }
+
+  test('a whitespace-only path is refused, never trimmed into a valid one', async () => {
+    const res = await call({ dependsOn: 'sess-anything', prompt: 'x', cwd: '   ' });
+    expect(res.status).toBe(400);
+    expect(res.body.code).toBe('cwd_required');
+  });
+});
+
+describe('/api/waiting — the rest of the validation order', () => {
+  test('a missing dependency is refused before the path is read', async () => {
+    const res = await call({ prompt: 'x', cwd: '/tmp/x' });
+    expect(res.status).toBe(400);
+    expect(res.body.code).toBe('depends_on_required');
+  });
+
+  test('a dependency that could name a path is refused', async () => {
+    const res = await call({ dependsOn: '../../etc', prompt: 'x', cwd: '/tmp/x' });
+    expect(res.body.code).toBe('depends_on_required');
+  });
+
+  test('an empty prompt with no attachment is refused', async () => {
+    const res = await call({ dependsOn: 'sess-anything', prompt: '  ', cwd: '/tmp/x' });
+    expect(res.status).toBe(400);
+    expect(res.body.code).toBe('prompt_required');
+  });
+
+  test('a refusal writes no row', async () => {
+    await call({ dependsOn: 'sess-anything', prompt: 'x', cwd: 'relative/path' });
+    expect(await listWaitingPrompts()).toHaveLength(0);
+  });
+});

package/src/shared/lib/chat/timeline/gutter.test.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The transcript's frame inset.
+ *
+ * One rule, four call sites — so it is stated here and asserted, not repeated
+ * as a class string. The bug it prevents was measured on a phone: every framed
+ * block carried `mx-3` on top of the timeline's own `px-3`, putting cards at
+ * 24px while the composer's card sat at 12px. The transcript read as two
+ * columns that never met.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { transcriptBlockPadding, transcriptGutter } from '@/shared/lib/chat/timeline/gutter';
+
+describe('transcriptGutter', () => {
+  test('a phone adds no inset — the timeline container IS the gutter', () => {
+    expect(transcriptGutter(true)).toBe('');
+  });
+
+  test('desktop keeps the 12px inset that pairs with the panel p-4', () => {
+    expect(transcriptGutter(false)).toBe('mx-3');
+  });
+});
+
+describe('transcriptBlockPadding', () => {
+  test('a phone pads to the shared 24px text column (12 frame + 12 padding)', () => {
+    expect(transcriptBlockPadding(true)).toBe('p-3');
+  });
+
+  test('desktop keeps its roomier 14px padding', () => {
+    expect(transcriptBlockPadding(false)).toBe('p-3.5');
+  });
+});

package/src/shared/lib/chat/timeline/gutter.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The horizontal frame inset of a transcript block — a tool card, a thinking
+ * accordion, a system notice, a user bubble.
+ *
+ * Desktop keeps `mx-3`: the timeline's own container is `p-4`, and the extra
+ * 12px is what gives a card the same optical margin as the prose beside it.
+ *
+ * A phone does NOT. Its timeline container is already `px-3`, and that is the
+ * same 12px the composer dock uses — so a block that added another `mx-3` put
+ * every card 12px inside the composer's own edge, and the transcript read as
+ * two columns that never met. On mobile the block's frame IS the gutter.
+ *
+ * Stated once, because the class was written out at four separate call sites
+ * and a missed one is a card sitting 12px off its neighbours.
+ */
+export function transcriptGutter(isMobile: boolean): string {
+  return isMobile ? '' : 'mx-3';
+}
+
+/**
+ * Padding INSIDE a framed transcript block (the user bubble, the provider
+ * error strip).
+ *
+ * The pair with `transcriptGutter` is what keeps a phone's text column on one
+ * line: 12px frame + 12px padding = 24, which is exactly where the prose rows
+ * (`px-3` inside the same container) and the composer's textarea already sit.
+ * Desktop keeps its roomier `p-3.5`, because there the frame is inset and the
+ * text column is not shared with an edge-to-edge composer.
+ */
+export function transcriptBlockPadding(isMobile: boolean): string {
+  return isMobile ? 'p-3' : 'p-3.5';
+}

package/src/shared/lib/realtime/protocol.ts

@@ -101,6 +101,16 @@ export const TOPIC_USAGE = 'usage';
 /** Scheduled tasks. */
 export const TOPIC_SCHEDULE = 'schedule';
 
+/**
+ * Prompts held until another session finishes.
+ *
+ * A global topic rather than per-session: the row belongs to the session that
+ * has NOT been created yet, and the dependency it names is a different session
+ * again. Both the sidebar (to draw the waiting row) and the composer (to offer
+ * the dependencies) read it.
+ */
+export const TOPIC_WAITING = 'waiting';
+
 /** Installed panel plugins and their catalog. */
 export const TOPIC_PANELS = 'panels';
 

package/src/shared/lib/workspace/left-dock-width.ts

@@ -0,0 +1,78 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The LEFT dock's width, remembered PER VIEW.
+ *
+ * The left column used to hold one view, so one number was enough and it lives
+ * in `sidebar-width.ts` (`omp_sidebar_width`). The column is a dock now, and a
+ * plugin panel placed on it wants its own width: a session list reads at 280px
+ * and a table does not, and a column that snapped to the list's width the moment
+ * the user switched views would be a column with one width that is wrong for
+ * every second view.
+ *
+ * GLOBAL, like the sidebar's own width and the right panel's order — the dock
+ * lists the same views in every session, so a width stored per session would
+ * move the layout when the user picked a different chat.
+ *
+ * The sessions view keeps reading `sidebar-width.ts` as its fallback, so an
+ * install that has been dragging the sidebar for a year opens at the width it
+ * was left at rather than at this module's default.
+ */
+
+import { readKabmoSetting, writeSetting } from '@/shared/lib/settings/client';
+import { SESSIONS_VIEW_ID } from '@/shared/lib/workspace/left-dock';
+import {
+  DEFAULT_LEFT_PANEL_WIDTH,
+  MAX_LEFT_PANEL_WIDTH,
+  MIN_LEFT_PANEL_WIDTH,
+  resolveSidebarWidth,
+} from '@/shared/lib/workspace/sidebar-width';
+
+/** `app_settings` key holding the dock's per-view widths, in pixels. */
+export const LEFT_DOCK_WIDTHS_SETTING_KEY = 'omp_left_dock_widths';
+
+/**
+ * Floor for a view that is not the session list.
+ *
+ * A plugin panel declares its own floor (320, `MIN_PLUGIN_PANEL_WIDTH`), and a
+ * column narrower than that clips the view it is showing. The list reads fine
+ * lower, which is why the two differ.
+ */
+export const MIN_LEFT_DOCK_PLUGIN_WIDTH = 320;
+
+function clamped(viewId: string, px: number): number {
+  const floor = viewId === SESSIONS_VIEW_ID ? MIN_LEFT_PANEL_WIDTH : MIN_LEFT_DOCK_PLUGIN_WIDTH;
+  return Math.min(MAX_LEFT_PANEL_WIDTH, Math.max(floor, Math.round(px)));
+}
+
+function readMap(): Record<string, number> {
+  const stored = readKabmoSetting<unknown>(LEFT_DOCK_WIDTHS_SETTING_KEY);
+  if (typeof stored !== 'object' || stored === null) return {};
+  const out: Record<string, number> = {};
+  for (const [view, value] of Object.entries(stored as Record<string, unknown>)) {
+    if (typeof value === 'number' && Number.isFinite(value)) out[view] = value;
+  }
+  return out;
+}
+
+/**
+ * The width this view opens at.
+ *
+ * A remembered width wins; otherwise the session list falls back to the width
+ * `sidebar-width.ts` has always resolved (setting, then the retired global blob,
+ * then the session slot), and a plugin view opens at the dock's plugin default.
+ */
+export function resolveLeftDockWidth(viewId: string): number {
+  const stored = readMap()[viewId];
+  if (stored !== undefined) return clamped(viewId, stored);
+  if (viewId === SESSIONS_VIEW_ID) return resolveSidebarWidth();
+  return clamped(viewId, DEFAULT_LEFT_PANEL_WIDTH);
+}
+
+/** Persist a dragged width for one view. */
+export function saveLeftDockWidth(viewId: string, px: number): void {
+  writeSetting(LEFT_DOCK_WIDTHS_SETTING_KEY, { ...readMap(), [viewId]: clamped(viewId, px) });
+}

package/src/shared/lib/workspace/left-dock.test.ts

@@ -0,0 +1,203 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The left dock's placement rules.
+ *
+ * Three properties, and each fails SILENTLY when broken:
+ *
+ * - **The sessions view is always on the left and cannot be placed anywhere
+ *   else.** It is the dock's own view, so a stored row naming it is dropped
+ *   rather than accepted — otherwise a blob could leave the left column showing
+ *   a plugin with no way back to the session list.
+ * - **A panel is on ONE side at a time.** The same id keys the enablement set,
+ *   the width map and the stored order, so a panel present in both lists would
+ *   be two buttons for one panel and one of them would draw nothing.
+ * - **A row this build does not recognise is dropped.** The list is not only a
+ *   preference here: it decides which buttons the dock draws, so a stale id
+ *   would be a button that resolves to nothing.
+ */
+
+import { describe, expect, test, beforeEach } from 'bun:test';
+import { primeKabmoSettings, readKabmoSetting } from '@/shared/lib/settings/client';
+import {
+  LEFT_DOCK_SETTING_KEY,
+  SESSIONS_VIEW_ID,
+  isLeftDockPanelId,
+  leftPanelIds,
+  panelSideOf,
+  readLeftDock,
+  ridesSides,
+  setPanelSide,
+  writeLeftDock,
+} from '@/shared/lib/workspace/left-dock';
+import {
+  LEFT_DOCK_WIDTHS_SETTING_KEY,
+  MIN_LEFT_DOCK_PLUGIN_WIDTH,
+  resolveLeftDockWidth,
+  saveLeftDockWidth,
+} from '@/shared/lib/workspace/left-dock-width';
+import { MAX_LEFT_PANEL_WIDTH, MIN_LEFT_PANEL_WIDTH } from '@/shared/lib/workspace/sidebar-width';
+
+beforeEach(() => primeKabmoSettings({}));
+
+describe('readLeftDock', () => {
+  test('nothing stored means OFF with no placed panels', () => {
+    expect(readLeftDock()).toEqual({ enabled: false, panels: [] });
+  });
+
+  test('a malformed row is filtered rather than keyed', () => {
+    primeKabmoSettings({
+      [LEFT_DOCK_SETTING_KEY]: { enabled: true, panels: ['plugin:a:rightPanel', 3, '', null, 'plugin:a:rightPanel', 'git', 'plugin:b:rightPanel'] },
+    });
+    // Built-in ids and duplicates are dropped: a bare `git` names a view whose
+    // floor and width slot were declared for the RIGHT column.
+    expect(readLeftDock()).toEqual({
+      enabled: true,
+      panels: ['plugin:a:rightPanel', 'plugin:b:rightPanel'],
+    });
+  });
+
+  test('the sessions view is never a placed panel', () => {
+    primeKabmoSettings({ [LEFT_DOCK_SETTING_KEY]: { enabled: true, panels: [SESSIONS_VIEW_ID] } });
+    expect(readLeftDock().panels).toEqual([]);
+  });
+
+  test('a non-object row reads as OFF', () => {
+    primeKabmoSettings({ [LEFT_DOCK_SETTING_KEY]: 'yes' });
+    expect(readLeftDock()).toEqual({ enabled: false, panels: [] });
+  });
+});
+
+describe('writeLeftDock / setPanelSide', () => {
+  test('the switch and the placement are independent halves', () => {
+    writeLeftDock({ enabled: true });
+    expect(readLeftDock()).toEqual({ enabled: true, panels: [] });
+    setPanelSide('plugin:a:rightPanel', 'left');
+    expect(readLeftDock()).toEqual({ enabled: true, panels: ['plugin:a:rightPanel'] });
+  });
+
+  test('placing twice is idempotent, and moving back removes it', () => {
+    setPanelSide('plugin:a:rightPanel', 'left');
+    setPanelSide('plugin:a:rightPanel', 'left');
+    expect(readLeftDock().panels).toEqual(['plugin:a:rightPanel']);
+    setPanelSide('plugin:a:rightPanel', 'right');
+    expect(readLeftDock().panels).toEqual([]);
+  });
+
+  test('a built-in id and the sessions view are refused', () => {
+    setPanelSide('git', 'left');
+    setPanelSide(SESSIONS_VIEW_ID, 'left');
+    expect(readLeftDock().panels).toEqual([]);
+  });
+});
+
+describe('placing a panel turns the rail on', () => {
+  test('a placement with the rail off enables it in the same state', () => {
+    // The rail exists to reach the panels on it: a successful placement with
+    // the rail still off is a move with no button and no view, which reads as
+    // nothing having happened.
+    expect(readLeftDock().enabled).toBe(false);
+    setPanelSide('plugin:a:rightPanel', 'left');
+    expect(readLeftDock()).toEqual({ enabled: true, panels: ['plugin:a:rightPanel'] });
+  });
+
+  test('moving a panel back to the right leaves the rail as the user set it', () => {
+    // The switch is the user's, so only a PLACEMENT turns it on; a removal must
+    // not turn it off behind their back.
+    writeLeftDock({ enabled: true });
+    setPanelSide('plugin:a:rightPanel', 'left');
+    setPanelSide('plugin:a:rightPanel', 'right');
+    expect(readLeftDock()).toEqual({ enabled: true, panels: [] });
+  });
+
+  test('a placement made BY HAND on a disabled dock stays off until the UI places it', () => {
+    // `writeLeftDock` is the raw store; the coupling lives at the placement
+    // action, so a blob written directly is not silently rewritten.
+    writeLeftDock({ enabled: false, panels: ['plugin:a:rightPanel'] });
+    expect(readLeftDock()).toEqual({ enabled: false, panels: ['plugin:a:rightPanel'] });
+  });
+});
+
+describe('panelSideOf / leftPanelIds', () => {
+  test('the sessions view is left; a placed plugin is left; everything else right', () => {
+    setPanelSide('plugin:a:rightPanel', 'left');
+    expect(panelSideOf(SESSIONS_VIEW_ID)).toBe('left');
+    expect(panelSideOf('plugin:a:rightPanel')).toBe('left');
+    expect(panelSideOf('plugin:b:rightPanel')).toBe('right');
+    expect(panelSideOf('git')).toBe('right');
+  });
+
+  test('the bar order is the sessions view then the placed panels', () => {
+    setPanelSide('plugin:b:rightPanel', 'left');
+    setPanelSide('plugin:a:rightPanel', 'left');
+    expect(leftPanelIds()).toEqual([SESSIONS_VIEW_ID, 'plugin:b:rightPanel', 'plugin:a:rightPanel']);
+  });
+});
+
+describe('slot rules', () => {
+  test('a view rides the rails; a takeover rides the editor column', () => {
+    // The rule is the SLOT's shape, not the plugin's identity: a `rightPanel` is
+    // an activity-bar view, a `panel` takes the editor column over whole.
+    expect(ridesSides('rightPanel')).toEqual(['left', 'right']);
+    expect(ridesSides('panel')).toEqual(['editor']);
+  });
+
+  test('a takeover cannot be placed on a rail', () => {
+    // A button on a rail that opens a column somewhere else is a control that
+    // lies about where it goes.
+    setPanelSide('plugin:x:panel', 'left');
+    expect(readLeftDock().panels).toEqual([]);
+  });
+
+  test('a view cannot be placed in the editor column', () => {
+    setPanelSide('plugin:x:rightPanel', 'editor');
+    // Refused, and the refusal leaves the panel where it was: the right column.
+    expect(panelSideOf('plugin:x:rightPanel')).toBe('right');
+  });
+
+  test('a takeover is in the editor column by default', () => {
+    expect(panelSideOf('plugin:x:panel')).toBe('editor');
+  });
+
+  test('two panels of one plugin are placed independently', () => {
+    // The whole reason placement is per PANEL: moving the right panel onto the
+    // left dock must not drag the plugin's editor takeover with it.
+    setPanelSide('plugin:session-info:rightPanel', 'left');
+    expect(panelSideOf('plugin:session-info:rightPanel')).toBe('left');
+    expect(panelSideOf('plugin:session-info:panel')).toBe('editor');
+  });
+});
+
+describe('isLeftDockPanelId', () => {
+  test('accepts the sessions view and a plugin key only', () => {
+    expect(isLeftDockPanelId(SESSIONS_VIEW_ID)).toBe(true);
+    expect(isLeftDockPanelId('plugin:a:rightPanel')).toBe(true);
+    expect(isLeftDockPanelId('files')).toBe(false);
+    expect(isLeftDockPanelId('plugin:')).toBe(false);
+  });
+});
+
+describe('left dock widths', () => {
+  test('a remembered width wins and is clamped to the view floor', () => {
+    saveLeftDockWidth('plugin:a:rightPanel', 400);
+    expect(resolveLeftDockWidth('plugin:a:rightPanel')).toBe(400);
+    saveLeftDockWidth('plugin:a:rightPanel', 10);
+    expect(resolveLeftDockWidth('plugin:a:rightPanel')).toBe(MIN_LEFT_DOCK_PLUGIN_WIDTH);
+    saveLeftDockWidth('plugin:a:rightPanel', 10_000);
+    expect(resolveLeftDockWidth('plugin:a:rightPanel')).toBe(MAX_LEFT_PANEL_WIDTH);
+  });
+
+  test('the session list keeps its own floor, and the setting it already had', () => {
+    primeKabmoSettings({ omp_sidebar_width: 333 });
+    expect(resolveLeftDockWidth(SESSIONS_VIEW_ID)).toBe(333);
+    saveLeftDockWidth(SESSIONS_VIEW_ID, 10);
+    expect(resolveLeftDockWidth(SESSIONS_VIEW_ID)).toBe(MIN_LEFT_PANEL_WIDTH);
+    // The dock's map is its own key: a plugin's width never rewrites the list's.
+    saveLeftDockWidth('plugin:a:rightPanel', 500);
+    expect(resolveLeftDockWidth(SESSIONS_VIEW_ID)).toBe(MIN_LEFT_PANEL_WIDTH);
+    expect((readKabmoSetting<Record<string, number>>(LEFT_DOCK_WIDTHS_SETTING_KEY) ?? {})['plugin:a:rightPanel']).toBe(500);
+  });
+});