@bahulam/code 0.1.16 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bahulam/code",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Bahulam Code — abundance, in your terminal. CLI-first, reliability-first, sub-agents, 65.6% SWE-bench Verified.",
   "type": "module",
   "bin": {

package/src/agents/loader.mjs

@@ -16,6 +16,7 @@ import { parseAgentDefinition } from './parser.mjs';
 export class AgentLoader {
     constructor() {
         this.agents = new Map();
+        this.aliases = new Map();
         this.searchPaths = [];
     }
 
@@ -48,9 +49,7 @@ export class AgentLoader {
                 try {
                     const content = fs.readFileSync(filePath, 'utf-8');
                     const agent = parseAgentDefinition(content, ext);
-                    if (agent && agent.name && !this.agents.has(agent.name)) {
-                        this.agents.set(agent.name, { ...agent, source: filePath });
-                    }
+                    this._register(agent, filePath);
                 } catch (err) {
                     if (process.env.DEBUG) {
                         console.error(`Failed to load agent ${filePath}: ${err.message}`);
@@ -71,30 +70,50 @@ export class AgentLoader {
     loadFromPlugins(plugins) {
         if (!Array.isArray(plugins)) return this;
         for (const plugin of plugins) {
-            const agents = plugin.spec?.agents || [];
+            const agents = plugin.config?.agents || [];
             for (const agentDef of agents) {
                 const slug = agentDef.slug || agentDef.name || '';
                 if (!slug) continue;
-                // Project agents take precedence — skip if already registered
-                if (this.agents.has(slug)) continue;
-                this.agents.set(slug, {
+                this._register({
                     ...agentDef,
                     slug,
                     source: `plugin:${plugin.metadata?.name || 'unknown'}`,
                     source_scope: 'plugin',
-                });
+                }, null);
             }
         }
         return this;
     }
 
+    _register(agent, sourcePath = null) {
+        if (!agent) return null;
+        const slug = normalizeKey(agent.slug || agent.id || agent.name);
+        if (!slug) return null;
+        const aliases = [
+            slug,
+            normalizeKey(agent.name),
+            normalizeKey(agent.id),
+        ].filter(Boolean);
+
+        // Earlier search paths have higher precedence: project beats global,
+        // and both beat plugin-provided agents.
+        if (aliases.some(alias => this.aliases.has(alias))) return null;
+
+        const stored = { ...agent, slug: agent.slug || slug, ...(sourcePath ? { source: sourcePath } : {}) };
+        this.agents.set(slug, stored);
+        for (const alias of aliases) this.aliases.set(alias, slug);
+        return stored;
+    }
+
     /**
      * Get an agent definition by name.
      * @param {string} name
      * @returns {object|null}
      */
     get(name) {
-        return this.agents.get(name) || null;
+        const key = normalizeKey(name);
+        const slug = this.aliases.get(key) || key;
+        return this.agents.get(slug) || null;
     }
 
     /**
@@ -111,6 +130,14 @@ export class AgentLoader {
      * @returns {boolean}
      */
     has(name) {
-        return this.agents.has(name);
+        return Boolean(this.get(name));
     }
 }
+
+function normalizeKey(value) {
+    return String(value || '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}

package/src/agents/registry.mjs

@@ -0,0 +1,240 @@
+import { BUILTIN_AGENTS } from '../terminal/agents.mjs';
+import { loadBahulamSettings } from '../config/settings-loader.mjs';
+import { agentToSpec, listLocalAgents } from './scaffold.mjs';
+import * as crypto from 'node:crypto';
+
+export const SUB_AGENT_EVENT_SCHEMA = [
+  { type: 'sub_agent_start', description: 'A delegated sub-agent run started.' },
+  { type: 'sub_agent_tool', description: 'A sub-agent requested or completed a tool call.' },
+  { type: 'sub_agent_complete', description: 'A delegated sub-agent run completed.' },
+  { type: 'graph_run_start', description: 'A local workflow or delegated graph run started.' },
+  { type: 'graph_node_start', description: 'One sub-agent, job, or service node started.' },
+  { type: 'graph_node_result', description: 'One sub-agent, job, or service node completed.' },
+  { type: 'graph_run_result', description: 'The local workflow or delegated graph run completed.' },
+  { type: 'tool_call', description: 'A tool call was requested; sub_agent identifies delegated calls.' },
+  { type: 'tool_result', description: 'A tool call completed; sub_agent identifies delegated calls.' },
+  { type: 'content', description: 'A sub-agent emitted final or partial answer content.' },
+  { type: 'error', description: 'A sub-agent, tool, or graph node failed.' },
+];
+
+const READ_ONLY_TOOLS = ['read_file', 'search_code', 'list_files', 'search_files', 'get_file_info'];
+
+export function compactAgentMetadata(agent) {
+  return {
+    slug: agent.slug,
+    name: agent.name,
+    description: agent.description || '',
+    role: agent.role || 'specialist',
+    model: agent.model || null,
+    models: agent.models || undefined,
+    tools: Array.isArray(agent.tools) ? agent.tools : [],
+    capabilities: Array.isArray(agent.capabilities) ? agent.capabilities : [],
+    domains: Array.isArray(agent.domains) ? agent.domains : [],
+    source_scope: agent.source_scope || 'unknown',
+    source: agent.source || '',
+    content_hash: agent.content_hash || '',
+    read_only: Boolean(agent.read_only || agent.readOnly),
+    runnable: agent.runnable !== false,
+  };
+}
+
+export function createAgentRegistry({
+  cwd = process.cwd(),
+  pluginRegistry = null,
+  channel = 'main',
+  settingsLoader = loadBahulamSettings,
+} = {}) {
+  function currentCwd() {
+    return typeof cwd === 'function' ? cwd() : cwd || process.cwd();
+  }
+
+  function pluginAgentAllowlist() {
+    try {
+      const loaded = settingsLoader({ cwd: currentCwd() });
+      const settings = loaded?.settings || loaded || {};
+      const allowlist = settings?.plugins?.agent_allowlist;
+      return Array.isArray(allowlist) ? allowlist.map(String) : [];
+    } catch {
+      return [];
+    }
+  }
+
+  function normalizeAgentTools(tools) {
+    if (Array.isArray(tools)) return tools.map(String).filter(Boolean);
+    if (typeof tools === 'string') {
+      return tools.split(',').map(item => item.trim()).filter(Boolean);
+    }
+    return READ_ONLY_TOOLS.slice(0, 3);
+  }
+
+  function pluginAgentToLocalShape(agentDef) {
+    const slug = agentDef.slug || agentDef.name || '';
+    const pluginName = agentDef._plugin_name || '';
+    const base = {
+      ...agentDef,
+      slug,
+      name: agentDef.name || slug,
+      description: agentDef.description || '',
+      role: agentDef.role || 'specialist',
+      model: agentDef.model || null,
+      models: agentDef.models || null,
+      tools: normalizeAgentTools(agentDef.tools || agentDef.agent_tools),
+      capabilities: Array.isArray(agentDef.capabilities) ? agentDef.capabilities : [],
+      domains: Array.isArray(agentDef.domains) ? agentDef.domains : [],
+      prompt: agentDef.prompt || agentDef.system_prompt || agentDef.systemPrompt || '',
+      system_prompt: agentDef.system_prompt || agentDef.systemPrompt || agentDef.prompt || '',
+      source_scope: 'plugin',
+      source: agentDef.source || (pluginName ? `plugin:${pluginName}` : 'plugin'),
+      content_hash: agentDef.content_hash || '',
+    };
+    const spec = agentDef.spec || agentToSpec(base);
+    if (spec.config?.metadata && typeof spec.config.metadata === 'object') {
+      spec.config.metadata.source = base.source;
+      spec.config.metadata.source_scope = 'plugin';
+    }
+    spec.source = base.source;
+    spec.source_scope = 'plugin';
+    const content = JSON.stringify(spec);
+    return {
+      ...base,
+      slug: spec.slug,
+      spec,
+      content_hash: agentDef.content_hash || crypto.createHash('sha256').update(content).digest('hex'),
+    };
+  }
+
+  function platformAgentToLocalShape(def) {
+    const base = {
+      slug: def.command,
+      command: def.command,
+      name: def.name || def.command,
+      description: def.description || '',
+      role: 'platform',
+      model: null,
+      models: undefined,
+      tools: Array.isArray(def.tools) && def.tools.length
+        ? def.tools
+        : (def.readOnly ? READ_ONLY_TOOLS : []),
+      capabilities: [],
+      domains: [],
+      prompt: def.systemPrompt || '',
+      system_prompt: def.systemPrompt || '',
+      source_scope: 'platform',
+      source: 'platform:cli',
+      content_hash: '',
+      read_only: Boolean(def.readOnly),
+      readOnly: Boolean(def.readOnly),
+      runnable: true,
+    };
+    const spec = agentToSpec(base);
+    spec.source = base.source;
+    spec.source_scope = 'platform';
+    if (spec.config?.metadata && typeof spec.config.metadata === 'object') {
+      spec.config.metadata.source = base.source;
+      spec.config.metadata.source_scope = 'platform';
+    }
+    return { ...base, spec };
+  }
+
+  function listPlatformAgents() {
+    return BUILTIN_AGENTS.map(platformAgentToLocalShape);
+  }
+
+  function listPluginAgents() {
+    if (!pluginRegistry?.listAgents) return [];
+    return pluginRegistry.listAgents().map(pluginAgentToLocalShape).filter(agent => agent.slug);
+  }
+
+  function listRunnables() {
+    const bySlug = new Map();
+    for (const agent of listLocalAgents(currentCwd())) {
+      if (agent.slug && !bySlug.has(agent.slug)) {
+        bySlug.set(agent.slug, { ...agent, runnable: true });
+      }
+    }
+    for (const agent of listPlatformAgents()) {
+      if (agent.slug && !bySlug.has(agent.slug)) {
+        bySlug.set(agent.slug, agent);
+      }
+    }
+    const allowlist = new Set(pluginAgentAllowlist());
+    for (const agent of listPluginAgents()) {
+      if (!agent.slug || bySlug.has(agent.slug)) continue;
+      if (channel === 'workspace' || allowlist.has(agent.slug)) {
+        bySlug.set(agent.slug, { ...agent, runnable: true });
+      }
+    }
+    return [...bySlug.values()];
+  }
+
+  function listWorkspaceScopedPluginAgents() {
+    const runnableSlugs = new Set(listRunnables().map(agent => agent.slug));
+    return listPluginAgents()
+      .filter(agent => agent.slug && !runnableSlugs.has(agent.slug))
+      .map(agent => ({ ...agent, runnable: false }));
+  }
+
+  function listAvailableAgents() {
+    // Backend workspaces such as kepler-code already implement their
+    // platform roles (explore/plan/verify/debug/refactor) as reserved
+    // meta-tool targets. Only send extension agents here so we do not
+    // shadow the backend's native routing.
+    return listRunnables().filter(agent => agent.source_scope !== 'platform');
+  }
+
+  function findAgent(target) {
+    const needle = String(target || '').trim().toLowerCase();
+    if (!needle) return null;
+    return listRunnables().find(agent => [
+      agent.slug,
+      agent.id,
+      agent.command,
+      agent.name,
+    ].some(value => String(value || '').trim().toLowerCase() === needle)) || null;
+  }
+
+  function filterAgents(args = {}) {
+    let scope = String(args.scope || '').trim();
+    if (scope === 'builtin') scope = 'platform';
+    if (scope && !['project', 'global', 'plugin', 'platform'].includes(scope)) {
+      throw new Error('scope must be "project", "global", "plugin", "platform", or "builtin"');
+    }
+    const pool = scope === 'plugin'
+      ? [...listRunnables(), ...listWorkspaceScopedPluginAgents()]
+      : listRunnables();
+    const query = String(args.query || args.name || '').trim().toLowerCase();
+    return pool
+      .filter(agent => !scope || agent.source_scope === scope)
+      .filter(agent => {
+        if (!query) return true;
+        return [
+          agent.slug,
+          agent.name,
+          agent.description,
+          agent.role,
+          ...(Array.isArray(agent.capabilities) ? agent.capabilities : []),
+          ...(Array.isArray(agent.domains) ? agent.domains : []),
+        ].some(value => String(value || '').toLowerCase().includes(query));
+      });
+  }
+
+  function observability() {
+    return {
+      version: 1,
+      events: SUB_AGENT_EVENT_SCHEMA,
+      correlation_fields: ['graph_run_id', 'node_id', 'sub_agent', 'sub_agent_run_id', 'call_id'],
+      tool_attribution_fields: ['internal', 'sub_agent', 'subAgent'],
+    };
+  }
+
+  return {
+    listRunnables,
+    listAvailableAgents,
+    listPlatformAgents,
+    listPluginAgents,
+    listWorkspaceScopedPluginAgents,
+    filterAgents,
+    findAgent,
+    observability,
+  };
+}

package/src/commands/install.mjs

@@ -4,7 +4,7 @@
  *   bahulam pull <src>     — install an ingredient (currently pi:<name>).
  *                            No pack scaffolding; the raw package lands in
  *                            ~/.bahulam/plugins-pi/ and is only useful when
- *                            referenced by a pack's spec.composes:.
+ *                            referenced by a pack's config.composes:.
  *
  *   bahulam install <src>  — install a full pack.
  *                            For pi:<name>: pulls the ingredient AND
@@ -88,7 +88,7 @@ export async function handlePullCommand(argv, { cwd = process.cwd() } = {}) {
 
   Pull an ingredient (pi package) into ~/.bahulam/plugins-pi/. The
   ingredient is composable but not directly runnable — reference it from
-  a pack's ${CYAN}spec.composes:${RESET} block, or use ${CYAN}bahulam install pi:<name>${RESET}
+  a pack's ${CYAN}config.composes:${RESET} block, or use ${CYAN}bahulam install pi:<name>${RESET}
   to auto-scaffold a full pack around it.
 
   Sources:
@@ -133,7 +133,7 @@ export async function handlePullCommand(argv, { cwd = process.cwd() } = {}) {
     process.stderr.write(`  ${DIM}location${RESET}  ${dest}\n`);
     process.stderr.write(`  ${YELLOW}!${RESET} Pi packages run with your full system permissions. Bahulam does not audit pi packages.\n`);
     process.stderr.write(`  ${DIM}Wrap in a pack:${RESET}  ${CYAN}bahulam install pi:${classified.package_name}${RESET}\n`);
-    process.stderr.write(`  ${DIM}Compose in yours:${RESET} ${CYAN}spec.composes: [{source: pi:${classified.package_name}, expose: [...]}]${RESET}\n\n`);
+    process.stderr.write(`  ${DIM}Compose in yours:${RESET} ${CYAN}config.composes: [{source: pi:${classified.package_name}, expose: [...]}]${RESET}\n\n`);
   } catch (err) {
     process.stderr.write(`\x1b[31m✗\x1b[0m ${err.message}\n`);
     process.exit(1);
@@ -397,7 +397,7 @@ async function preflightAndReport({ dest, args, cwd, meta = null }) {
 
   // Host check for each composed pi ingredient (same policy as the
   // scaffolder path). Blocks install if a required binary is missing.
-  const composes = m.spec?.composes || [];
+  const composes = m.config?.composes || [];
   if (composes.length && !meta) {
     // meta present == scaffolder path already did this pre-scaffold
     const { bahulamHome } = await import('../core/paths.mjs');
@@ -431,11 +431,11 @@ async function preflightAndReport({ dest, args, cwd, meta = null }) {
 
   process.stderr.write(`\n${GREEN}✓${RESET} Installed ${BOLD}${m.metadata.name}${RESET} v${m.metadata.version}\n`);
   process.stderr.write(`  ${DIM}location${RESET}  ${dest}\n`);
-  const nativeTools = (m.spec.tools || []).map(t => t.name);
-  const composedCount = (m.spec.composes || []).reduce((n, c) => n + ((c.expose || []).length || 0), 0);
+  const nativeTools = (m.config.tools || []).map(t => t.name);
+  const composedCount = (m.config.composes || []).reduce((n, c) => n + ((c.expose || []).length || 0), 0);
   process.stderr.write(`  ${DIM}tools${RESET}     ${nativeTools.length ? nativeTools.join(', ') : '(none)'}${composedCount ? ` ${DIM}+ ${composedCount} composed${RESET}` : ''}\n`);
-  process.stderr.write(`  ${DIM}agents${RESET}    ${(m.spec.agents || []).map(a => a.slug).join(', ') || '(none)'}\n`);
-  const views = m.spec.workspace?.views || [];
+  process.stderr.write(`  ${DIM}agents${RESET}    ${(m.config.agents || []).map(a => a.slug).join(', ') || '(none)'}\n`);
+  const views = m.config.views || [];
   process.stderr.write(`  ${DIM}views${RESET}     ${views.length ? views.map(v => v.name).join(', ') : '(none)'}\n`);
   if (meta) {
     process.stderr.write(`  ${DIM}scaffolded${RESET} from ${CYAN}pi:${meta.packageName}${RESET} (namespace ${CYAN}${meta.namespace}${RESET}, ${meta.exposeTools.length} composed tool${meta.exposeTools.length === 1 ? '' : 's'})\n`);

package/src/commands/plugin-manage.mjs

@@ -24,6 +24,7 @@ import { spawn } from 'node:child_process';
 import { parsePluginManifestFile } from '../plugins/manifest.mjs';
 import { preflightPlugin, existingInstalledNames } from '../plugins/preflight.mjs';
 import { parsePiSource } from '../plugins/pi-compose.mjs';
+import { bahulamHome } from '../core/paths.mjs';
 
 const RESET = '\x1b[0m';
 const BOLD = '\x1b[1m';
@@ -38,13 +39,13 @@ const INSTALL_STAMP = '.bahulam-plugin.json';
 function searchDirs(cwd) {
   return [
     { scope: 'project', dir: path.join(cwd, '.bahulam', 'plugins') },
-    { scope: 'global', dir: path.join(os.homedir(), '.bahulam', 'plugins') },
+    { scope: 'global', dir: path.join(bahulamHome(), 'plugins') },
   ];
 }
 
 export function pluginTargetDir({ global, cwd }) {
   return global
-    ? path.join(os.homedir(), '.bahulam', 'plugins')
+    ? path.join(bahulamHome(), 'plugins')
     : path.join(cwd, '.bahulam', 'plugins');
 }
 
@@ -72,7 +73,7 @@ function scanInstalled(cwd) {
       // else in the plugins/ dir is stray (readManifest returns null).
       if (!parsed && !disabled) continue;
       const stamp = readStamp(pluginDir);
-      const agentSlugs = (parsed?.manifest?.spec?.agents || [])
+      const agentSlugs = (parsed?.manifest?.config?.agents || [])
         .map(a => a.slug || a.name).filter(Boolean);
       found.push({
         scope,
@@ -81,10 +82,10 @@ function scanInstalled(cwd) {
         name: parsed?.manifest?.metadata?.name || entry.name.replace(/\.disabled$/, ''),
         version: parsed?.manifest?.metadata?.version || null,
         description: parsed?.manifest?.metadata?.description || '',
-        tools: parsed?.manifest?.spec?.tools?.length || 0,
-        agents: parsed?.manifest?.spec?.agents?.length || 0,
-        views: parsed?.manifest?.spec?.workspace?.views?.length || 0,
-        composes: parsed?.manifest?.spec?.composes?.length || 0,
+        tools: parsed?.manifest?.config?.tools?.length || 0,
+        agents: parsed?.manifest?.config?.agents?.length || 0,
+        views: parsed?.manifest?.config?.views?.length || 0,
+        composes: parsed?.manifest?.config?.composes?.length || 0,
         agentSlugs,
         disabled,
         origin: stamp?.origin || null,
@@ -390,12 +391,12 @@ export async function installFromLocal({ src, targetDir, force }) {
 }
 
 /**
- * Auto-install pi packages referenced by a pack's spec.composes:. Callers
+ * Auto-install pi packages referenced by a pack's config.composes:. Callers
  * invoke this after preflight so a hand-authored pack that composes
  * missing pi ingredients still resolves in one command.
  */
 export async function resolveComposeDependencies(manifest, { targetDir } = {}) {
-  const composes = manifest?.spec?.composes || [];
+  const composes = manifest?.config?.composes || [];
   if (!composes.length) return;
   const { discoverPiTools } = await import('../plugins/pi-compat/probe.mjs');
   const { bahulamHome } = await import('../core/paths.mjs');
@@ -446,7 +447,7 @@ async function cmdList(args, cwd) {
     if (!p.composes) continue;
     try {
       const m = readManifest(p.directory);
-      const composes = m?.manifest?.spec?.composes || [];
+      const composes = m?.manifest?.config?.composes || [];
       pluginComposes.set(p.name, composes.map(c => c.package_name || c.packageName).filter(Boolean));
     } catch { /* skip */ }
   }
@@ -519,7 +520,7 @@ async function cmdList(args, cwd) {
     const orphans = pi.filter(p => usedBy(p.name).length === 0);
     if (orphans.length) {
       process.stderr.write(`\n${YELLOW}!${RESET} ${orphans.length} pi ingredient${orphans.length === 1 ? '' : 's'} installed but not composed by any pack.\n`);
-      process.stderr.write(`  Pi ingredients are unusable on their own — reference in a pack's ${CYAN}spec.composes:${RESET} block.\n`);
+      process.stderr.write(`  Pi ingredients are unusable on their own — reference in a pack's ${CYAN}config.composes:${RESET} block.\n`);
     }
   }
 
@@ -588,9 +589,9 @@ function cmdInfo(args, cwd) {
   }
   if (found.installed_at) process.stderr.write(`  ${DIM}installed${RESET}  ${found.installed_at}\n`);
   if (m) {
-    process.stderr.write(`\n  ${DIM}tools${RESET}      ${(m.spec.tools || []).map(t => t.name).join(', ') || '(none)'}\n`);
-    process.stderr.write(`  ${DIM}agents${RESET}     ${(m.spec.agents || []).map(a => a.slug).join(', ') || '(none)'}\n`);
-    const views = m.spec.workspace?.views || [];
+    process.stderr.write(`\n  ${DIM}tools${RESET}      ${(m.config.tools || []).map(t => t.name).join(', ') || '(none)'}\n`);
+    process.stderr.write(`  ${DIM}agents${RESET}     ${(m.config.agents || []).map(a => a.slug).join(', ') || '(none)'}\n`);
+    const views = m.config.views || [];
     process.stderr.write(`  ${DIM}views${RESET}      ${views.length ? views.map(v => v.name).join(', ') : '(none)'}\n`);
   }
   process.stderr.write('\n');
@@ -711,7 +712,7 @@ async function cmdDoctor(args, cwd) {
     const found = findByName(target, cwd);
     if (!found) throw new Error(`plugin not found: ${target}`);
     const scan = readManifest(found.directory);
-    const composes = scan?.manifest?.spec?.composes || [];
+    const composes = scan?.manifest?.config?.composes || [];
     for (const c of composes) {
       if (!c.package_name) continue;
       const safe = c.package_name.replace(/[/@]/g, '_');

package/src/commands/plugin.mjs

@@ -11,7 +11,6 @@
  */
 
 import * as fs from 'node:fs';
-import * as os from 'node:os';
 import * as path from 'node:path';
 import {
   createLocalWorkspaceSession,
@@ -21,6 +20,7 @@ import {
 } from '../local-service/session-store.mjs';
 import { startLocalWorkspaceService } from '../local-service/server.mjs';
 import { openLocalBrowser } from '../local-service/browser.mjs';
+import { bahulamHome } from '../core/paths.mjs';
 
 const RESET = '\x1b[0m';
 const BOLD = '\x1b[1m';
@@ -33,20 +33,22 @@ const RED = '\x1b[31m';
 /**
  * Standard directories to search for plugins.
  */
-const PLUGIN_SEARCH_DIRS = [
-  path.join(process.cwd(), '.bahulam', 'plugins'),
-  path.join(os.homedir(), '.bahulam', 'plugins'),
-];
+function pluginSearchDirs(cwd = process.cwd()) {
+  return [
+    path.join(cwd, '.bahulam', 'plugins'),
+    path.join(bahulamHome(), 'plugins'),
+  ];
+}
 
 /**
  * Find a plugin directory by name across all standard search paths.
  * Returns the directory path and manifests on success, null on miss.
  */
-function findPluginDir(name) {
+function findPluginDir(name, cwd = process.cwd()) {
   const needle = String(name || '').trim().toLowerCase();
   if (!needle) return null;
 
-  for (const searchDir of PLUGIN_SEARCH_DIRS) {
+  for (const searchDir of pluginSearchDirs(cwd)) {
     try {
       if (!fs.existsSync(searchDir)) continue;
       const entries = fs.readdirSync(searchDir, { withFileTypes: true });
@@ -113,17 +115,18 @@ export async function handlePluginCommand(args, { cwd = process.cwd() } = {}) {
   const targetPath = String(args.targetPath || cwd).trim();
 
   if (!pluginName || args.help) {
-    printPluginUsage();
+    printPluginUsage(cwd);
     process.exit(args.help ? 0 : 1);
   }
 
   // 1. Find the plugin
-  const found = findPluginDir(pluginName);
+  const found = findPluginDir(pluginName, cwd);
   if (!found) {
+    const searchDirs = pluginSearchDirs(cwd);
     process.stderr.write(
       `${RED}✗ Plugin "${pluginName}" not found.${RESET}\n` +
       `  ${DIM}Searched:${RESET}\n` +
-      PLUGIN_SEARCH_DIRS.map(d => `    ${d}`).join('\n') + '\n' +
+      searchDirs.map(d => `    ${d}`).join('\n') + '\n' +
       `  ${DIM}Create a plugin.yaml or plugin.json in one of these directories.${RESET}\n`
     );
     process.exit(1);
@@ -210,7 +213,7 @@ export async function handlePluginCommand(args, { cwd = process.cwd() } = {}) {
   });
 }
 
-function printPluginUsage() {
+function printPluginUsage(cwd = process.cwd()) {
   process.stderr.write(
     `${BOLD}PLUGIN COMMANDS${RESET}\n` +
     `  ${CYAN}bahulam plugin <name> [path]${RESET}                Open a workspace with a plugin loaded\n` +
@@ -238,7 +241,7 @@ function printPluginUsage() {
     `    --force           overwrite existing install\n` +
     `\n` +
     `  ${DIM}Search paths (later overrides earlier):${RESET}\n` +
-    PLUGIN_SEARCH_DIRS.map(d => `    ${d}`).join('\n') + '\n' +
+    pluginSearchDirs(cwd).map(d => `    ${d}`).join('\n') + '\n' +
     `\n` +
     `  ${DIM}Example:${RESET}\n` +
     `    bahulam plugin install https://github.com/community/seo-toolkit\n` +

package/src/core/background-tasks.mjs

@@ -14,11 +14,26 @@ const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
 const KILL_ESCALATION_MS = 5000;
 const MAX_TAIL_BYTES = 64 * 1024;
 
+function trimShellBackgroundOperator(command) {
+  const raw = String(command || '');
+  let i = raw.length - 1;
+  while (i >= 0 && /\s/.test(raw[i])) i -= 1;
+  if (raw[i] !== '&') return raw;
+  if (raw[i - 1] === '&' || raw[i - 1] === '\\') return raw;
+  return raw.slice(0, i).trimEnd();
+}
+
 function stripAnsi(str) {
   // eslint-disable-next-line no-control-regex
   return String(str || '').replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '');
 }
 
+function setChildStdioRef(proc, ref) {
+  for (const stream of [proc?.stdout, proc?.stderr]) {
+    try { stream?.[ref ? 'ref' : 'unref']?.(); } catch { /* best effort */ }
+  }
+}
+
 class BackgroundTasks {
   constructor() {
     this.jobs = new Map();
@@ -35,12 +50,15 @@ class BackgroundTasks {
   start({ command, cwd = process.cwd(), timeoutMs = DEFAULT_TIMEOUT_MS, name = '', on_complete = null }) {
     this._installExitHook();
     const id = `job-${++this._seq}-${Date.now().toString(36)}`;
+    const originalCommand = String(command || '');
+    const managedCommand = trimShellBackgroundOperator(originalCommand);
     const logDir = path.join(cwd, '.bahulam', 'tmp', 'jobs');
     fs.mkdirSync(logDir, { recursive: true });
     const logPath = path.join(logDir, `${id}.log`);
     const logStream = fs.createWriteStream(logPath);
+    try { logStream.unref?.(); } catch { /* best effort */ }
 
-    const proc = spawn('bash', ['-c', command], {
+    const proc = spawn('bash', ['-c', managedCommand], {
       cwd,
       env: { ...process.env },
       stdio: ['ignore', 'pipe', 'pipe'],
@@ -49,8 +67,9 @@ class BackgroundTasks {
 
     const job = {
       id,
-      name: name || command.slice(0, 60),
-      command,
+      name: name || managedCommand.slice(0, 60),
+      command: managedCommand,
+      original_command: originalCommand !== managedCommand ? originalCommand : null,
       cwd,
       pid: proc.pid,
       status: 'running',
@@ -62,6 +81,7 @@ class BackgroundTasks {
       timed_out: false,
       on_complete,
       _proc: proc,
+      _logStream: logStream,
       _done: null,
     };
 
@@ -106,6 +126,7 @@ class BackgroundTasks {
     });
 
     proc.unref();
+    setChildStdioRef(proc, false);
     this.jobs.set(id, job);
     return this.describe(id);
   }
@@ -120,8 +141,12 @@ class BackgroundTasks {
     // process so fast commands still get their close event before Node decides
     // the top-level await is unsettled.
     try { job._proc?.ref?.(); } catch { /* best effort */ }
+    try { job._logStream?.ref?.(); } catch { /* best effort */ }
+    setChildStdioRef(job._proc, true);
     return job._done.finally(() => {
       try { job._proc?.unref?.(); } catch { /* best effort */ }
+      try { job._logStream?.unref?.(); } catch { /* best effort */ }
+      setChildStdioRef(job._proc, false);
     });
   }
 
@@ -132,6 +157,7 @@ class BackgroundTasks {
       id: job.id,
       name: job.name,
       command: job.command,
+      original_command: job.original_command,
       pid: job.pid,
       status: job.status,
       exit_code: job.exit_code,