@bahulam/code 0.1.24 → 0.1.26

package/src/local-service/server.mjs

@@ -288,6 +288,19 @@ async function routeRequest({ req, res, sessionId, token, events, sseClients, em
     return;
   }
 
+  // Vendor asset: Bahulam plugin design system (CSS/JS shared across views).
+  // Served from assets/bahulam-plugin/ so every plugin workspace view can
+  // import a common design language without inlining or server-side packing.
+  if (req.method === 'GET' && url.pathname.startsWith('/vendor/bahulam-plugin/')) {
+    sendPackageAsset({
+      res,
+      root: fileURLToPath(new URL('../../assets/bahulam-plugin/', import.meta.url)),
+      pathname: url.pathname,
+      prefix: '/vendor/bahulam-plugin/',
+    });
+    return;
+  }
+
   if (req.method === 'GET' && url.pathname === '/assets/bahulam-mark.png') {
     sendBrandMark(res);
     return;
@@ -312,6 +325,30 @@ async function routeRequest({ req, res, sessionId, token, events, sseClients, em
     return;
   }
 
+  // Trace export — one JSONL line per tool call with FULL args / output /
+  // error / stack (no eliding). Pass ?turns=1 to also stream user +
+  // assistant messages (as separate lines with role="turn") for
+  // correlation.
+  if (req.method === 'GET' && url.pathname === '/api/trace/export') {
+    const relay = getAgentRelay(session);
+    const includeTurns = url.searchParams.get('turns') === '1' || url.searchParams.get('turns') === 'true';
+    const data = relay.fullTrace({ includeTurns });
+    const filename = `trace-${session.id || 'session'}-${Date.now()}.jsonl`;
+    res.writeHead(200, {
+      'Content-Type': 'application/x-ndjson; charset=utf-8',
+      'Content-Disposition': `attachment; filename="${filename}"`,
+      'Cache-Control': 'no-store',
+    });
+    if (includeTurns) {
+      for (const t of data.turns || []) res.write(JSON.stringify({ role: 'turn', ...t }) + '\n');
+      for (const e of data.trace || []) res.write(JSON.stringify({ role: 'tool', ...e }) + '\n');
+    } else {
+      for (const e of data || []) res.write(JSON.stringify(e) + '\n');
+    }
+    res.end();
+    return;
+  }
+
   if (req.method === 'GET' && url.pathname === '/api/chat/sessions') {
     const relay = getAgentRelay(session);
     const historySessions = await relay.listHistorySessions();

package/src/orchestration/node-runner.mjs

@@ -43,7 +43,8 @@ export async function* runNode(node, agent, instruction, ctx, options = {}) {
 
   const model = node.model || effectiveAgent.model || ctx.defaultModel || null;
   const { apiKey = null, openRouterKey = null } = ctx.credentials || {};
-  if (!apiKey && !openRouterKey) {
+  const useGateway = ctx.modelTransport === 'gateway' && ctx.gatewayToken;
+  if (!useGateway && !apiKey && !openRouterKey) {
     throw new Error(
       `Cannot run node '${node.id}' locally: no model API key. ` +
       'Set ANTHROPIC_API_KEY or OPENROUTER_API_KEY, or log in and use the session substrate.',
@@ -60,8 +61,11 @@ export async function* runNode(node, agent, instruction, ctx, options = {}) {
     .filter(schema => declaredTools.has(schema.name));
 
   const localAgent = new LocalAgent({
-    apiKey,
-    openRouterKey,
+    apiKey: useGateway ? null : apiKey,
+    openRouterKey: useGateway ? null : openRouterKey,
+    gatewayUrl: useGateway ? ctx.gatewayUrl : null,
+    gatewayToken: useGateway ? ctx.gatewayToken : null,
+    sessionId: ctx.sessionId || null,
     model,
     toolExecutor: scopedExecutor,
     cwd: ctx.cwd || process.cwd(),

package/src/plugins/executor.mjs

@@ -8,6 +8,7 @@
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import path from 'path';
 import { makePluginState } from './state.mjs';
+import { normalizeToolResult } from '../core/tool-error.mjs';
 
 /**
  * Load a plugin tool handler by resolving its path relative to the plugin directory.
@@ -105,13 +106,12 @@ export async function createPluginToolExecutor(manifest, opts = {}) {
         get state() { return getState(); },
         pluginName,
       };
+      const traceId = options?._trace_id || null;
       try {
         const result = await entry.handler.call(args || {}, handlerOpts);
-        return result?.success !== false
-          ? { success: true, output: result?.output ?? result, _tool: name, _plugin: pluginName }
-          : { success: false, output: result?.output ?? String(result), _tool: name, _plugin: pluginName };
+        return normalizeToolResult({ tool: name, plugin: pluginName, traceId }, result, null);
       } catch (err) {
-        return { success: false, output: `Plugin tool error (${name}): ${err.message}`, _tool: name, _plugin: pluginName };
+        return normalizeToolResult({ tool: name, plugin: pluginName, traceId }, null, err);
       }
     },
     list: () => [...handlers.keys()],

package/src/plugins/lifecycle.mjs

@@ -0,0 +1,337 @@
+/**
+ * Plugin lifecycle — install / seed / upgrade / uninstall / migrations.
+ *
+ * The manifest declares four optional hook files under `config.lifecycle`:
+ *
+ *   config:
+ *     lifecycle:
+ *       seed:          ./hooks/seed.mjs
+ *       post_install:  ./hooks/post-install.mjs
+ *       pre_uninstall: ./hooks/pre-uninstall.mjs
+ *       migrations:
+ *         - { version: "0.3.0", sql: ./migrations/0.3.0.sql }
+ *         - { version: "0.4.0", run: ./migrations/0.4.0.mjs }
+ *
+ * All hooks receive one argument, a context object:
+ *
+ *   ctx = {
+ *     pluginDir,    // absolute path to the installed plugin folder
+ *     dataDir,      // ~/.bahulam/data/<name>
+ *     state,        // per-plugin state handle (lazy getter — same shape as tool handlers see)
+ *     args,         // CLI/programmatic invocation args (installer passes flags etc.)
+ *     log(level, msg, meta?),  // structured log — routed to stdout + a per-plugin lifecycle log
+ *     ranBefore(key),          // hook idempotency helper — returns true if the given key was recorded
+ *     recordRun(key, extra?),  // mark a hook / migration as run
+ *   }
+ *
+ * Hook contract:
+ *   export async function run(ctx) { ... }
+ *
+ *   May return { keepData?: bool, warnings?: string[] } — pre_uninstall
+ *   uses this to influence the caller's data-cleanup default.
+ *
+ * Migration entry:
+ *   { version: "0.3.0", sql?: "./migrations/0.3.0.sql", run?: "./migrations/0.3.0.mjs" }
+ *
+ *   Exactly one of `sql` or `run` must be present. SQL files execute via
+ *   the plugin state DB's `exec`. JS modules export `run(ctx)`; the ctx
+ *   is the same shape as hook ctx (but `args` is null).
+ *
+ * State bookkeeping is stored in a JSON file at
+ * `<dataDir>/_bahulam_lifecycle.json`:
+ *
+ *   {
+ *     installed_at: "2026-09-17T...",
+ *     installed_version: "0.3.0",
+ *     last_upgrade_at: null,
+ *     applied_migrations: ["0.3.0"],
+ *     runs: { seed: {at: "...", version: "0.3.0"}, post_install: {...} }
+ *   }
+ *
+ * The migration path is snapshot-then-roll-forward: before a batch of
+ * migrations runs, the SQLite file is copied to
+ * `<dataDir>/state.db.pre-<from>-to-<to>` and restored on failure.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { pathToFileURL } from 'node:url';
+
+const DATA_ROOT = () => path.join(os.homedir(), '.bahulam', 'data');
+const PLUGIN_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+
+function pluginDataDir(pluginName) {
+  if (!PLUGIN_NAME_RE.test(pluginName)) throw new Error(`invalid plugin name for lifecycle: ${pluginName}`);
+  const dir = path.join(DATA_ROOT(), pluginName);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+function lifecyclePath(dataDir) {
+  return path.join(dataDir, '_bahulam_lifecycle.json');
+}
+
+function readLifecycle(dataDir) {
+  const p = lifecyclePath(dataDir);
+  if (!fs.existsSync(p)) return { runs: {}, applied_migrations: [] };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(p, 'utf-8'));
+    return { runs: {}, applied_migrations: [], ...parsed };
+  } catch { return { runs: {}, applied_migrations: [] }; }
+}
+
+function writeLifecycle(dataDir, record) {
+  fs.writeFileSync(lifecyclePath(dataDir), JSON.stringify(record, null, 2), 'utf-8');
+}
+
+function nowIso() { return new Date().toISOString(); }
+
+function resolveHookPath(pluginDir, ref) {
+  if (!ref) return null;
+  // Ref is a POSIX relative path from the manifest — `./hooks/seed.mjs`
+  const abs = path.resolve(pluginDir, ref);
+  if (!fs.existsSync(abs)) throw new Error(`lifecycle hook not found: ${ref} (looked at ${abs})`);
+  return abs;
+}
+
+/**
+ * Load a hook module and return its `run` function. Cache-busted per
+ * call so an operator can edit a hook and re-run install/upgrade
+ * without a fresh Node process.
+ */
+async function loadHookRun(pluginDir, ref, label) {
+  const abs = resolveHookPath(pluginDir, ref);
+  if (!abs) return null;
+  const url = `${pathToFileURL(abs).href}?t=${Date.now()}`;
+  const mod = await import(url);
+  if (typeof mod.run !== 'function') {
+    throw new Error(`lifecycle ${label} hook ${ref} must export a run(ctx) function`);
+  }
+  return mod.run;
+}
+
+/**
+ * Build a hook context. `stateFactory` is a thunk so hooks that never
+ * touch state don't open the SQLite handle.
+ */
+function makeCtx({ pluginDir, dataDir, args, record, logger, stateFactory }) {
+  const runs = record.runs || {};
+  const applied = new Set(record.applied_migrations || []);
+  return {
+    pluginDir,
+    dataDir,
+    args: args || null,
+    get state() { return stateFactory ? stateFactory() : null; },
+    log: (level, msg, meta) => logger(level, msg, meta),
+    ranBefore(key) {
+      if (String(key).startsWith('migration:')) return applied.has(String(key).slice('migration:'.length));
+      return Boolean(runs[key]);
+    },
+    recordRun(key, extra) {
+      if (String(key).startsWith('migration:')) {
+        applied.add(String(key).slice('migration:'.length));
+        record.applied_migrations = [...applied];
+      } else {
+        record.runs = record.runs || {};
+        record.runs[key] = { at: nowIso(), ...(extra || {}) };
+      }
+      writeLifecycle(dataDir, record);
+    },
+  };
+}
+
+function makeLogger(pluginName, dataDir) {
+  const logPath = path.join(dataDir, '_bahulam_lifecycle.log');
+  const quiet = process.env.BAHULAM_LIFECYCLE_QUIET === '1';
+  return (level, msg, meta) => {
+    const line = `${nowIso()} [${level}] ${pluginName}: ${msg}${meta ? ' ' + JSON.stringify(meta) : ''}\n`;
+    try { fs.appendFileSync(logPath, line); } catch { /* best-effort */ }
+    if (quiet) return;
+    const target = level === 'error' || level === 'warn' ? process.stderr : process.stdout;
+    try { target.write(line); } catch { /* best-effort */ }
+  };
+}
+
+/**
+ * Public API — runSeed / runPostInstall / runPreUninstall / runMigrations.
+ *
+ * All calls are idempotent: calling runSeed twice will not re-run the
+ * seed unless the caller passes { force: true }. Post-install always
+ * runs on install (both fresh + --force) and on update.
+ */
+
+export async function runSeed({ pluginName, pluginDir, manifest, args = {}, stateFactory = null } = {}) {
+  const ref = manifest?.config?.lifecycle?.seed;
+  if (!ref) return { ran: false, reason: 'no seed hook declared' };
+  const dataDir = pluginDataDir(pluginName);
+  const record = readLifecycle(dataDir);
+  const logger = makeLogger(pluginName, dataDir);
+  const version = manifest?.metadata?.version || 'unversioned';
+  if (record.runs?.seed && !args.force) {
+    logger('info', 'seed already ran; skipping (pass --force or --reseed to re-run)');
+    return { ran: false, reason: 'already ran', prior: record.runs.seed };
+  }
+  const runFn = await loadHookRun(pluginDir, ref, 'seed');
+  const ctx = makeCtx({ pluginDir, dataDir, args, record, logger, stateFactory });
+  const started = Date.now();
+  try {
+    const result = await runFn(ctx);
+    ctx.recordRun('seed', { version, duration_ms: Date.now() - started });
+    logger('info', 'seed completed', { duration_ms: Date.now() - started });
+    return { ran: true, duration_ms: Date.now() - started, result };
+  } catch (err) {
+    logger('error', 'seed failed', { message: err.message });
+    throw err;
+  }
+}
+
+export async function runPostInstall({ pluginName, pluginDir, manifest, args = {}, stateFactory = null } = {}) {
+  const ref = manifest?.config?.lifecycle?.post_install;
+  if (!ref) return { ran: false, reason: 'no post_install hook declared' };
+  const dataDir = pluginDataDir(pluginName);
+  const record = readLifecycle(dataDir);
+  const logger = makeLogger(pluginName, dataDir);
+  const runFn = await loadHookRun(pluginDir, ref, 'post_install');
+  const ctx = makeCtx({ pluginDir, dataDir, args, record, logger, stateFactory });
+  const started = Date.now();
+  try {
+    const result = await runFn(ctx);
+    ctx.recordRun('post_install', { version: manifest?.metadata?.version, duration_ms: Date.now() - started });
+    // Also stamp installed_at / installed_version on first install
+    if (!record.installed_at) {
+      record.installed_at = nowIso();
+      record.installed_version = manifest?.metadata?.version || null;
+      writeLifecycle(dataDir, record);
+    }
+    logger('info', 'post_install completed', { duration_ms: Date.now() - started });
+    return { ran: true, duration_ms: Date.now() - started, result };
+  } catch (err) {
+    logger('error', 'post_install failed', { message: err.message });
+    throw err;
+  }
+}
+
+/**
+ * pre_uninstall may return { keepData?: bool, warnings?: [] } which
+ * uninstall commands use as the default for the data-cleanup decision.
+ */
+export async function runPreUninstall({ pluginName, pluginDir, manifest, args = {}, stateFactory = null } = {}) {
+  const ref = manifest?.config?.lifecycle?.pre_uninstall;
+  if (!ref) return { ran: false, reason: 'no pre_uninstall hook declared', result: {} };
+  const dataDir = pluginDataDir(pluginName);
+  const record = readLifecycle(dataDir);
+  const logger = makeLogger(pluginName, dataDir);
+  const runFn = await loadHookRun(pluginDir, ref, 'pre_uninstall');
+  const ctx = makeCtx({ pluginDir, dataDir, args, record, logger, stateFactory });
+  try {
+    const result = await runFn(ctx);
+    logger('info', 'pre_uninstall completed');
+    return { ran: true, result: result || {} };
+  } catch (err) {
+    logger('error', 'pre_uninstall failed', { message: err.message });
+    throw err;
+  }
+}
+
+/**
+ * Purge the data dir. Called by uninstall when --purge or interactive
+ * y-answer wins.
+ */
+export function purgeData(pluginName) {
+  const dir = path.join(DATA_ROOT(), pluginName);
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+    return { purged: true, dir };
+  }
+  return { purged: false, dir };
+}
+
+/**
+ * Apply pending migrations sequentially, snapshotting the state DB
+ * beforehand and restoring on failure.
+ */
+export async function runMigrations({ pluginName, pluginDir, manifest, stateFactory = null } = {}) {
+  const list = Array.isArray(manifest?.config?.lifecycle?.migrations) ? manifest.config.lifecycle.migrations : [];
+  if (!list.length) return { ran: 0, skipped: 0, applied: [] };
+
+  const dataDir = pluginDataDir(pluginName);
+  const record = readLifecycle(dataDir);
+  const logger = makeLogger(pluginName, dataDir);
+  const applied = new Set(record.applied_migrations || []);
+
+  const pending = list.filter(m => !applied.has(m.version));
+  if (!pending.length) {
+    logger('info', `migrations up-to-date (${applied.size} applied)`);
+    return { ran: 0, skipped: list.length, applied: [] };
+  }
+
+  // Snapshot the DB file first — restore on any failure.
+  const dbPath = path.join(dataDir, 'state.db');
+  const snapPath = fs.existsSync(dbPath)
+    ? path.join(dataDir, `state.db.pre-${pending[0].version}-${nowIso().replace(/[:.]/g, '-')}`)
+    : null;
+  if (snapPath) {
+    fs.copyFileSync(dbPath, snapPath);
+    logger('info', `migration snapshot: ${path.basename(snapPath)}`);
+  }
+
+  const ranNow = [];
+  try {
+    for (const m of pending) {
+      if (!m.version) throw new Error('migration entry missing version');
+      if (!m.sql && !m.run) throw new Error(`migration ${m.version} needs one of sql/run`);
+      if (m.sql && m.run) throw new Error(`migration ${m.version}: only one of sql/run allowed`);
+      logger('info', `applying migration ${m.version}`);
+      const started = Date.now();
+      if (m.sql) {
+        const abs = resolveHookPath(pluginDir, m.sql);
+        const sqlText = fs.readFileSync(abs, 'utf-8');
+        const state = stateFactory ? stateFactory() : null;
+        if (!state) throw new Error(`migration ${m.version}: SQL migration requires a state handle`);
+        state.exec ? state.exec(sqlText) : execViaQuery(state, sqlText);
+      } else {
+        const runFn = await loadHookRun(pluginDir, m.run, `migration:${m.version}`);
+        const ctx = makeCtx({ pluginDir, dataDir, args: null, record, logger, stateFactory });
+        await runFn(ctx);
+      }
+      applied.add(m.version);
+      record.applied_migrations = [...applied];
+      writeLifecycle(dataDir, record);
+      ranNow.push({ version: m.version, duration_ms: Date.now() - started });
+      logger('info', `migration ${m.version} applied`, { duration_ms: Date.now() - started });
+    }
+    return { ran: ranNow.length, skipped: list.length - pending.length, applied: ranNow };
+  } catch (err) {
+    logger('error', `migration failed — restoring snapshot`, { message: err.message });
+    if (snapPath && fs.existsSync(snapPath)) {
+      // Best-effort restore. If the failure was mid-write, the WAL may
+      // linger; wiping it is safer than leaving inconsistent frames.
+      try { fs.copyFileSync(snapPath, dbPath); } catch { /* fall through */ }
+      for (const ext of ['-wal', '-shm']) {
+        const aux = dbPath + ext;
+        if (fs.existsSync(aux)) { try { fs.rmSync(aux); } catch { /* ok */ } }
+      }
+      // Restore lifecycle record to pre-migration state
+      const preRecord = readLifecycle(dataDir);
+      preRecord.applied_migrations = [...(preRecord.applied_migrations || [])].filter(v => !ranNow.some(r => r.version === v));
+      writeLifecycle(dataDir, preRecord);
+      logger('warn', 'snapshot restored — plugin is at the pre-migration schema. Fix and re-run install/update.');
+    }
+    err.migration_context = { attempted: ranNow.map(r => r.version), failed_on: pending[ranNow.length]?.version };
+    throw err;
+  }
+}
+
+// Fallback exec for JSON-backed state (no exec method, only query).
+function execViaQuery(state, sqlText) {
+  const stmts = sqlText.split(/;\s*$/m).map(s => s.trim()).filter(Boolean);
+  for (const s of stmts) {
+    if (typeof state.query === 'function') state.query(s);
+    else throw new Error('cannot execute raw SQL against the JSON-backed state fallback');
+  }
+}
+
+export function readLifecycleRecord(pluginName) {
+  return readLifecycle(pluginDataDir(pluginName));
+}

package/src/plugins/manifest.mjs

@@ -172,6 +172,42 @@ const SAFE_IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
 // manifest degrades into a working table instead of a failed CREATE.
 const SQL_TYPES = new Set(['INTEGER', 'TEXT', 'REAL', 'BLOB', 'NUMERIC']);
 
+/**
+ * Normalize `config.lifecycle` — install / seed / uninstall / migration hooks.
+ * Returns null when the section is absent so callers can distinguish
+ * "no lifecycle declared" from "empty lifecycle".
+ *
+ * Shape:
+ *   {
+ *     seed:          "./hooks/seed.mjs"       | null,
+ *     post_install:  "./hooks/post-install.mjs" | null,
+ *     pre_uninstall: "./hooks/pre-uninstall.mjs" | null,
+ *     migrations: [
+ *       { version: "0.3.0", sql: "./migrations/0.3.0.sql" },
+ *       { version: "0.4.0", run: "./migrations/0.4.0.mjs" },
+ *     ],
+ *   }
+ */
+function normalizeLifecycle(value) {
+  if (!value || typeof value !== 'object') return null;
+  const out = {
+    seed:          typeof value.seed === 'string'          ? value.seed          : null,
+    post_install:  typeof value.post_install === 'string'  ? value.post_install  : null,
+    pre_uninstall: typeof value.pre_uninstall === 'string' ? value.pre_uninstall : null,
+    migrations: [],
+  };
+  if (Array.isArray(value.migrations)) {
+    for (const m of value.migrations) {
+      if (!m || typeof m !== 'object' || !m.version) continue;
+      const entry = { version: String(m.version) };
+      if (typeof m.sql === 'string') entry.sql = m.sql;
+      if (typeof m.run === 'string') entry.run = m.run;
+      out.migrations.push(entry);
+    }
+  }
+  return out;
+}
+
 function normalizeSqlType(value) {
   const raw = String(value || '').trim().toUpperCase();
   if (!raw) return 'TEXT';
@@ -520,6 +556,7 @@ export function normalizeManifest(raw, source = '') {
       mcpServers,
       composes,
       state,
+      ...(normalizeLifecycle(config.lifecycle) ? { lifecycle: normalizeLifecycle(config.lifecycle) } : {}),
     },
     source,
     _dir: source ? path.dirname(source) : '',

package/src/plugins/pi-compat/requirements.mjs

@@ -26,20 +26,22 @@ export const REQUIREMENTS_FILE = '.bahulam-requirements.json';
 // Known binary → install hint DB. Extend as we learn new pi packages.
 // Keep it small and honest: unknown binaries just report the name.
 const INSTALL_HINTS = {
-  ffmpeg:      { darwin: 'brew install ffmpeg',         linux: 'apt install -y ffmpeg' },
-  ffprobe:     { darwin: 'brew install ffmpeg',         linux: 'apt install -y ffmpeg' },
-  imagemagick: { darwin: 'brew install imagemagick',    linux: 'apt install -y imagemagick' },
-  convert:     { darwin: 'brew install imagemagick',    linux: 'apt install -y imagemagick' },
-  magick:      { darwin: 'brew install imagemagick',    linux: 'apt install -y imagemagick' },
-  docker:      { darwin: 'brew install --cask docker',  linux: 'https://docs.docker.com/engine/install/' },
-  git:         { darwin: 'brew install git',            linux: 'apt install -y git' },
-  python:      { darwin: 'brew install python',         linux: 'apt install -y python3' },
-  python3:     { darwin: 'brew install python',         linux: 'apt install -y python3' },
-  node:        { darwin: 'brew install node',           linux: 'apt install -y nodejs' },
-  yt_dlp:      { darwin: 'brew install yt-dlp',         linux: 'pip install yt-dlp' },
-  'yt-dlp':    { darwin: 'brew install yt-dlp',         linux: 'pip install yt-dlp' },
-  pandoc:      { darwin: 'brew install pandoc',         linux: 'apt install -y pandoc' },
-  tesseract:   { darwin: 'brew install tesseract',      linux: 'apt install -y tesseract-ocr' },
+  ffmpeg:      { darwin: 'brew install ffmpeg',         linux: 'apt install -y ffmpeg',              win32: 'choco install ffmpeg' },
+  ffprobe:     { darwin: 'brew install ffmpeg',         linux: 'apt install -y ffmpeg',              win32: 'choco install ffmpeg' },
+  imagemagick: { darwin: 'brew install imagemagick',    linux: 'apt install -y imagemagick',         win32: 'choco install imagemagick' },
+  convert:     { darwin: 'brew install imagemagick',    linux: 'apt install -y imagemagick',         win32: 'choco install imagemagick' },
+  magick:      { darwin: 'brew install imagemagick',    linux: 'apt install -y imagemagick',         win32: 'choco install imagemagick' },
+  docker:      { darwin: 'brew install --cask docker',  linux: 'https://docs.docker.com/engine/install/', win32: 'choco install docker-desktop' },
+  git:         { darwin: 'brew install git',            linux: 'apt install -y git',                 win32: 'choco install git' },
+  python:      { darwin: 'brew install python',         linux: 'apt install -y python3',             win32: 'choco install python' },
+  python3:     { darwin: 'brew install python',         linux: 'apt install -y python3',             win32: 'choco install python' },
+  node:        { darwin: 'brew install node',           linux: 'apt install -y nodejs',              win32: 'choco install nodejs-lts' },
+  yt_dlp:      { darwin: 'brew install yt-dlp',         linux: 'pip install yt-dlp',                 win32: 'choco install yt-dlp' },
+  'yt-dlp':    { darwin: 'brew install yt-dlp',         linux: 'pip install yt-dlp',                 win32: 'choco install yt-dlp' },
+  pandoc:      { darwin: 'brew install pandoc',         linux: 'apt install -y pandoc',              win32: 'choco install pandoc' },
+  pdflatex:    { darwin: 'brew install --cask basictex', linux: 'apt install -y texlive-latex-recommended', win32: 'choco install miktex' },
+  xelatex:     { darwin: 'brew install --cask mactex-no-gui', linux: 'apt install -y texlive-xetex', win32: 'choco install miktex' },
+  tesseract:   { darwin: 'brew install tesseract',      linux: 'apt install -y tesseract-ocr',       win32: 'choco install tesseract' },
 };
 
 // Shell keywords that mean "the arg after me is the binary" when
@@ -462,11 +464,22 @@ export function formatRequirementsReport(reqs, { verbose = false } = {}) {
   if (!reqs) return lines;
 
   if (reqs.system_binaries?.length) {
-    lines.push({ level: 'warn', text: `system binaries required: ${reqs.system_binaries.map(b => b.name).join(', ')}` });
+    const platformKey = process.platform === 'win32' ? 'win32'
+      : process.platform === 'darwin' ? 'darwin'
+      : 'linux';
+    const required = reqs.system_binaries.filter(b => b.optional !== true);
+    const optional = reqs.system_binaries.filter(b => b.optional === true);
+    if (required.length) {
+      lines.push({ level: 'warn', text: `system binaries required: ${required.map(b => b.name).join(', ')}` });
+    }
+    if (optional.length) {
+      lines.push({ level: 'info', text: `system binaries optional: ${optional.map(b => b.name).join(', ')}` });
+    }
     if (verbose) {
       for (const b of reqs.system_binaries) {
-        const hint = b.install_hints?.darwin || b.install_hints?.linux;
-        lines.push({ level: 'info', text: `   ${b.name}${hint ? ` — install: ${hint}` : ''}` });
+        const hint = b.install_hints?.[platformKey] || b.install_hints?.darwin || b.install_hints?.linux;
+        const tag = b.optional === true ? ' (optional)' : '';
+        lines.push({ level: 'info', text: `   ${b.name}${tag}${hint ? ` — install: ${hint}` : ''}` });
       }
     }
   }

package/src/plugins/preflight.mjs

@@ -249,6 +249,43 @@ export async function preflightPlugin(pluginDir, opts = {}) {
     else if (!/\.(html?|htm)$/i.test(source)) warnings.push(`View "${label}": source should be an .html file`);
   }
 
+  // 6b. Lifecycle hooks + migrations
+  const lifecycle = manifest.config?.lifecycle || null;
+  if (lifecycle) {
+    const checkHook = (ref, label) => {
+      if (!ref) return;
+      const abs = path.resolve(pluginDir, ref);
+      const inside = abs === pluginDir || abs.startsWith(pluginDir + path.sep);
+      if (!inside) errors.push(`Lifecycle ${label}: path escapes the plugin directory: ${ref}`);
+      else if (!fs.existsSync(abs)) errors.push(`Lifecycle ${label} hook not found: ${ref}`);
+      else if (!fs.statSync(abs).isFile()) errors.push(`Lifecycle ${label} hook is not a file: ${ref}`);
+      else if (!/\.(mjs|js|cjs)$/.test(ref)) warnings.push(`Lifecycle ${label} hook should be .mjs/.js/.cjs: ${ref}`);
+    };
+    checkHook(lifecycle.seed, 'seed');
+    checkHook(lifecycle.post_install, 'post_install');
+    checkHook(lifecycle.pre_uninstall, 'pre_uninstall');
+
+    const seenVersions = new Set();
+    for (const [i, m] of (lifecycle.migrations || []).entries()) {
+      const tag = `migration #${i + 1}${m.version ? ` (${m.version})` : ''}`;
+      if (!m.version) { errors.push(`${tag}: missing version`); continue; }
+      if (!/^[0-9]+\.[0-9]+\.[0-9]+(?:[-+][\w.-]+)?$/.test(m.version)) {
+        warnings.push(`${tag}: version "${m.version}" is not semver — sort order may be unpredictable`);
+      }
+      if (seenVersions.has(m.version)) errors.push(`${tag}: duplicate version`);
+      seenVersions.add(m.version);
+      if (!m.sql && !m.run) errors.push(`${tag}: needs one of sql or run`);
+      if (m.sql && m.run) errors.push(`${tag}: only one of sql or run allowed`);
+      const target = m.sql || m.run;
+      if (target) {
+        const abs = path.resolve(pluginDir, target);
+        const inside = abs === pluginDir || abs.startsWith(pluginDir + path.sep);
+        if (!inside) errors.push(`${tag}: path escapes the plugin directory: ${target}`);
+        else if (!fs.existsSync(abs)) errors.push(`${tag}: file not found: ${target}`);
+      }
+    }
+  }
+
   // 7. Install collision
   const existing = new Set(
     Array.from(opts.existingPluginNames?.() || [])

package/src/terminal/main.mjs

@@ -57,6 +57,10 @@ function parsePluginArgs(argv) {
       case '--global': parsed.global = true; break;
       case '--force': case '-f': parsed.force = true; break;
       case '--ref': case '--tag': case '--branch': parsed.ref = argv[++i]; break;
+      case '--purge': parsed.purge = true; break;
+      case '--keep-data': parsed.keep_data = true; break;
+      case '--no-seed': parsed.no_seed = true; break;
+      case '--reseed': parsed.reseed = true; break;
       default:
         if (!arg.startsWith('-')) positional.push(arg);
         break;
@@ -336,6 +340,10 @@ async function main() {
     bahulam --agent <slug> -p "x"  Run a named agent (local deterministic graph)
     bahulam --workflow <name> -p   Run a named workflow (local deterministic graph)
     bahulam --headless -p "x"      Non-interactive: auto-approve, JSONL output
+    bahulam --remote -p "x"        Remote backend /api/execute orchestration
+    bahulam --bundled -p "x"       Local bundled backend-style orchestration
+    bahulam --local -p "x"         Local npm orchestration via Bahulam Gateway
+    bahulam --direct -p "x"         Local npm orchestration via provider API
     bahulam --headless -p "x" --vision screenshot.png
                               Attach an image via the vision analysis pipeline
     bahulam --resume               Resume last conversation
@@ -525,7 +533,7 @@ async function main() {
   const effectivePrompt = args.prompt || (daemonSpawned && daemonPrompt) || '';
   const hasGraphTarget = Boolean(args.agent || args.workflow);
   if ((effectivePrompt || hasGraphTarget)
-      && (daemonSpawned || process.argv.includes('--headless') || !process.stdin.isTTY || hasGraphTarget)) {
+      && (daemonSpawned || process.argv.includes('--headless') || args.runtimeMode || !process.stdin.isTTY || hasGraphTarget)) {
     const { runHeadless } = await import('../core/headless.mjs');
     await runHeadless({
       instruction: effectivePrompt,
@@ -534,6 +542,7 @@ async function main() {
       verbose: args.verbose,
       cacheReport: args.cacheReport,
       local: args.local,
+      mode: args.runtimeMode || (args.local ? 'local' : 'remote'),
       vision: args.vision,
       agent: args.agent,
       workflow: args.workflow,