total-recall-brain 3.45.0 → 3.46.1

package/src/server/routes/brains.mjs

@@ -12,14 +12,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { requireAuth, requireScope } from '../auth.mjs';
+import { dashboardBrainDir, readRegisteredProjects } from '../../core/brain-registry.mjs';
 import { getNodes } from '../../core/vault-cache.mjs';
 import { logger } from '../../core/logger.mjs';
-import {
-  BRAIN_DIR,
-  VAULT_DIR,
-  DERIVED_DIR,
-  serverError,
-} from './_shared.mjs';
+import { serverError } from './_shared.mjs';
 
 const router = Router();
 
@@ -49,8 +45,9 @@ function countMd(dir) {
  * List all known brains (global + registered projects + optional tenant) with state metadata.
  */
 router.get('/api/brains', requireAuth, requireScope('ssss:read'), async (req, res) => {
+  res.set('Cache-Control', 'private, no-store');
   try {
-    const globalBrainDir = path.join(os.homedir(), '.agent', 'skills', 'total-recall');
+    const globalBrainDir = dashboardBrainDir();
     const brains = [];
 
     // Global brain
@@ -75,35 +72,27 @@ router.get('/api/brains', requireAuth, requireScope('ssss:read'), async (req, re
     });
 
     // Project brains from registry
-    const registryPath = path.join(globalBrainDir, 'config', 'project-registry.json');
-    if (fs.existsSync(registryPath)) {
-      try {
-        const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
-        for (const project of registry) {
-          const projectVaultDir = path.join(project.brainDir, 'memory-vault');
-          let nodeCount = 0;
-          const exists = fs.existsSync(project.path);
-          if (!exists) continue; // Hide non-existent projects automatically
-
-          if (fs.existsSync(projectVaultDir)) {
-            nodeCount = countMd(projectVaultDir);
-          }
-
-          brains.push({
-            id: `project:${project.name}`,
-            name: project.name,
-            layer: 'project',
-            path: project.brainDir,
-            project_root: project.path,
-            exists: true,
-            node_count: nodeCount,
-            registered_at: project.registered_at,
-            last_compiled: project.last_compiled || getLastModified(path.join(project.brainDir, 'memory-derived', 'graph-index.jsonl')),
-          });
-        }
-      } catch (err) {
-        logger.error('server', 'Failed to read project registry', { error: err.message });
+    try {
+      const registry = readRegisteredProjects(globalBrainDir);
+      for (const project of registry) {
+        if (!project.name || !project.path || !project.brainDir || !fs.existsSync(project.path)) continue;
+        const duplicateName = registry.some(other => other !== project && other.name === project.name);
+        if (duplicateName && !project.project_id) continue;
+        brains.push({
+          id: `project:${duplicateName ? project.project_id : project.name}`,
+          name: project.name,
+          layer: 'project',
+          path: project.brainDir,
+          project_root: project.path,
+          exists: true,
+          node_count: countMd(path.join(project.brainDir, 'memory-vault')),
+          registered_at: project.registered_at,
+          last_compiled: project.last_compiled || getLastModified(path.join(project.brainDir, 'memory-derived', 'graph-index.jsonl')),
+        });
       }
+    } catch (err) {
+      logger.error('server', 'Failed to read project registry', { error: err.message });
+      return res.status(503).json({ error: 'Brain registry metadata is unavailable' });
     }
 
     // Optional remote/tenant vault from config
@@ -145,22 +134,18 @@ router.get('/api/brains', requireAuth, requireScope('ssss:read'), async (req, re
  * List all memory nodes for a specific brain.
  */
 router.get('/api/brains/:id/nodes', requireAuth, requireScope('ssss:read', 'memory:read'), async (req, res) => {
+  res.set('Cache-Control', 'private, no-store');
   try {
     const brainId = req.params.id;
     let vaultDir;
 
     if (brainId === 'global') {
-      const brainDir = path.join(os.homedir(), '.agent', 'skills', 'total-recall');
-      vaultDir = path.join(brainDir, 'memory-vault');
+      vaultDir = path.join(dashboardBrainDir(), 'memory-vault');
     } else if (brainId.startsWith('project:')) {
       const projectName = brainId.slice('project:'.length);
-      const globalBrainDir = path.join(os.homedir(), '.agent', 'skills', 'total-recall');
-      const registryPath = path.join(globalBrainDir, 'config', 'project-registry.json');
-      if (!fs.existsSync(registryPath)) {
-        return res.status(404).json({ error: 'Project registry not found' });
-      }
-      const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
-      const project = registry.find(p => p.name === projectName);
+      const registry = readRegisteredProjects(dashboardBrainDir());
+      const matching = registry.filter(p => p.name === projectName || p.project_id === projectName);
+      const project = matching.length === 1 ? matching[0] : null;
       if (!project) {
         return res.status(404).json({ error: `Project "${projectName}" not found in registry` });
       }

package/src/server/routes/dashboard.mjs

@@ -4,8 +4,10 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { requireAuth, requireScope } from '../auth.mjs';
 import { getNodes } from '../../core/vault-cache.mjs';
+import { DrawerInputError, readDrawerConfig, writeDrawerConfig } from '../../core/workspace-drawers.mjs';
 import {
   VAULT_DIR,
+  BRAIN_DIR,
   INSTRUCTIONS,
   ROOT as SHARED_ROOT,
   resolveVaultFromQuery,
@@ -17,6 +19,30 @@ const router = Router();
 // (breaks on Windows and on paths with encoded characters).
 const ROOT = process.env.TR_ROOT || SHARED_ROOT || path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
 
+router.get('/api/dashboard/drawers/:edge', requireAuth, requireScope('config:read'), (req, res) => {
+  res.set('Cache-Control', 'no-store');
+  try {
+    return res.json(readDrawerConfig(BRAIN_DIR, req.params.edge));
+  } catch (error) {
+    if (error instanceof DrawerInputError) return res.status(400).json({ error: error.message });
+    return res.status(500).json({ error: 'Could not read the saved drawer.' });
+  }
+});
+
+router.put('/api/dashboard/drawers/:edge', requireAuth, requireScope('config:write'), async (req, res) => {
+  res.set('Cache-Control', 'no-store');
+  if (!req.is('application/json')) return res.status(415).json({ error: 'Use JSON to save the drawer.' });
+  try {
+    return res.json(await writeDrawerConfig(BRAIN_DIR, req.params.edge, req.body?.config, req.body?.version));
+  } catch (error) {
+    if (error instanceof DrawerInputError) return res.status(400).json({ error: error.message });
+    if (error.message.startsWith('Plugin state version conflict')) {
+      return res.status(409).json({ error: 'The drawer changed elsewhere. Reload it before saving.' });
+    }
+    return res.status(500).json({ error: 'Could not save the drawer.' });
+  }
+});
+
 router.get('/api/dashboard/instructions', requireAuth, requireScope('instructions:read'), (req, res) => {
   const vaultDir = resolveVaultFromQuery(req);
   const paths = pathsForVault(vaultDir);

package/src/server/routes/plugins.mjs

@@ -3,7 +3,8 @@ import fs from "node:fs";
 import path from "node:path";
 import matter from "../../core/frontmatter.mjs";
 import { requireAuth, requireScope } from "../auth.mjs";
-import { getPluginById } from "../../core/plugin-loader.mjs";
+import { resolvePluginBrainTargets } from '../plugin-brain-targets.mjs';
+import { discoverPlugins, getPluginById } from "../../core/plugin-loader.mjs";
 import {
   listInstalledPlugins,
   listAvailableBundled,
@@ -18,20 +19,25 @@ import {
 import { listPeerPlugins } from "../../core/plugin-peers.mjs";
 import { runPluginCommand, validatePluginSecretInput } from "../../core/plugin-runner.mjs";
 import { readPluginRecord, patchPluginRecord, emit, vaultFor } from '../../core/plugin-store.mjs';
-import { setPluginActive } from '../../core/plugin-activation.mjs';
+import { activatePluginOnUse, setPluginActive } from '../../core/plugin-activation.mjs';
 import { pluginActivation } from '../../core/plugin-state.mjs';
+import { REQUIRED_INSTALLATION_PLUGIN_IDS } from '../../core/default-plugins.mjs';
 import { configurationValues } from '../../core/plugin-contracts/configuration.mjs';
 import { writeNodeValidatedAsync } from "../../core/validated-write.mjs";
 import { walkMd } from "../../core/vault.mjs";
 import { serverError, badRequest, VAULT_DIR, BRAIN_DIR, globalBrainDir, sanitizeNode } from "./_shared.mjs";
 
 const router = Router();
+let activationTail = Promise.resolve();
 
-// Plugins always resolve against the server's own project. Routes used to take
-// a caller-supplied `root`, which let a request point discovery — and the
-// runner — at any directory on disk.
+// Omitted selectors use the serving project. Explicit selectors resolve only
+// through registered brains, without accepting host paths from a request.
 const projectRoot = () => process.cwd();
 
+function surfaceTarget(req, id) {
+  return id === undefined ? { brainDir: BRAIN_DIR, projectRoot: projectRoot() } : resolvePluginBrainTargets([id], req.auth)[0];
+}
+
 router.get('/api/plugins/execution-targets', requireAuth, requireScope('config:read'), async (req, res) => {
   try {
     const { loadPluginModule } = await import('../../core/plugin-runtime.mjs');
@@ -43,19 +49,81 @@ router.get('/api/plugins/execution-targets', requireAuth, requireScope('config:r
 
 router.put('/api/plugins/:id/activation', requireAuth, requireScope('config:write'), async (req, res) => {
   try {
-    const result = await setPluginActive(req.params.id, req.body?.enabled, { projectRoot: projectRoot() });
-    res.status(result.compilation.ok ? 200 : 500).json({ success: result.compilation.ok, ...result });
-  } catch (err) { badRequest(res, err.message); }
+    const { enabled, brainIds, mode } = req.body || {};
+    if (req.query.brain !== undefined || req.body?.brainId !== undefined) {
+      return badRequest(res, 'Use the brainIds array to target plugin activation.');
+    }
+    if (mode === undefined && typeof enabled !== 'boolean') return badRequest(res, 'Plugin activation requires a boolean');
+    if (mode !== undefined && (enabled !== undefined || !['on-use', 'use'].includes(mode) ||
+        !Array.isArray(brainIds) || (mode === 'use' && brainIds.length !== 1))) {
+      return badRequest(res, 'On use requires project brain IDs. Opening a plugin requires one project brain ID.');
+    }
+    // Global changes rebuild project surfaces too, so serialize writes and rebuilds together.
+    const change = activationTail.then(async () => {
+      if (brainIds === undefined) {
+        const result = await setPluginActive(req.params.id, enabled, { projectRoot: projectRoot() });
+        const cleanup = reportedCleanup(result);
+        const success = result.compilation.ok && cleanup?.ok !== false;
+        return { status: success ? 200 : 500, body: { ...result, success, cleanup, ...(cleanup?.error ? { error: cleanup.error } : {}) } };
+      }
+      const targets = resolvePluginBrainTargets(brainIds, req.auth);
+      if (mode && targets.some(target => target.projectRoot === null)) {
+        return { status: 400, body: { error: 'On use is available for individual project brains.' } };
+      }
+      const results = [];
+      for (const target of targets) {
+        results.push(await updateSelectedPluginActivation(req.params.id, enabled, mode, target));
+      }
+      return { status: 200, body: { success: results.every(result => result.success), results } };
+    });
+    activationTail = change.catch(() => {});
+    const { status, body } = await change;
+    res.status(status).json(body);
+  } catch (err) { res.status(err.status || 400).json({ error: err.message }); }
 });
 
+function reportedCleanup(result) {
+  if (!result.cleanup) return undefined;
+  const { ok, state } = result.cleanup;
+  return { ok, state, ...(ok ? {} : { error: 'The plugin is off, but cleanup did not finish. Retry cleanup.' }) };
+}
+
+async function updateSelectedPluginActivation(id, enabled, mode, { brainId, name, projectRoot }) {
+  const identity = { brainId, name };
+  const failure = error => ({ ...identity, success: false, error });
+  try {
+    const plugin = getPluginById(id, projectRoot);
+    if (!plugin?.valid) return failure('Plugin is unavailable in this brain.');
+    if ((enabled === false || mode === 'on-use') && REQUIRED_INSTALLATION_PLUGIN_IDS.includes(id)) {
+      return failure('Required plugins cannot be disabled.');
+    }
+    const result = mode === 'use'
+      ? await activatePluginOnUse(id, { projectRoot })
+      : await setPluginActive(id, mode ?? enabled, { projectRoot, scope: projectRoot === null ? 'shared' : 'project' });
+    if (!result) {
+      const activation = pluginActivation(plugin, { projectRoot });
+      return activation.enabled ? { ...identity, success: true, activation } : failure('This plugin is not set to open on use.');
+    }
+    if (mode === 'use' && !result.activation.enabled) return failure('The plugin was switched off before it could open.');
+    const cleanup = reportedCleanup(result);
+    const error = cleanup?.error || (result.compilation.ok ? undefined : 'Activation was saved, but the workspace could not be rebuilt.');
+    return { ...identity, success: !error, activation: result.activation, cleanup, error };
+  } catch {
+    return failure('Could not complete activation in this brain.');
+  }
+}
+
 router.post('/api/plugins/:id/credentials', requireAuth, requireScope('config:write'), async (req, res) => {
+  let target;
+  try { target = surfaceTarget(req, req.query.brain); }
+  catch (error) { return res.status(error.status || 400).json({ error: 'Could not select the credential workspace.' }); }
   try {
-    const plugin = getPluginById(req.params.id, projectRoot());
+    const plugin = getPluginById(req.params.id, target.projectRoot);
     if (!plugin) return res.status(404).json({ error: 'Plugin not installed' });
     const { key, value } = req.body || {};
     if (typeof key !== 'string' || typeof value !== 'string' || value.length > 16384 || !plugin.manifest.secrets?.some(secret => secret.key === key)) return badRequest(res, 'Invalid declared credential');
     const { loadPluginModule } = await import('../../core/plugin-runtime.mjs');
-    const owner = await loadPluginModule(plugin.id, 'credentials');
+    const owner = await loadPluginModule(plugin.id, 'credentials', { projectRoot: target.projectRoot });
     const result = await owner.saveCredential({ key, value, configuration: readPluginRecord(plugin)?.configuration || {}, brainDir: process.env.TR_SECRETS_BRAIN || globalBrainDir || BRAIN_DIR });
     res.json(result);
   } catch (error) {
@@ -86,15 +154,21 @@ router.put('/api/plugins/:id/configuration', requireAuth, requireScope('config:w
 /** Serve only modules declared by an installed plugin's UI manifest. */
 router.get('/api/plugins/:id/ui/:element', requireAuth, requireScope('config:read'), (req, res) => {
   try {
-    const plugin = getPluginById(req.params.id, projectRoot());
-    if (!plugin?.valid) return res.status(404).json({ error: 'Plugin unavailable' });
+    const target = surfaceTarget(req, req.query.brain);
+    const plugin = getPluginById(req.params.id, target.projectRoot);
+    if (!plugin?.valid || (req.query.brain !== undefined && !pluginActivation(plugin, target).enabled)) {
+      return res.status(404).json({ error: 'Plugin unavailable' });
+    }
     const element = plugin.manifest?.ui?.elements?.find((item) => item.id === req.params.element);
     if (!element) return res.status(404).json({ error: 'UI element unavailable' });
     const root = fs.realpathSync(plugin.dir);
     const file = fs.realpathSync(path.resolve(root, element.module));
     if (!file.startsWith(root + path.sep)) return res.status(400).json({ error: 'Invalid UI module path' });
     res.type('text/javascript').set('X-Content-Type-Options', 'nosniff').send(fs.readFileSync(file, 'utf8'));
-  } catch (err) { serverError(res, err); }
+  } catch (err) {
+    if ([400, 403, 404, 409, 503].includes(err.status)) return res.status(err.status).json({ error: err.message });
+    serverError(res, err);
+  }
 });
 
 /** Serve only the logo a plugin declares in branding.logo, never an arbitrary file. */
@@ -121,15 +195,45 @@ router.get('/api/plugins/:id/logo', requireAuth, requireScope('config:read'), (r
  * Installed plugins (project + global): manifest facts, provenance, content
  * hash, sharing state and scheduled-task history. Nothing else.
  */
-router.get("/api/plugins", requireAuth, requireScope("config:read"), (_req, res) => {
+router.get("/api/plugins", requireAuth, requireScope("config:read"), (req, res) => {
   try {
-    const plugins = listInstalledPlugins(projectRoot());
+    const selection = req.query.brain;
+    if (selection !== undefined && typeof selection !== 'string') return badRequest(res, 'Use one comma-separated brain selector.');
+    const plugins = selection === undefined
+      ? listInstalledPlugins(projectRoot())
+      : selectedPluginInventory(resolvePluginBrainTargets(selection.split(','), req.auth));
     res.json({ success: true, count: plugins.length, plugins });
   } catch (err) {
+    if (err.status) return res.status(err.status).json({ error: err.message });
     serverError(res, err);
   }
 });
 
+function selectedPluginInventory(targets) {
+  const descriptions = new Map();
+  const serving = new Map(discoverPlugins(projectRoot()).map(plugin => [plugin.id, plugin]));
+  const catalogs = targets.map(target => new Map(
+    listInstalledPlugins(target.projectRoot, { descriptions }).map(plugin => [plugin.id, plugin]),
+  ));
+  const ids = new Set(catalogs.flatMap(catalog => [...catalog.keys()]));
+  return [...ids].map(id => {
+    const entries = catalogs.map(catalog => catalog.get(id));
+    const representative = entries.find(plugin => plugin?.valid) || entries.find(Boolean);
+    const activationByBrain = entries.map((plugin, index) => {
+      const { brainId, name } = targets[index];
+      const state = !plugin ? 'unavailable' : !plugin.valid ? 'error' : (plugin.activation?.state || 'error');
+      const mode = state === 'inactive' && plugin.activation?.mode;
+      return { brainId, name, state, enabled: state === 'active', required: !!plugin?.activation?.required, ...(mode ? { mode } : {}) };
+    });
+    const first = activationByBrain[0];
+    const state = activationByBrain.every(item => item.state === first.state && item.mode === first.mode) ? first.state : 'mixed';
+    const activation = { state, enabled: state === 'active', required: activationByBrain.some(item => item.required),
+      ...(state !== 'mixed' && first.mode ? { mode: first.mode } : {}) };
+    return { ...representative, activation, activationByBrain,
+      servingAvailable: Boolean(serving.get(id) && serving.get(id).dir === representative.dir) };
+  });
+}
+
 /**
  * GET /api/plugins/available
  * Plugins bundled with this Total Recall package, installable on any node.
@@ -277,28 +381,7 @@ router.get("/api/plugins/:id", requireAuth, requireScope("config:read"), (req, r
   try {
     const plugin = getPluginById(req.params.id, projectRoot());
     if (!plugin) return res.status(404).json({ success: false, error: `Plugin ${req.params.id} not found` });
-    res.json({ success: true, plugin: { ...describePlugin(plugin), manifest: plugin.manifest } });
-  } catch (err) {
-    serverError(res, err);
-  }
-});
-
-/**
- * PATCH /api/plugins/:id/card-face
- * Customizes card face skin, theme, colors, headline, quick actions, and metrics.
- */
-router.patch("/api/plugins/:id/card-face", requireAuth, requireScope("config:write"), (req, res) => {
-  try {
-    const plugin = getPluginById(req.params.id, projectRoot());
-    if (!plugin) return res.status(404).json({ success: false, error: `Plugin ${req.params.id} not found` });
-    const manifestPath = path.join(plugin.dir, "plugin.json");
-    if (!fs.existsSync(manifestPath)) return res.status(404).json({ success: false, error: "Manifest not found" });
-    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
-    const { card_face = {}, branding = {} } = req.body || {};
-    manifest.card_face = { ...(manifest.card_face || {}), ...card_face };
-    manifest.branding = { ...(manifest.branding || {}), ...branding };
-    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
-    res.json({ success: true, card_face: manifest.card_face, branding: manifest.branding });
+    res.json({ success: true, plugin: { ...describePlugin(plugin, projectRoot()), manifest: plugin.manifest } });
   } catch (err) {
     serverError(res, err);
   }
@@ -312,16 +395,37 @@ router.patch("/api/plugins/:id/card-face", requireAuth, requireScope("config:wri
  * write-level regardless of that declaration.
  */
 router.post("/api/plugins/:id/run", requireAuth, (req, res, next) => {
-  const { subcommand, args = [], stdin, execution } = req.body || {};
+  const { subcommand, args = [], stdin, execution, brainId } = req.body || {};
   try {
-    const plugin = getPluginById(req.params.id, projectRoot());
-    const operation = plugin?.valid && plugin.manifest?.cli?.subcommands?.find(item => item.name === subcommand);
+    const target = surfaceTarget(req, brainId);
+    const plugin = getPluginById(req.params.id, target.projectRoot);
+    if (brainId !== undefined && execution) {
+      return res.status(400).json({ success: false, error: 'Use the selected brain with local plugin execution.' });
+    }
+    if (brainId !== undefined && ['on', 'off'].includes(subcommand || args?.[0])) {
+      return res.status(400).json({ success: false, error: 'Use the selected brain activation control.' });
+    }
+    const declared = plugin?.valid ? plugin.manifest?.cli?.subcommands || [] : [];
+    const operation = declared.find(item => item.name === subcommand);
+    const activation = ['on', 'off'].includes(subcommand) && Array.isArray(args) && !args.length && stdin === undefined && !execution;
+    const browserBlocked = item => item.sensitive_output === true || item.terminal_only === true;
+    if (operation ? browserBlocked(operation) : !activation && declared.some(browserBlocked)) {
+      return res.status(403).json({ success: false, error: 'Use the owning CLI or account controls for this operation.' });
+    }
+    const terminalFlags = new Set((operation ? [operation] : declared).flatMap(item => item.terminal_only_args ?? []));
+    if (Array.isArray(args) && args.some(arg => typeof arg === 'string' && terminalFlags.has(arg.split('=', 1)[0]))) {
+      return res.status(403).json({ success: false, error: 'Use the owning CLI for terminal-only arguments.' });
+    }
     res.locals.executionPlugin = plugin;
+    res.locals.executionTarget = target;
     const read = typeof subcommand === 'string' && Array.isArray(args) && args.every(arg => typeof arg === 'string') &&
       operation?.effect === 'read' && stdin === undefined && !execution &&
       !operation.args?.some(arg => arg.secret);
     return requireScope(read ? 'config:read' : 'config:write')(req, res, next);
-  } catch (error) { badRequest(res, error.message); }
+  } catch (error) {
+    if ([400, 403, 404, 409, 503].includes(error.status)) return res.status(error.status).json({ error: error.message });
+    badRequest(res, error.message);
+  }
 }, async (req, res) => {
   try {
     const { subcommand = "", args = [], stdin, execution } = req.body || {};
@@ -329,21 +433,26 @@ router.post("/api/plugins/:id/run", requireAuth, (req, res, next) => {
       return badRequest(res, "subcommand must be a string and args an array of strings");
     }
     const plugin = res.locals.executionPlugin;
+    const target = res.locals.executionTarget;
+    const cwd = target.projectRoot ?? target.brainDir;
     if (!plugin) return res.status(404).json({ success: false, error: `Plugin ${req.params.id} not found` });
     if (!plugin.valid) return badRequest(res, `Plugin ${plugin.id} has an invalid manifest: ${plugin.errors.join("; ")}`);
     if (!plugin.manifest?.cli?.handler) return badRequest(res, `Plugin ${plugin.id} does not declare a CLI handler`);
+    if (req.body?.brainId !== undefined && !pluginActivation(plugin, target).enabled) {
+      return res.status(403).json({ success: false, error: 'Plugin is off in the selected brain.' });
+    }
     validatePluginSecretInput(plugin, subcommand, stdin);
 
     if (execution) {
       if (stdin !== undefined) return badRequest(res, 'Credential operations require direct local execution');
-      if (!pluginActivation(plugin, { projectRoot: projectRoot() }).enabled && !['on', 'off', 'status', 'health', 'jobs', '--help', 'help'].includes(subcommand)) return badRequest(res, `Plugin ${plugin.id} is inactive`);
+      if (!pluginActivation(plugin, target).enabled && !['on', 'off', 'status', 'health', 'jobs', '--help', 'help'].includes(subcommand)) return badRequest(res, `Plugin ${plugin.id} is inactive`);
       const { loadPluginModule } = await import('../../core/plugin-runtime.mjs');
-      const owner = await loadPluginModule('meta-harness', 'command-executor', { activeRequired: true });
-      const result = await owner.executeCommand({ plugin, subcommand, args, execution, projectRoot: projectRoot() });
+      const owner = await loadPluginModule('meta-harness', 'command-executor', { activeRequired: true, projectRoot: target.projectRoot });
+      const result = await owner.executeCommand({ plugin, subcommand, args, execution, projectRoot: cwd });
       return res.json({ success: result.ok, pluginId: plugin.id, ...result });
     }
 
-    const result = await runPluginCommand(plugin, { subcommand, args, ...(stdin !== undefined ? { stdinText: stdin } : {}), cwd: projectRoot(), secretsBrainDir: process.env.TR_SECRETS_BRAIN || globalBrainDir || BRAIN_DIR, maxOutputBytes: 4 * 1024 * 1024 });
+    const result = await runPluginCommand(plugin, { subcommand, args, ...(stdin !== undefined ? { stdinText: stdin } : {}), cwd, projectRoot: target.projectRoot, secretsBrainDir: process.env.TR_SECRETS_BRAIN || globalBrainDir || BRAIN_DIR, maxOutputBytes: 4 * 1024 * 1024 });
     res.json({ success: result.ok, pluginId: plugin.id, ...result });
   } catch (err) {
     badRequest(res, err.message);

package/src/server/routes/ui-chunks.mjs

@@ -0,0 +1,192 @@
+import { Router } from 'express';
+import { addWorkspaceUiChunk, getUiChunk, readPluginDesign, searchUiChunks, UiChunkInputError } from '../../core/ui-chunks.mjs';
+import { chooseUiComposition } from '../../core/ui-chunk-choice.mjs';
+import {
+  createWorkspacePage, listWorkspacePages, prepareWorkspacePage, publishWorkspaceComposition,
+  readWorkspaceComposition, readWorkspacePage, saveWorkspaceCompositionPage,
+  updateWorkspacePage,
+} from '../../core/workspace-compositions.mjs';
+import { requireAuth, requireScope } from '../auth.mjs';
+import { resolvePluginBrainTargets } from '../plugin-brain-targets.mjs';
+import { BRAIN_DIR } from './_shared.mjs';
+
+const router = Router();
+
+function workspaceTarget(req, brainId) {
+  return brainId === undefined
+    ? { brainDir: BRAIN_DIR, projectRoot: process.cwd() }
+    : resolvePluginBrainTargets([brainId], req.auth)[0];
+}
+
+function sendScopeError(res, error) {
+  if ([400, 403, 404, 409, 503].includes(error.status)) {
+    res.status(error.status).json({ error: error.message });
+    return true;
+  }
+  return false;
+}
+
+function sendWorkspaceData(res, read, resource = 'UI chunk') {
+  res.set('Cache-Control', 'private, no-store').set('X-Content-Type-Options', 'nosniff');
+  try {
+    const result = read();
+    if (!result) return res.status(404).json({ error: `${resource} unavailable` });
+    return res.json(result);
+  } catch (error) {
+    if (error instanceof UiChunkInputError) return res.status(400).json({ error: error.message });
+    if (sendScopeError(res, error)) return;
+    return res.status(500).json({ error: resource === 'UI chunk' ? 'Could not read the UI chunk catalog' : 'Could not read saved pages' });
+  }
+}
+
+router.get('/api/ui-chunks', requireAuth, requireScope('config:read'), (req, res) => {
+  const { plugin, surface, q, limit, offset } = req.query;
+  return sendWorkspaceData(res, () => {
+    if (limit !== undefined && (typeof limit !== 'string' || !/^\d{1,3}$/.test(limit))) {
+      throw new UiChunkInputError('Limit must be between 1 and 200.');
+    }
+    if (offset !== undefined && (typeof offset !== 'string' || !/^\d{1,16}$/.test(offset))) {
+      throw new UiChunkInputError('Offset must be a nonnegative integer.');
+    }
+    return searchUiChunks({
+      ...workspaceTarget(req, req.query.brain), plugin, surface, query: q,
+      limit: limit === undefined ? undefined : Number(limit),
+      offset: offset === undefined ? undefined : Number(offset),
+    });
+  });
+});
+
+router.get('/api/ui-chunks/:plugin/:id', requireAuth, requireScope('config:read'), (req, res) =>
+  sendWorkspaceData(res, () => {
+    const chunk = getUiChunk(req.params.plugin, req.params.id, { ...workspaceTarget(req, req.query.brain), surface: req.query.surface });
+    return chunk ? { chunk } : null;
+  }));
+
+router.get('/api/ui-chunks/:plugin/design/revision', requireAuth, requireScope('config:read'), (req, res) =>
+  sendWorkspaceData(res, () => {
+    const { revision } = req.query;
+    if (revision !== undefined && (typeof revision !== 'string' || !/^[a-f0-9]{64}$/.test(revision))) {
+      throw new UiChunkInputError('Invalid design revision.');
+    }
+    return readPluginDesign(req.params.plugin, { ...workspaceTarget(req, req.query.brain), revision });
+  }));
+
+router.get('/api/ui-chunks/:plugin/composition/current', requireAuth, requireScope('config:read'), (req, res) =>
+  sendWorkspaceData(res, () => {
+    const { brainDir, projectRoot } = workspaceTarget(req, req.query.brain);
+    return readWorkspaceComposition(brainDir, req.params.plugin, projectRoot);
+  }));
+
+function workspacePagePath(id, brain) {
+  return '/memory?' + new URLSearchParams({ page: id, brain });
+}
+
+router.get('/api/workspace/pages', requireAuth, requireScope('config:read'), (req, res) =>
+  sendWorkspaceData(res, () => {
+    const { brainDir } = resolvePluginBrainTargets([req.query.brain], req.auth)[0];
+    return { pages: listWorkspacePages(brainDir) };
+  }, 'Saved page'));
+
+router.get('/api/workspace/pages/:id', requireAuth, requireScope('config:read'), (req, res) =>
+  sendWorkspaceData(res, () => {
+    const { brainDir, projectRoot } = resolvePluginBrainTargets([req.query.brain], req.auth)[0];
+    return readWorkspacePage(brainDir, req.params.id, projectRoot);
+  }, 'Saved page'));
+
+router.post('/api/workspace/pages', requireAuth, requireScope('config:write'), async (req, res) => {
+  res.set('Cache-Control', 'private, no-store');
+  if (!req.is('application/json')) return res.status(415).json({ error: 'Use JSON to save a page.' });
+  try {
+    const { id, title, brainId, sourcePlugin, sourceVersion, keys } = req.body ?? {};
+    const { brainDir, projectRoot } = resolvePluginBrainTargets([brainId], req.auth)[0];
+    if (keys !== undefined && (sourcePlugin !== undefined || sourceVersion !== undefined)) {
+      throw new UiChunkInputError('Supply either ordered block keys or a source Home revision.');
+    }
+    const page = keys === undefined
+      ? await saveWorkspaceCompositionPage(brainDir, { id, title, sourcePlugin, sourceVersion }, projectRoot)
+      : await createWorkspacePage(brainDir, { id, title, keys }, projectRoot);
+    return res.status(201).json({ ...page, path: workspacePagePath(id, brainId) });
+  } catch (error) {
+    if (error instanceof UiChunkInputError) return res.status(400).json({ error: error.message });
+    if (sendScopeError(res, error)) return;
+    return res.status(500).json({ error: 'Could not save the page.' });
+  }
+});
+
+router.put('/api/workspace/pages/:id', requireAuth, requireScope('config:write'), async (req, res) => {
+  res.set('Cache-Control', 'private, no-store');
+  if (!req.is('application/json')) return res.status(415).json({ error: 'Use JSON to edit a page.' });
+  try {
+    const { brainId, revision, keys } = req.body ?? {};
+    const { id } = req.params;
+    const { brainDir, projectRoot } = resolvePluginBrainTargets([brainId], req.auth)[0];
+    const page = await updateWorkspacePage(brainDir, { id, revision, keys }, projectRoot);
+    return res.json({ ...page, path: workspacePagePath(id, brainId) });
+  } catch (error) {
+    if (error instanceof UiChunkInputError) return res.status(400).json({ error: error.message });
+    if (sendScopeError(res, error)) return;
+    if (error.message.startsWith('Plugin state version conflict')) {
+      return res.status(409).json({ error: 'The saved page changed. Read its current revision before editing.' });
+    }
+    return res.status(500).json({ error: 'Could not edit the saved page.' });
+  }
+});
+
+router.post('/api/ui-chunks/pool', requireAuth, requireScope('config:write'), async (req, res) => {
+  res.set('Cache-Control', 'private, no-store');
+  if (!req.is('application/json')) return res.status(415).json({ error: 'Use JSON to add a block.' });
+  try {
+    const { brainDir, projectRoot } = workspaceTarget(req, req.body?.brainId);
+    return res.status(201).json(await addWorkspaceUiChunk(brainDir, req.body ?? {}, projectRoot));
+  } catch (error) {
+    if (error instanceof UiChunkInputError) return res.status(400).json({ error: error.message });
+    if (sendScopeError(res, error)) return;
+    if (error.message.startsWith('Plugin state version conflict')) return res.status(409).json({ error: 'That workspace block ID already exists.' });
+    return res.status(500).json({ error: 'Could not add the block to the pool.' });
+  }
+});
+
+router.post(['/api/ui-chunks/suggest', '/api/ui-chunks/compose'], requireAuth, requireScope('config:write'), async (req, res) => {
+  res.set('Cache-Control', 'private, no-store');
+  if (!req.is('application/json')) return res.status(415).json({ error: 'Use JSON to request a block suggestion.' });
+  const { plugin, query, brainId, pageId, pageTitle } = req.body ?? {};
+  if (typeof plugin !== 'string' || typeof query !== 'string' || !query.trim()) {
+    return res.status(400).json({ error: 'Choose a plugin and describe what you want to do.' });
+  }
+  try {
+    const publish = req.path === '/api/ui-chunks/compose';
+    const named = pageId !== undefined || pageTitle !== undefined;
+    if (named && !publish) throw new UiChunkInputError('Use compose to publish a saved page.');
+    const resolveDestination = () => named
+      ? resolvePluginBrainTargets([brainId], req.auth)[0]
+      : workspaceTarget(req, brainId);
+    const target = resolveDestination();
+    if (named) prepareWorkspacePage(target.brainDir, pageId, pageTitle);
+    const current = publish && !named ? readWorkspaceComposition(target.brainDir, plugin, target.projectRoot) : null;
+    const { chunks } = searchUiChunks({ ...target, plugin: publish ? undefined : plugin, surface: 'page', query, limit: 20 });
+    const selection = await chooseUiComposition(chunks, query.trim(), undefined, target);
+    if (!publish) return res.json({ chunks, selection });
+    if (selection.source !== 'decision' || !selection.keys.length) {
+      return res.status(422).json({ error: 'Jev did not select a page to publish.', selection });
+    }
+    const destination = resolveDestination();
+    if (target.brainDir !== destination.brainDir || target.projectRoot !== destination.projectRoot) {
+      return res.status(409).json({ error: 'The destination brain changed while Jev was composing.' });
+    }
+    if (named) {
+      const page = await createWorkspacePage(destination.brainDir, { id: pageId, title: pageTitle, keys: selection.keys }, destination.projectRoot);
+      return res.json({ selection, version: page.version, path: workspacePagePath(pageId, brainId) });
+    }
+    const state = await publishWorkspaceComposition(target.brainDir, plugin, selection.keys, current.version, target.projectRoot);
+    const params = new URLSearchParams({ plugin });
+    if (destination.brainId) params.set('brain', destination.brainId);
+    return res.json({ selection, version: state.version, path: '/memory?' + params });
+  } catch (error) {
+    if (error instanceof UiChunkInputError) return res.status(400).json({ error: error.message });
+    if (sendScopeError(res, error)) return;
+    if (error.message.startsWith('Plugin state version conflict')) return res.status(409).json({ error: 'The page changed while Jev was composing it.' });
+    return res.status(500).json({ error: 'Could not suggest a page block.' });
+  }
+});
+
+export default router;