ompchamber 3.5.0 → 3.6.0

package/src/server/routes/settings/skills.ts

@@ -5,171 +5,223 @@ import { getDb } from '@/server/db.server';
 import { DEFAULT_CATALOG_SKILLS, DEFAULT_CATALOG_SOURCES, DEFAULT_SKILLS } from '@/client/data/settings/skill';
 import { isMockMode } from '@/server/mock.server';
 import type { SkillItem } from '@/shared/types';
-import { createSettingsListStore, readSettingsJson, writeSettingsJson } from '@/server/lib/db/settings-store';
-import { discoverNativeSkills, setSkillModelInvocation, type DiscoveredSkill } from '@/server/lib/omp/config/skills';
-import { installCatalogSkill, searchSkillCatalog, toCatalogSkills } from '@/server/lib/omp/config/skills-catalog';
+import { readSettingsJson, writeSettingsJson } from '@/server/lib/db/settings-store';
+import {
+  deleteSkillDir,
+  discoverSkills,
+  readSkillFile,
+  setSkillModelInvocation,
+  writeSkillFile,
+  type DiscoveredSkill,
+} from '@/server/lib/omp/config/skills';
+import {
+  installCatalogSkill,
+  searchSkillCatalog,
+  toCatalogSkills,
+  uninstallCatalogSkill,
+} from '@/server/lib/omp/config/skills-catalog';
+import { resolveDiscoveryScope, type DiscoveryScope } from '@/server/lib/omp/config/scope';
+import { reloadLiveSessions } from '@/server/lib/omp/session/reload.server';
 
-const SKILLS_KEY = 'omp_skills';
 const SOURCES_KEY = 'omp_catalog_sources';
 
-const skillsStore = createSettingsListStore<SkillItem>({
-  key: SKILLS_KEY,
-  mockDefaults: DEFAULT_SKILLS,
-  idOf: (skill) => skill.id,
-  singular: 'skill',
-  plural: 'skills',
-});
+/** Human label for an omp discovery source. */
+const SOURCE_LABELS: Record<string, string> = {
+  'native:user': 'User / omp agent',
+  'native:project': 'Project / .omp/skills',
+  'agents:user': 'User / .agents',
+  'agents:project': 'Project / .agents',
+  'claude:user': 'User / .claude',
+  'claude:project': 'Project / .claude',
+  'codex:user': 'User / .codex',
+  'codex:project': 'Project / .codex',
+  'github:project': 'Project / .github/skills',
+  'opencode:user': 'User / opencode',
+  'opencode:project': 'Project / .opencode',
+};
 
 /**
- * Convert a natively discovered SKILL.md into the chamber SkillItem shape.
- * location/locationLabel reflect the real disk root the skill came from.
+ * Convert a discovered skill into the chamber's SkillItem. A chamber-managed
+ * skill carries its SKILL.md body so the pane can edit it; a read-only one
+ * carries its file path, because the pane must not offer a save that would
+ * rewrite another tool's file.
  */
-function nativeToSkillItem(skill: DiscoveredSkill): SkillItem {
+async function toSkillItem(skill: DiscoveredSkill): Promise<SkillItem> {
+  const locationLabel = SOURCE_LABELS[skill.source] ?? skill.source;
+  let instructions = skill.filePath;
+  if (skill.managed) {
+    const file = await readSkillFile(skill.filePath);
+    if (file) instructions = file.body;
+  }
   return {
     id: skill.id,
     name: skill.name,
     description: skill.description,
     location: skill.sourceRoot,
-    locationLabel: skill.sourceRoot === 'user' ? 'User / OMP agent' : 'Project / .omp/skills',
-    instructions: skill.filePath,
+    locationLabel,
+    instructions,
     project: 'omp',
+    filePath: skill.filePath,
+    source: skill.source,
+    managed: skill.managed,
+    hidden: skill.hidden,
   };
 }
 
-/** Merge native omp skills (disk scan) with app-local custom skills. */
-async function mergeSkills(custom: SkillItem[]): Promise<SkillItem[]> {
-  const native = (await discoverNativeSkills()).map(nativeToSkillItem);
-  const nativeNames = new Set(native.map((s) => s.name.toLowerCase()));
-  return [...native, ...custom.filter((s) => !nativeNames.has(s.name.toLowerCase()))];
+/** Every skill an omp session in this scope loads, newest state included. */
+async function listSkills(scope: DiscoveryScope): Promise<SkillItem[]> {
+  const discovered = await discoverSkills(scope.cwd, scope.workspace);
+  return Promise.all(discovered.map((skill) => toSkillItem(skill)));
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
 }
 
 export async function loader({ request }: LoaderFunctionArgs) {
+  const mock = isMockMode();
   try {
+    if (mock) {
+      const db = await getDb();
+      const storedSources = await readSettingsJson<typeof DEFAULT_CATALOG_SOURCES>(db, SOURCES_KEY, DEFAULT_CATALOG_SOURCES);
+      return json({
+        skills: DEFAULT_SKILLS,
+        catalogSources: Array.isArray(storedSources) && storedSources.length > 0 ? storedSources : DEFAULT_CATALOG_SOURCES,
+        catalogSkills: DEFAULT_CATALOG_SKILLS,
+        root: null,
+        isMock: true,
+      });
+    }
+
     const db = await getDb();
     const url = new URL(request.url);
-    const includeNative = url.searchParams.get('native') === '1' || !isMockMode();
-    const mock = isMockMode();
+    const scope = await resolveDiscoveryScope(url.searchParams.get('root'), url.searchParams.get('scope'));
 
-    const skills = await skillsStore.read(db);
     const storedSources = await readSettingsJson<typeof DEFAULT_CATALOG_SOURCES>(db, SOURCES_KEY, DEFAULT_CATALOG_SOURCES);
     const catalogSources = Array.isArray(storedSources) && storedSources.length > 0 ? storedSources : DEFAULT_CATALOG_SOURCES;
 
-    const mergedSkills = includeNative && !mock ? await mergeSkills(skills) : skills;
-
-    let catalogSkills = DEFAULT_CATALOG_SKILLS;
-    if (!mock) {
-      const [popular, curated] = await Promise.all([
-        searchSkillCatalog('popular', 18),
-        searchSkillCatalog('code review', 8),
-      ]);
-      const seen = new Set<string>();
-      catalogSkills = toCatalogSkills([...popular, ...curated], catalogSources[0]?.id ?? 'skills-sh')
-        .filter((item) => (seen.has(item.repoTag) ? false : (seen.add(item.repoTag), true)));
-    }
+    const [skills, popular, curated] = await Promise.all([
+      listSkills(scope),
+      searchSkillCatalog('popular', 18),
+      searchSkillCatalog('code review', 8),
+    ]);
 
+    const seen = new Set<string>();
+    const catalogSkills = toCatalogSkills([...popular, ...curated], catalogSources[0]?.id ?? 'skills-sh')
+      .filter((item) => (seen.has(item.repoTag) ? false : (seen.add(item.repoTag), true)));
+
+    return json({ skills, catalogSources, catalogSkills, root: scope.workspace, isMock: false });
+  } catch (error) {
     return json({
-      skills: mergedSkills,
-      catalogSources,
-      catalogSkills,
-      isMock: mock,
-    });
-  } catch (error: any) {
-    const mock = isMockMode();
-    return json({
-      error: error.message,
-      skills: mock ? DEFAULT_SKILLS : [],
+      error: errorMessage(error),
+      skills: [],
       catalogSources: DEFAULT_CATALOG_SOURCES,
       catalogSkills: DEFAULT_CATALOG_SKILLS,
+      root: null,
       isMock: mock,
     }, { status: 500 });
   }
 }
 
 export async function action({ request, params }: ActionFunctionArgs) {
+  const mock = isMockMode();
   try {
     const db = await getDb();
+    const url = new URL(request.url);
 
     if (request.method === 'DELETE') {
-      const url = new URL(request.url);
+      const scope = await resolveDiscoveryScope(url.searchParams.get('root'), url.searchParams.get('scope'));
       const id = url.searchParams.get('id');
       if (!id) return json({ error: 'id is required' }, { status: 400 });
-      if (id.startsWith('omp-')) {
-        return json({ error: 'Native omp skills are managed on disk' }, { status: 403 });
-      }
+      if (mock) return json({ success: true, skills: DEFAULT_SKILLS });
 
-      const list = await skillsStore.remove(db, id);
-      return json({ success: true, skills: list });
+      const removed = await deleteSkillDir(id, scope.workspace);
+      if (!removed) return json({ error: 'Skill not found' }, { status: 404 });
+      await reloadLiveSessions();
+      return json({ success: true, skills: await listSkills(scope) });
     }
 
-    if (request.method === 'POST' || request.method === 'PUT') {
-      const body = await request.json();
-
-      // Toggle model invocation on a native skill file (frontmatter edit).
-      if (body.type === 'toggle_model_invocation' && typeof body.skillId === 'string' && body.skillId.startsWith('omp-')) {
-        const [root, sourceRoot, ...nameParts] = body.skillId.split('-');
-        void root;
-        const skill = (await discoverNativeSkills()).find(
-          (s) => s.name === nameParts.join('-') && s.sourceRoot === sourceRoot,
-        );
-        if (!skill) return json({ error: 'Skill not found' }, { status: 404 });
-        const changed = await setSkillModelInvocation(skill.filePath, body.disable === true);
-        return json({ success: changed, disable: body.disable === true });
-      }
+    if (request.method !== 'POST' && request.method !== 'PUT') {
+      return methodNotAllowed({ request, params });
+    }
 
-      if (body.type === 'add_source') {
-        const sources = await readSettingsJson<typeof DEFAULT_CATALOG_SOURCES>(db, SOURCES_KEY, DEFAULT_CATALOG_SOURCES);
-        const updated = [...sources, body.source];
-        await writeSettingsJson(db, SOURCES_KEY, updated);
-        return json({ success: true, catalogSources: updated });
-      }
+    const body = await request.json();
+    // The root may ride on the query (a plain GET-shaped read) or in the body
+    // (a POST that carries the draft), so a write is scoped either way.
+    const scope = await resolveDiscoveryScope(
+      url.searchParams.get('root') ?? (typeof body.root === 'string' ? body.root : null),
+      url.searchParams.get('scope') ?? (typeof body.scope === 'string' ? body.scope : null),
+    );
+
+    // Toggle model invocation: the skill stays runnable, it just drops out of
+    // the model's skill listing.
+    if (body.type === 'toggle_model_invocation') {
+      if (mock) return json({ success: false });
+      const target = (await discoverSkills(scope.cwd, scope.workspace)).find((skill) => skill.id === body.skillId);
+      if (!target) return json({ error: 'Skill not found' }, { status: 404 });
+      const changed = await setSkillModelInvocation(target.filePath, body.disable === true);
+      if (changed) await reloadLiveSessions();
+      return json({ success: changed, skills: await listSkills(scope) });
+    }
 
-      if (body.type === 'install_toggle') {
-        const { skill, install } = body;
-        let skills = await skillsStore.read(db);
-
-        if (install) {
-          // Catalog skill with a package tag installs via the real skills.sh CLI.
-          if (typeof skill.repoTag === 'string' && /^[\w.\-]+\/[\w.\-@:]+$/.test(skill.repoTag)) {
-            await installCatalogSkill(skill.repoTag);
-          }
-          if (!skills.some(s => s.name === skill.name)) {
-            skills.push({
-              id: `skill-${Date.now()}`,
-              name: skill.name,
-              description: skill.description,
-              location: 'user',
-              locationLabel: 'User / OMP agent',
-              instructions: skill.instructions || `Autonomous guidelines for ${skill.name}. Adhere strictly to skill instructions.`,
-              project: 'omp',
-              isInstalledFromCatalog: true,
-              catalogSource: skill.catalogSource ?? skill.sourceId,
-            });
-          }
-        } else {
-          skills = skills.filter(s => s.name !== skill.name);
-        }
+    if (body.type === 'reload') {
+      if (mock) return json({ success: true, reloaded: [] });
+      const reloaded = await reloadLiveSessions();
+      return json({ success: true, reloaded });
+    }
 
-        await skillsStore.write(db, skills);
-        return json({ success: true, skills: isMockMode() ? skills : await mergeSkills(skills) });
-      }
+    if (body.type === 'add_source') {
+      const sources = await readSettingsJson<typeof DEFAULT_CATALOG_SOURCES>(db, SOURCES_KEY, DEFAULT_CATALOG_SOURCES);
+      const updated = [...sources, body.source];
+      await writeSettingsJson(db, SOURCES_KEY, updated);
+      return json({ success: true, catalogSources: updated });
+    }
+
+    // Catalog install/uninstall goes through the real skills CLI, which is what
+    // actually puts the skill where omp reads it.
+    if (body.type === 'install_toggle') {
+      const { skill, install } = body;
+      if (mock) return json({ success: true, skills: DEFAULT_SKILLS });
 
-      // Catalog skill POST installs via the skills.sh CLI: the component
-      // echoes the package back in instructions (and may include repoTag).
-      if (body.skill) {
-        const pkg = typeof body.skill.repoTag === 'string' && /^[\w.\-]+\/[\w.\-@:]+$/.test(body.skill.repoTag)
-          ? body.skill.repoTag
-          : (typeof body.skill.instructions === 'string' && /^[\w.\-]+\/[\w.\-@:]+$/.test(body.skill.instructions) ? body.skill.instructions : null);
-        if (!isMockMode() && pkg) await installCatalogSkill(pkg);
+      if (install) {
+        if (typeof skill.repoTag === 'string' && /^[\w.\-]+\/[\w.\-@:]+$/.test(skill.repoTag)) {
+          await installCatalogSkill(skill.repoTag, typeof skill.name === 'string' ? skill.name : null);
+        }
+      } else if (typeof skill.name === 'string' && skill.name.trim()) {
+        await uninstallCatalogSkill(skill.name.trim());
       }
+      await reloadLiveSessions();
+      return json({ success: true, skills: await listSkills(scope) });
+    }
 
-      const updatedSkills = await skillsStore.upsert(db, body);
-      await skillsStore.write(db, updatedSkills);
+    // Create or update a chamber-managed SKILL.md.
+    if (body.skill) {
+      if (mock) return json({ success: true, skills: DEFAULT_SKILLS });
+
+      const draft = body.skill as Partial<SkillItem>;
+      const target = draft.location === 'project' ? 'project' : 'user';
+      const existing = typeof draft.id === 'string'
+        ? (await discoverSkills(scope.cwd, scope.workspace)).find((skill) => skill.id === draft.id)
+        : undefined;
+      if (existing && !existing.managed) {
+        return json({ error: `"${existing.name}" is managed by ${existing.source} and cannot be edited here` }, { status: 403 });
+      }
 
-      return json({ success: true, skills: isMockMode() ? updatedSkills : mergeSkills(updatedSkills) });
+      await writeSkillFile({
+        scope: target,
+        projectDir: scope.workspace,
+        previousDir: existing?.baseDir ?? null,
+        name: draft.name ?? '',
+        description: draft.description ?? '',
+        hidden: draft.hidden === true,
+        body: typeof draft.instructions === 'string' ? draft.instructions : '',
+      });
+      await reloadLiveSessions();
+      return json({ success: true, skills: await listSkills(scope) });
     }
 
-    return methodNotAllowed({ request, params });
-  } catch (error: any) {
-    return json({ error: error.message }, { status: 500 });
+    return json({ error: 'Unsupported skill action' }, { status: 400 });
+  } catch (error) {
+    return json({ error: errorMessage(error) }, { status: 500 });
   }
 }

package/src/server/routes/terminal/sessions.ts

@@ -14,7 +14,7 @@
  */
 
 import { json, type LoaderFunctionArgs } from '@/server/lib/remix-compat';
-import { listTerminals } from '@/server/lib/terminal/runtime.server';
+import { listTerminals } from '@/server/lib/terminal/liveness.server';
 
 export async function loader({ request }: LoaderFunctionArgs) {
   const url = new URL(request.url);

package/src/server/routes/updates/apply.ts

@@ -1,25 +1,112 @@
-import { json } from '@/server/lib/remix-compat';
-import type { ActionFunctionArgs } from '@/server/lib/remix-compat';
+import { json, type ActionFunctionArgs } from '@/server/lib/remix-compat';
 import { methodNotAllowed } from '@/server/lib/route-adapter';
+import { scheduleSelfRestart } from '@/server/lib/lifecycle/restart';
+import { createSseStream } from '@/server/lib/sse';
 import { applyUpdate } from '@/server/lib/updates/apply';
+import { runningUpdate, updateBusyMessage } from '@/server/lib/updates/single-flight';
+
+/** Longest a buffered output chunk waits before it is flushed anyway. */
+const FLUSH_DELAY_MS = 50;
 
 /**
  * POST /api/updates/apply — body `{ target: 'omp' | 'ompchamber' }`.
- * Unknown targets are a 400; unexpected failures are a 500.
+ *
+ * Answers with an SSE stream rather than one JSON body: the update runs for
+ * minutes and prints as it goes, and a buffered response showed the user a
+ * spinner and nothing else until it finished. Frames:
+ *
+ *   `line`   — raw command output
+ *   `stage`  — a step heading
+ *   `result` — the UpdateApplyResult, last before the stream closes
+ *
+ * A non-SSE answer is still possible and still meaningful: an unknown target or
+ * a malformed body is a plain JSON error with its own status, because there is
+ * no run to report on.
  */
 export async function action({ request, params }: ActionFunctionArgs) {
-  if (request.method !== 'POST') {
-    return methodNotAllowed({ request, params });
-  }
+  if (request.method !== 'POST') return methodNotAllowed({ request, params });
+
+  let target: unknown;
   try {
-    const body = (await request.json()) as { target?: unknown };
-    const target = body.target;
-    if (target === 'omp' || target === 'ompchamber') {
-      return json(await applyUpdate(target));
-    }
+    target = ((await request.json()) as { target?: unknown }).target;
+  } catch {
+    return json({ error: 'Request body is not valid JSON' }, { status: 400 });
+  }
+  if (target !== 'omp' && target !== 'ompchamber') {
     return json({ error: 'Unknown update target' }, { status: 400 });
-  } catch (error) {
-    const message = error instanceof Error ? error.message : 'Failed to apply update';
-    return json({ error: message }, { status: 500 });
   }
+
+  // Checked before the stream exists, because after it starts the status is
+  // already 200 and a refusal could only be reported as a failure frame. The
+  // slot itself is taken inside `applyUpdate` — this is the clean answer for
+  // the ordinary case (a reload, a second tab), not the guard.
+  const running = runningUpdate();
+  if (running) return json({ error: updateBusyMessage(running) }, { status: 409 });
+
+  const stream = createSseStream({
+    heartbeatMs: 15_000,
+    signal: request.signal,
+    onStart: async (handlers) => {
+      // Output arrives in arbitrary chunks, so a small buffer collapses a burst
+      // of writes into one frame without splitting a line in half.
+      let pending = '';
+      let flushTimer: ReturnType<typeof setTimeout> | null = null;
+
+      const flush = () => {
+        if (flushTimer !== null) {
+          clearTimeout(flushTimer);
+          flushTimer = null;
+        }
+        if (!pending || handlers.isClosed()) return;
+        const chunk = pending;
+        pending = '';
+        handlers.send('line', chunk);
+      };
+
+      try {
+        const { result, updated } = await applyUpdate(target, {
+          onLine: (chunk) => {
+            if (handlers.isClosed()) return;
+            pending += chunk;
+            if (flushTimer === null) flushTimer = setTimeout(flush, FLUSH_DELAY_MS);
+          },
+          onStage: (label) => {
+            if (handlers.isClosed()) return;
+            flush();
+            handlers.send('stage', label);
+          },
+        });
+
+        flush();
+        // A run that replaced files leaves this process serving the build it
+        // just replaced. `scheduleSelfRestart` ARMS the detached restart on its
+        // own grace timer (`RESTART_GRACE_MS`) — long enough for the frames
+        // below to reach the browser — and it is the only place that knows
+        // whether this instance is one the CLI can restart at all. Its plan is
+        // folded into the message before the result is sent: "updated" over a
+        // server still on the old build would mislead.
+        if (target === 'ompchamber' && result.success && updated) {
+          const plan = scheduleSelfRestart();
+          result.message = `${result.message} ${plan.message}`;
+        }
+        handlers.send('result', result);
+      } catch (err) {
+        flush();
+        handlers.send('result', {
+          success: false,
+          target,
+          manual: false,
+          message: err instanceof Error ? err.message : 'Failed to apply the update',
+        });
+      }
+
+      if (flushTimer !== null) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+      }
+      handlers.close();
+    },
+  });
+
+  return stream.response;
 }

package/src/shared/lib/chat/composer/client.ts

@@ -3,9 +3,9 @@ import { CHAMBER_COMMANDS } from '@/shared/lib/chat/composer/trigger';
 
 const CACHE_TTL_MS = 300_000;
 
-/** Cache keys: `'agent'`, `'command'`, and `'file::<root>'` per workspace root. */
+/** Cache keys: `'agent'`, `'command::<root>'`, and `'file::<root>'` per workspace root. */
 const AGENTS_KEY = 'agent';
-const COMMANDS_KEY = 'command';
+const commandKey = (root: string): string => `command::${root}`;
 const fileKey = (root: string): string => `file::${root}`;
 
 interface CacheEntry {
@@ -161,34 +161,37 @@ async function loadFileItems(root: string | null): Promise<ComposerPickItem[]> {
 }
 
 /** Load command + skill items, deduping concurrent callers and caching 5 minutes. */
-async function loadCommandItems(): Promise<ComposerPickItem[]> {
-  const cached = cache.get(COMMANDS_KEY);
+async function loadCommandItems(root: string | null): Promise<ComposerPickItem[]> {
+  const key = commandKey(root ?? '');
+  const cached = cache.get(key);
   if (cached && cached.expiresAt > Date.now()) return cached.data;
 
-  const existing = inFlight.get(COMMANDS_KEY);
+  const existing = inFlight.get(key);
   if (existing) return existing;
 
   const pending = (async () => {
     try {
+      const query = root ? `?root=${encodeURIComponent(root)}` : '';
       const [commands, skills] = await Promise.all([
-        fetchJson<{ commands: CommandItem[] }>('/api/settings/commands'),
-        fetchJson<{ skills: SkillItem[] }>('/api/settings/skills'),
+        fetchJson<{ commands: CommandItem[] }>(`/api/settings/commands${query}`),
+        fetchJson<{ skills: SkillItem[] }>(`/api/settings/skills${query}`),
       ]);
       const items = mergeCommandAndSkillItems(commands.commands, skills.skills);
-      cache.set(COMMANDS_KEY, { data: items, expiresAt: Date.now() + CACHE_TTL_MS });
+      cache.set(key, { data: items, expiresAt: Date.now() + CACHE_TTL_MS });
       return items;
     } finally {
-      inFlight.delete(COMMANDS_KEY);
+      inFlight.delete(key);
     }
   })();
 
-  inFlight.set(COMMANDS_KEY, pending);
+  inFlight.set(key, pending);
   return pending;
 }
 
 /**
  * Load pick items for a trigger kind. `mention` merges agents (first) and
- * workspace files; `command` merges commands and skills.
+ * workspace files; `command` merges commands and skills, both scoped to `root`
+ * so a workspace's own `.omp/commands` and `.omp/skills` are offered.
  */
 export function loadComposerItems(
   kind: ComposerPickKind,
@@ -199,7 +202,7 @@ export function loadComposerItems(
       ([agents, files]) => [...agents, ...files],
     );
   }
-  return loadCommandItems();
+  return loadCommandItems(root ?? null);
 }
 
 /** Load agent names via the shared agent cache. Never throws. */
@@ -212,13 +215,19 @@ export async function loadAgentNames(): Promise<string[]> {
   }
 }
 
-/** Clear the cache (and in-flight dedupe) for one key or all keys. */
+/** Clear the cache (and in-flight dedupe) for one key or all keys. A key with
+ *  per-root variants (`command::<root>`) is matched by its prefix, so a caller
+ *  that names the logical kind clears every workspace's copy. */
 export function invalidateComposerCache(key?: string): void {
-  if (key) {
-    cache.delete(key);
-    inFlight.delete(key);
+  if (!key) {
+    cache.clear();
+    inFlight.clear();
     return;
   }
-  cache.clear();
-  inFlight.clear();
+  for (const cacheKey of [...cache.keys()]) {
+    if (cacheKey === key || cacheKey.startsWith(`${key}::`)) cache.delete(cacheKey);
+  }
+  for (const inFlightKey of [...inFlight.keys()]) {
+    if (inFlightKey === key || inFlightKey.startsWith(`${key}::`)) inFlight.delete(inFlightKey);
+  }
 }

package/src/shared/lib/chat/composer/scope.test.ts

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The composer's command pool is WORKSPACE-scoped: omp resolves project
+ * commands and project skills from the process's cwd, so a request that omits
+ * the root answers with `$HOME`'s inventory and the popup silently misses the
+ * workspace's own `.omp/commands` and `.omp/skills` (measured: 7 skill entries
+ * for $HOME against 9 for this repository). The cache is keyed per root for the
+ * same reason — one shared `command` key served the previous workspace's list
+ * after a switch.
+ */
+
+import { describe, expect, test, beforeEach } from 'bun:test';
+
+import { invalidateComposerCache, loadComposerItems } from '@/shared/lib/chat/composer/client';
+
+const realFetch = globalThis.fetch;
+let requested: string[] = [];
+
+function stubFetch(): void {
+  requested = [];
+  globalThis.fetch = (async (input: RequestInfo | URL) => {
+    const url = typeof input === 'string' ? input : input.toString();
+    requested.push(url);
+    const body = url.includes('/commands') ? { commands: [] } : { skills: [] };
+    return new Response(JSON.stringify(body), { status: 200, headers: { 'content-type': 'application/json' } });
+  }) as typeof fetch;
+}
+
+beforeEach(() => {
+  invalidateComposerCache();
+  stubFetch();
+});
+
+describe('loadComposerItems workspace scope', () => {
+  test('scopes both command sources to the given root', async () => {
+    await loadComposerItems('command', '/ws/one');
+
+    expect(requested.some((url) => url === '/api/settings/commands?root=%2Fws%2Fone')).toBe(true);
+    expect(requested.some((url) => url === '/api/settings/skills?root=%2Fws%2Fone')).toBe(true);
+  });
+
+  test('omits the query when no root is known', async () => {
+    await loadComposerItems('command', null);
+
+    expect(requested).toContain('/api/settings/commands');
+    expect(requested).toContain('/api/settings/skills');
+    expect(requested.every((url) => !url.includes('root='))).toBe(true);
+  });
+
+  test('does not serve one workspace from another workspace cache entry', async () => {
+    await loadComposerItems('command', '/ws/one');
+    const afterFirst = requested.length;
+
+    await loadComposerItems('command', '/ws/two');
+
+    expect(requested.length).toBeGreaterThan(afterFirst);
+    expect(requested.some((url) => url === '/api/settings/commands?root=%2Fws%2Ftwo')).toBe(true);
+  });
+
+  test('a repeated read is served from the cache', async () => {
+    await loadComposerItems('command', '/ws/one');
+    const afterFirst = requested.length;
+
+    await loadComposerItems('command', '/ws/one');
+
+    expect(requested.length).toBe(afterFirst);
+  });
+
+  test('invalidating the logical kind clears every workspace entry', async () => {
+    await loadComposerItems('command', '/ws/one');
+    await loadComposerItems('command', '/ws/two');
+    const afterBoth = requested.length;
+
+    invalidateComposerCache('command');
+    await loadComposerItems('command', '/ws/one');
+    await loadComposerItems('command', '/ws/two');
+
+    expect(requested.length).toBeGreaterThan(afterBoth);
+  });
+});
+
+// Restore the real fetch so a later test file in the same process is unaffected.
+process.once('exit', () => {
+  globalThis.fetch = realFetch;
+});