total-recall-brain 3.40.7 → 3.41.0

package/src/core/daemon-control.mjs

@@ -5,7 +5,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { logger } from './logger.mjs';
 import { agentDir, brainDir } from './config.mjs';
-import { readProcessCommand } from './pid-lock.mjs';
+import { observeDaemon } from './startup-health.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.join(__dirname, '..', '..');
@@ -22,46 +22,19 @@ const LOG_FILE = path.join(brainDir, 'logs', 'daemon.log');
  * @returns {number|null} The active PID, or null if not running/invalid.
  */
 export function readPid() {
-  try {
-    if (!fs.existsSync(PID_FILE)) return null;
-    const pid = parseInt(fs.readFileSync(PID_FILE, 'utf8').trim(), 10);
-    if (isNaN(pid) || pid <= 0) return null;
-    
-    // Check if the process is alive using signal 0
-    try {
-      process.kill(pid, 0);
-      const command=readProcessCommand(pid);
-      if(!command)throw new Error('Cannot verify daemon process identity');
-      if(!command.includes(path.join('core','daemon-loop.mjs')) && !command.includes(path.join('core','dream.mjs')))return null;
-      return pid;
-    } catch {
-      return null;
-    }
-  } catch {
-    return null;
-  }
+  const observation = getDaemonObservation();
+  return observation.status === 'running' ? observation.pid : null;
 }
 
+export function getDaemonObservation() { return observeDaemon(brainDir); }
+
 /**
  * Returns the status of the daemon process.
- * @returns {'running'|'dead'|'not_started'}
+ * @returns {'running'|'dead'|'not_started'|'conflict'|'unknown'}
  */
 export function getDaemonStatus() {
-  try {
-    const pid = readPid();
-    if (pid) {
-      return 'running';
-    }
-    
-    // If process is not running but PID file exists, it's considered dead
-    if (fs.existsSync(PID_FILE)) {
-      return 'dead';
-    }
-    
-    return 'not_started';
-  } catch {
-    return 'not_started';
-  }
+  const { status } = getDaemonObservation();
+  return status === 'not-started' ? 'not_started' : status === 'stopped' ? 'dead' : status;
 }
 
 /**
@@ -69,7 +42,11 @@ export function getDaemonStatus() {
  * @returns {number} The PID of the newly spawned daemon.
  */
 export function startDaemon() {
-  const existingPid = readPid();
+  const observation = getDaemonObservation();
+  if (['conflict', 'unknown'].includes(observation.status)) {
+    throw new Error(`Daemon start refused: ${observation.reason || observation.status}; expected ${observation.expected_entry}${observation.entry ? `, observed ${observation.entry}` : ''}`);
+  }
+  const existingPid = observation.status === 'running' ? observation.pid : null;
   if (existingPid) {
     logger.warn('daemon-control', `Daemon already running under PID ${existingPid}.`);
     return existingPid;
@@ -77,13 +54,7 @@ export function startDaemon() {
 
   const dreamScript = path.join(ROOT, 'src', 'core', 'daemon-loop.mjs');
   if (!fs.existsSync(dreamScript)) {
-    // Fallback to dream.mjs for backward compatibility
-    const fallback = path.join(ROOT, 'src', 'core', 'dream.mjs');
-    if (fs.existsSync(fallback)) {
-      logger.warn('daemon-control', 'daemon-loop.mjs not found, falling back to dream.mjs');
-    } else {
-      throw new Error(`Daemon script not found at ${dreamScript}`);
-    }
+    throw new Error(`Daemon script not found at ${dreamScript}`);
   }
 
   const logsDir = path.dirname(LOG_FILE);

package/src/core/fast-recall.mjs

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import matter from './frontmatter.mjs';
-import { atomicWrite, isSafeVaultName } from './vault.mjs';
+import { atomicWrite, isSafeVaultName } from './vault-files.mjs';
 
 const caches = new Map();
 const words = text => [...new Set(String(text).toLowerCase().match(/[\p{L}\p{N}_-]+/gu) || [])];

package/src/core/memory-brain.mjs

@@ -2,6 +2,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { writeFileSecure } from './secure-file.mjs';
+import { ensureProjectId } from './project-id.mjs';
 
 function ensureDir(dir) { fs.mkdirSync(dir, { recursive: true }); }
 
@@ -58,6 +59,7 @@ export function registerProjectBrain(globalBrainDir, entry) {
     name: entry.name,
     path: abs,
     brainDir: entry.brainDir,
+    project_id: ensureProjectId(entry.brainDir).project_id,
     full_brain: true,
     layer: 'project',
     tags: entry.tags || ['project-brain'],

package/src/core/plugin-activation.mjs

@@ -1,15 +1,47 @@
 /** Host activation policy; never pretends a provider or external daemon is healthy. */
 import { getPlugin } from './plugin-loader.mjs';
-import { patchPluginRecord, emit, vaultFor, recompileAfterPluginMutation } from './plugin-store.mjs';
+import { patchPluginRecord, patchProjectActivationRecord, emit, vaultFor, recompileAfterPluginMutation } from './plugin-store.mjs';
 import { pluginActivation } from './plugin-state.mjs';
 export { pluginActivation };
 
-export async function setPluginActive(id, enabled, { projectRoot = process.cwd() } = {}) {
+/**
+ * Switch one plugin on or off.
+ *
+ * A plugin installed in one repository alone (a project copy) carries its own
+ * setting. A plugin in the shared folder is switched for the whole machine
+ * (`scope: 'shared'`), for the current repository alone (the default), or back to
+ * following the shared setting (`clear: true`).
+ */
+export async function setPluginActive(id, enabled, { projectRoot = process.cwd(), scope = 'project', clear = false } = {}) {
+  if (clear === true) {
+    const plugin = getPlugin(id, projectRoot);
+    if (!plugin?.valid) throw new Error(`Plugin ${id} is missing or invalid`);
+    await patchProjectActivationRecord(id, projectRoot, null);
+    await emit(vaultFor(plugin), id, 'activation-cleared', { projectRoot });
+    const compilation = await recompileAfterPluginMutation(projectRoot, false);
+    return { pluginId: id, activation: pluginActivation(plugin, { projectRoot }), scope: 'shared', compilation };
+  }
   if (typeof enabled !== 'boolean') throw new Error('Plugin activation requires a boolean');
   const plugin = getPlugin(id, projectRoot);
   if (!plugin?.valid) throw new Error(`Plugin ${id} is missing or invalid`);
-  await patchPluginRecord(plugin, { runtime_enabled: enabled });
-  await emit(vaultFor(plugin), id, enabled ? 'activated' : 'deactivated', { enabled });
-  const compilation = await recompileAfterPluginMutation(projectRoot, plugin.scope === 'global' || plugin.scope === 'scaffold');
-  return { pluginId: id, activation: pluginActivation(plugin), compilation };
+  if (scope === 'shared') {
+    if (plugin.scope !== 'global') throw new Error(`Plugin ${id} is a ${plugin.scope} copy without a shared setting to change`);
+    await patchPluginRecord(plugin, { runtime_enabled: enabled });
+    await emit(vaultFor(plugin), id, enabled ? 'activated' : 'deactivated', { enabled, scope: 'shared' });
+    const compilation = await recompileAfterPluginMutation(projectRoot, true);
+    return { pluginId: id, activation: pluginActivation(plugin, { projectRoot }), scope: 'shared', compilation };
+  }
+  // Repository scope. A repository-owned copy already is that repository's setting.
+  if (plugin.scope !== 'global') {
+    await patchPluginRecord(plugin, { runtime_enabled: enabled });
+    await emit(vaultFor(plugin), id, enabled ? 'activated' : 'deactivated', { enabled, scope: plugin.scope });
+    // A project copy compiles the project's own surface and catalog. Only the
+    // shared (scaffold) layer also rebuilds every registered project.
+    const compilation = await recompileAfterPluginMutation(projectRoot, plugin.scope === 'scaffold');
+    return { pluginId: id, activation: pluginActivation(plugin, { projectRoot }), scope: plugin.scope, compilation };
+  }
+  await patchProjectActivationRecord(id, projectRoot, enabled, { manifest: plugin.manifest });
+  await emit(vaultFor(plugin), id, enabled ? 'activated' : 'deactivated', { enabled, projectRoot, scope: 'project' });
+  const compilation = await recompileAfterPluginMutation(projectRoot, false);
+  return { pluginId: id, activation: pluginActivation(plugin, { projectRoot }), scope: 'project', compilation };
 }

package/src/core/plugin-bundle.mjs

@@ -49,6 +49,60 @@ export function listPluginFiles(pluginDir) {
   return out;
 }
 
+const BRICK_ROOT_FILES = /^LICENSE[^/]*$/i;
+
+/**
+ * Files a plugin distributes to one audience.
+ *
+ * `host` is every file, for a mesh peer or a Total Recall installation.
+ * `brick` is the host-free capability only: the directory holding
+ * `capability.entry`, plus LICENSE. package.json is regenerated with only its
+ * runtime fields, and the README is left behind because it documents the host. The UI, the CLI
+ * handler and the host manifest never leave with a brick, so a vendored copy
+ * has no UI and no path back to Total Recall. Its plugin.json and package.json
+ * are reduced copies, returned as `data` rather than read from disk.
+ * @returns {Array<{ path: string, abs: string, size: number, mode: number, data?: Buffer }>}
+ */
+export function pluginBundleFiles(pluginDir, { audience = 'host' } = {}) {
+  const files = listPluginFiles(pluginDir);
+  if (audience === 'host') return files;
+  if (audience !== 'brick') throw new Error(`Unknown bundle audience '${audience}'`);
+  const root = fs.realpathSync(pluginDir);
+  const manifest = JSON.parse(fs.readFileSync(path.join(root, 'plugin.json'), 'utf8'));
+  const entry = manifest.capability?.entry;
+  if (typeof entry !== 'string') throw new Error(`Plugin '${manifest.id}' declares no capability.entry, so it cannot be vendored as a brick`);
+  const capDir = path.posix.dirname(entry);
+  const inCap = (p) => (capDir === '.' ? p === entry : p.startsWith(`${capDir}/`));
+  const kept = files.filter((f) => f.path.split('/')[0] !== 'ui' && (inCap(f.path) || BRICK_ROOT_FILES.test(f.path)));
+  if (!kept.some((f) => f.path === entry)) throw new Error(`capability.entry '${entry}' does not exist in plugin '${manifest.id}'`);
+  const reduced = Buffer.from(`${JSON.stringify({
+    id: manifest.id, name: manifest.name, version: manifest.version, description: manifest.description,
+    brick: true, capability: manifest.capability,
+    ...(manifest.requires ? { requires: manifest.requires } : {})
+  }, null, 2)}\n`);
+  const generated = [{ path: 'plugin.json', abs: null, size: reduced.length, mode: 0o644, data: reduced }];
+  const pkgFile = path.join(root, 'package.json');
+  if (fs.existsSync(pkgFile)) {
+    const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf8'));
+    const runtime = {};
+    for (const k of ['name', 'version', 'type', 'description', 'license', 'dependencies']) if (pkg[k] !== undefined) runtime[k] = pkg[k];
+    // A capability that declares its own dependencies keeps only those: the plugin's other
+    // dependencies serve the host side (routes, CLI) and never leave with the brick.
+    const own = manifest.capability.dependencies;
+    if (own !== undefined) {
+      if (!Array.isArray(own) || own.some((d) => typeof d !== 'string')) throw new Error(`Plugin '${manifest.id}' capability.dependencies must be an array of package names`);
+      const missing = own.filter((d) => !pkg.dependencies?.[d]);
+      if (missing.length) throw new Error(`Plugin '${manifest.id}' capability.dependencies names packages its package.json does not depend on: ${missing.join(', ')}`);
+      const kept = Object.fromEntries(own.map((d) => [d, pkg.dependencies[d]]));
+      if (Object.keys(kept).length) runtime.dependencies = kept; else delete runtime.dependencies;
+    }
+    const data = Buffer.from(`${JSON.stringify(runtime, null, 2)}\n`);
+    generated.push({ path: 'package.json', abs: null, size: data.length, mode: 0o644, data });
+  }
+  return [...kept, ...generated]
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+
 function hashEntries(entries) {
   const h = crypto.createHash('sha256');
   for (const e of entries) {

package/src/core/plugin-catalog.mjs

@@ -15,7 +15,7 @@ export function buildPluginCatalog(projectRoot = process.cwd(), { discover = dis
     return {
       id: plugin.id, name: manifest.name || plugin.id, version: manifest.version || null,
       scope: plugin.scope, valid: plugin.valid === true, errors: plugin.errors || [],
-      activation: pluginActivation(plugin),
+      activation: pluginActivation(plugin, { projectRoot }),
       description: manifest.description || '', namespace: manifest.cli?.command || null,
       callable, operations: [...(manifest.cli?.subcommands || []).filter(command => !['on', 'off'].includes(command.name)),
         ...['on', 'off'].map(name => ({ name, description: `${name === 'on' ? 'Enable' : 'Disable'} host execution and compile surfaces`, effect: 'write', output: 'json', args: [] }))].map(command => ({

package/src/core/plugin-context.mjs

@@ -18,7 +18,7 @@ export async function assemblePluginContexts({ projectRoot = process.cwd(), vaul
   const blocks = [];
 
   for (const plugin of plugins) {
-    if (!plugin.valid || !pluginActivation(plugin).enabled) continue;
+    if (!plugin.valid || !pluginActivation(plugin, { projectRoot: resolvedProjectRoot }).enabled) continue;
     const { manifest, dir, id } = plugin;
     const name = manifest.name || id;
 

package/src/core/plugin-contracts/card.mjs

@@ -1,9 +1,14 @@
 /**
- * Functional card contract. The host renders one card per plugin from these
- * declarations: what the plugin can do (commands with typed arguments and an
- * effect), what it needs (settings, credentials), and how to read its real
- * state (a status command). Everything here is optional; a plugin without it
- * still gets a card listing its commands and secrets.
+ * Functional card contract. A plugin's card face is its own bespoke Web
+ * Component, declared as a `ui.elements[]` entry of kind `card`. There is no
+ * template: no shared layout, no widget vocabulary, no allowlist of shapes.
+ * Core validates that the face exists and that the commands behind it are
+ * declared; it never dictates how the face is arranged.
+ *
+ * A plugin carries exactly one face and AS MANY secondary screens as it needs,
+ * each declared `kind: 'panel'`. Screens are the plugin's own design: it names
+ * them, orders them and decides what is on them. The host imposes no count and
+ * no screen set, and never derives a screen from the command list.
  */
 const plain = (v) => v && typeof v === 'object' && !Array.isArray(v);
 const COMMAND = /^[a-z][a-z0-9-]{0,63}$/;
@@ -15,14 +20,10 @@ export const OUTPUT_KINDS = ['json', 'text'];
 export const TIERS = ['core', 'official', 'personal', 'community'];
 export const LICENSE_CLASSES = ['open', 'closed'];
 const STATUS_STATES = ['ok', 'warn', 'error', 'unknown'];
-export const CARD_TEMPLATES = ['console', 'ledger', 'monitor', 'inbox', 'dashboard', 'workbench', 'vault'];
-export const CARD_WIDGETS = ['status', 'actions', 'table', 'detail', 'log', 'form', 'keypad', 'gauge', 'list', 'settings', 'credentials', 'activity', 'live'];
-export const WIDGETS_NEEDING_SOURCE = ['table', 'detail', 'list', 'gauge', 'log'];
 export const CARD_FONTS = ['system', 'inter', 'ibm-plex', 'space-grotesk', 'jetbrains-mono', 'dm-sans', 'outfit', 'fraunces', 'newsreader', 'chivo-mono'];
 export const CARD_DENSITIES = ['compact', 'comfortable', 'spacious'];
 export const CARD_RADII = ['none', 'sm', 'md', 'lg', 'pill'];
 export const CARD_HEADERS = ['plain', 'ledger-rule', 'band', 'tab-strip', 'badge-left'];
-export const CELL_FORMATS = ['text', 'number', 'money', 'date', 'datetime', 'bytes', 'percent', 'status'];
 export const WORKSPACE_PERMISSIONS = ['microphone', 'camera', 'notifications'];
 const HEX = /^#[0-9a-fA-F]{6}$/;
 
@@ -87,7 +88,7 @@ export function validateCardContract(manifest) {
       if (!LICENSE_CLASSES.includes(manifest.distribution.license)) errors.push(`'distribution.license' must be one of: ${LICENSE_CLASSES.join(', ')}`);
     }
   }
-  validateLayout(manifest, names, errors);
+  validateCardFace(manifest, errors, warnings);
   validateBranding(manifest.branding, errors, warnings);
   validateWorkspace(manifest.workspace, errors);
   if (Array.isArray(manifest.secrets)) {
@@ -101,36 +102,67 @@ export function validateCardContract(manifest) {
   return { errors, warnings, states: STATUS_STATES };
 }
 
-function validateLayout(manifest, commandNames, errors) {
-  const layout = manifest.card_layout;
-  if (layout === undefined) return;
-  if (!plain(layout)) { errors.push("'card_layout' must be an object"); return; }
-  if (!CARD_TEMPLATES.includes(layout.template)) errors.push(`'card_layout.template' must be one of: ${CARD_TEMPLATES.join(', ')}`);
-  if (!Array.isArray(layout.regions) || layout.regions.length === 0 || layout.regions.length > 12) {
-    errors.push("'card_layout.regions' must be an array of 1 to 12 regions");
-    return;
+/**
+ * Every plugin has a card face: bespoke owner code, declared once in
+ * ui.elements[]. A plugin without one is incomplete, and a plugin that declares
+ * a shared template is invalid.
+ *
+ * The *scaffold* emitted by `plugin create` deliberately contains no card: a
+ * face is authored by hand once the plugin's function is understood. A scaffold
+ * declares `scaffold: true`, so it installs while the author works and reports
+ * its missing face as a warning rather than an error. Any other plugin without
+ * a face is an error, because nothing else explains why it is missing.
+ */
+function validateCardFace(manifest, errors, warnings) {
+  if (manifest.card_layout !== undefined) {
+    errors.push("'card_layout' is not supported: a card face is bespoke owner code in ui.elements[], never a shared template");
   }
-  layout.regions.forEach((region, i) => {
-    const where = `card_layout.regions[${i}]`;
-    if (!plain(region)) { errors.push(`${where} must be an object`); return; }
-    if (!CARD_WIDGETS.includes(region.widget)) { errors.push(`${where}.widget must be one of: ${CARD_WIDGETS.join(', ')}`); return; }
-    if (WIDGETS_NEEDING_SOURCE.includes(region.widget)) {
-      const cmd = region.source?.command;
-      if (typeof cmd !== 'string' || !commandNames.has(cmd)) errors.push(`${where}.source.command must name a declared cli subcommand`);
-    }
-    if (region.widget === 'form' && !commandNames.has(region.command)) errors.push(`${where}.command must name a declared cli subcommand`);
-    if (region.commands !== undefined) {
-      if (!Array.isArray(region.commands) || region.commands.some((c) => !commandNames.has(c))) errors.push(`${where}.commands must list declared cli subcommands`);
+  const elements = manifest.ui?.elements;
+  // A brick is distributed as capability code alone. It carries no UI, so it
+  // has no face; every other plugin still requires exactly one.
+  if (manifest.brick === true) {
+    validateCapability(manifest, errors);
+    if (manifest.ui !== undefined && Array.isArray(elements) && elements.length > 0) {
+      errors.push("a brick ships without UI: remove 'ui.elements' or drop 'brick: true'");
     }
-    if (region.columns !== undefined) {
-      if (!Array.isArray(region.columns) || region.columns.length === 0) errors.push(`${where}.columns must be a non-empty array`);
-      else region.columns.forEach((c, j) => {
-        if (!plain(c) || typeof c.key !== 'string' || typeof c.label !== 'string') errors.push(`${where}.columns[${j}] needs key and label`);
-        else if (c.format !== undefined && !CELL_FORMATS.includes(c.format)) errors.push(`${where}.columns[${j}].format must be one of: ${CELL_FORMATS.join(', ')}`);
-      });
+    return;
+  }
+  if (manifest.capability !== undefined) validateCapability(manifest, errors);
+  if (!Array.isArray(elements) || elements.length === 0) {
+    // A scaffold is a freshly created plugin whose face has not been authored
+    // yet. It must be installable so the author can iterate, but it is not a
+    // shippable plugin, so the missing face is reported and stays visible.
+    if (manifest.scaffold === true) {
+      warnings.push("'ui.elements' declares no card face yet: author ui/card.js and ui/DESIGN.md by hand for this plugin's own function, then declare the face in ui.elements[]");
+      return;
     }
-    if (region.widget === 'table' && !Array.isArray(region.columns)) errors.push(`${where}.columns is required for a table`);
-  });
+    errors.push("'ui.elements' must declare the plugin's card face; every plugin has one, authored by hand");
+    return;
+  }
+  // One face, and as many secondary screens as the plugin needs. Cardinality is
+  // checked for `card` alone, so panels may be declared in any number and on
+  // either side of the face.
+  const faces = elements.filter((element) => plain(element) && element.kind === 'card');
+  if (faces.length === 0) errors.push("'ui.elements' must declare an element of kind 'card'");
+  if (faces.length > 1) errors.push("'ui.elements' must declare exactly one card face; further screens use kind 'panel'");
+}
+
+/**
+ * `capability {entry, exports}` names the host-free module a project vendors:
+ * a relative path inside the plugin, and the exported names it promises.
+ */
+function validateCapability(manifest, errors) {
+  const cap = manifest.capability;
+  if (!plain(cap)) { errors.push("'capability' must declare {entry, exports}"); return; }
+  const entry = cap.entry;
+  if (typeof entry !== 'string' || !/^[A-Za-z0-9._\/-]{1,200}\.m?js$/.test(entry) || entry.startsWith('/') || entry.split('/').includes('..')) {
+    errors.push("capability.entry must be a relative .js or .mjs path inside the plugin");
+  } else if (entry.split('/')[0] === 'ui') {
+    errors.push('capability.entry must not live under ui/: a brick contains no UI');
+  }
+  if (!Array.isArray(cap.exports) || cap.exports.length === 0 || cap.exports.some((n) => typeof n !== 'string' || !/^[A-Za-z_$][\w$]*$/.test(n))) {
+    errors.push('capability.exports must be a non-empty array of export names');
+  }
 }
 
 function validateBranding(branding, errors, warnings) {

package/src/core/plugin-loader.mjs

@@ -29,7 +29,7 @@ export function globalPluginsDir() {
 }
 
 export function bundledPluginsDir() {
-  return process.env._TR_TEST_BUNDLED_PLUGINS_DIR || path.join(PACKAGE_ROOT, 'scaffold', '.agent', 'skills', 'total-recall', 'plugins');
+  return path.join(PACKAGE_ROOT, 'scaffold', '.agent', 'skills', 'total-recall', 'plugins');
 }
 
 /** The vault that owns records for plugins installed in `pluginsDir` (`<brain>/plugins` → `<brain>/memory-vault`). */
@@ -434,11 +434,10 @@ export function discoverPlugins(projectRoot = process.cwd()) {
 export function listBundledPlugins(projectRoot = process.cwd()) {
   const seen = new Set();
   const out = [];
-  // Under test the fixture directory is the only source, so results never
-  // depend on plugins installed in the developer's own brain.
-  const dirs = process.env._TR_TEST_BUNDLED_PLUGINS_DIR
-    ? [bundledPluginsDir()]
-    : [bundledPluginsDir(), path.join(PACKAGE_ROOT, '.agent', 'skills', 'total-recall', 'plugins')];
+  // Each plugin repository owns its own manifest, and nothing keeps a second
+  // copy of it. A shared fixture describing a plugin would be a competing
+  // definition of that plugin, and it drifts.
+  const dirs = [bundledPluginsDir(), path.join(PACKAGE_ROOT, '.agent', 'skills', 'total-recall', 'plugins')];
   for (const dir of dirs) {
     if (!fs.existsSync(dir)) continue;
     for (const p of readPluginsDir(dir, 'bundled')) {

package/src/core/plugin-runner.mjs

@@ -10,11 +10,16 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { PACKAGE_ROOT, resolvePluginFile } from './plugin-loader.mjs';
 import { readPluginRecord } from './plugin-store.mjs';
+import { pluginExecutionEnabled } from './plugin-state.mjs';
 import { setPluginActive } from './plugin-activation.mjs';
 
 const CHILD = path.join(path.dirname(fileURLToPath(import.meta.url)), 'plugin-runner-child.mjs');
 export const DEFAULT_TIMEOUT_MS = 30_000;
 export const MAX_OUTPUT_BYTES = 256 * 1024;
+// A terminal call (stdin inherited from the operator) is read by a person or an
+// agent, not buffered by the server, so it gets the ceiling the host's other
+// child processes use instead of the server's bound.
+export const CLI_MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
 export const MAX_INPUT_BYTES = 64 * 1024;
 
 /** A credential is one declared string on stdin, never a command-line value. */
@@ -37,6 +42,8 @@ export function validatePluginSecretInput(plugin, subcommand, input) {
  */
 export function runPluginCommand(plugin, options = {}) {
   const { subcommand = '', args = [], cwd = process.cwd(), timeoutMs: requestedTimeoutMs, stdin = 'ignore', stdinText, composable = false, secretsBrainDir } = options;
+  const maxOutputBytes = options.maxOutputBytes ?? (stdin === 'inherit' ? CLI_MAX_OUTPUT_BYTES : MAX_OUTPUT_BYTES);
+  if (!Number.isInteger(maxOutputBytes) || maxOutputBytes < 1 || maxOutputBytes > CLI_MAX_OUTPUT_BYTES) return Promise.reject(new Error(`Plugin output limit must be 1..${CLI_MAX_OUTPUT_BYTES} bytes`));
   try { validatePluginSecretInput(plugin, subcommand, stdinText); }
   catch (err) { return Promise.reject(err); }
   const operation = subcommand || args[0];
@@ -46,7 +53,7 @@ export function runPluginCommand(plugin, options = {}) {
       output: JSON.stringify(result), durationMs: 0, timedOut: false,
     }));
   }
-  if (readPluginRecord(plugin)?.runtime_enabled === false && !['status', 'health', 'jobs', '--help', '-h', 'help'].includes(operation)) {
+  if (!pluginExecutionEnabled(plugin, { projectRoot: cwd }) && !['status', 'health', 'jobs', '--help', '-h', 'help'].includes(operation)) {
     return Promise.reject(new Error(`Plugin ${plugin.id} is inactive; run total-recall plugin on ${plugin.id}`));
   }
   const declaredTimeout = plugin?.manifest?.cli?.subcommands?.find(item => item.name === operation)?.timeout_ms;
@@ -95,9 +102,9 @@ export function runPluginCommand(plugin, options = {}) {
       // Even a faulty owner that echoes stdin cannot return credential material.
       if (stdinText !== undefined) return;
       if (truncated) return;
-      if (bytes + buf.length > MAX_OUTPUT_BYTES) {
-        const partial=buf.subarray(0, MAX_OUTPUT_BYTES - bytes);chunks.push(partial);stream.push(partial);
-        bytes = MAX_OUTPUT_BYTES;
+      if (bytes + buf.length > maxOutputBytes) {
+        const partial=buf.subarray(0, maxOutputBytes - bytes);chunks.push(partial);stream.push(partial);
+        bytes = maxOutputBytes;
         truncated = true;
         return;
       }
@@ -124,11 +131,11 @@ export function runPluginCommand(plugin, options = {}) {
       clearTimeout(timer);
       let output = Buffer.concat(chunks).toString('utf8');
       if (spawnError) output += `${output ? '\n' : ''}[runner] ${spawnError.message}`;
-      if (truncated) output += `\n[runner] output truncated at ${MAX_OUTPUT_BYTES} bytes`;
+      if (truncated) output += `\n[runner] output truncated at ${maxOutputBytes} bytes`;
       if (timedOut) output += `\n[runner] killed after ${timeoutMs} ms`;
       let stderr=Buffer.concat(stderrChunks).toString('utf8');
       if(spawnError)stderr+=`\n[runner] ${spawnError.message}`;
-      if(truncated)stderr+=`\n[runner] output truncated at ${MAX_OUTPUT_BYTES} bytes`;
+      if(truncated)stderr+=`\n[runner] output truncated at ${maxOutputBytes} bytes`;
       if(timedOut)stderr+=`\n[runner] killed after ${timeoutMs} ms`;
       resolve({
         ok: !spawnError && !timedOut && exitCode === 0,

package/src/core/plugin-runtime.mjs

@@ -6,7 +6,7 @@ import { pluginActivation } from './plugin-state.mjs';
 export async function loadPluginModule(id, name, { activeRequired = false, projectRoot = process.cwd() } = {}) {
   const plugin = discoverPlugins(projectRoot).find(item => item.id === id);
   if (!plugin?.valid) throw new Error(`Required plugin ${id} is missing or invalid`);
-  if (activeRequired && !pluginActivation(plugin).enabled) throw new Error(`Plugin ${id} is inactive`);
+  if (activeRequired && !pluginActivation(plugin, { projectRoot }).enabled) throw new Error(`Plugin ${id} is inactive`);
   // Pure bootstrap bindings remain importable so an inactive auth/config owner
   // cannot prevent the management CLI from turning it back on. Execution is
   // gated at the runner, scheduler and mounted router boundaries.
@@ -21,7 +21,8 @@ export async function loadPluginModule(id, name, { activeRequired = false, proje
 
 export async function loadPluginRouters() {
   const routers = [];
-  for (const plugin of discoverPlugins(process.cwd()).filter(item => item.valid)) {
+  const projectRoot = process.cwd();
+  for (const plugin of discoverPlugins(projectRoot).filter(item => item.valid)) {
     for (const relative of plugin.manifest.runtime?.routers || []) {
       process.env.TR_PACKAGE_ROOT = PACKAGE_ROOT;
       const file = resolvePluginFile(plugin.dir, relative);
@@ -29,8 +30,8 @@ export async function loadPluginRouters() {
       if (typeof module.default !== 'function') throw new Error(`Plugin ${plugin.id} router must export middleware`);
       const guarded = function router(req, res, next) {
         const ownsPath = module.default.stack?.some(layer => layer.route && layer.match(req.path));
-        if (!pluginActivation(plugin).enabled && ownsPath) return res.status(503).json({ error: `Plugin ${plugin.id} is inactive` });
-        if (!pluginActivation(plugin).enabled) return next();
+        if (!pluginActivation(plugin, { projectRoot }).enabled && ownsPath) return res.status(503).json({ error: `Plugin ${plugin.id} is inactive` });
+        if (!pluginActivation(plugin, { projectRoot }).enabled) return next();
         return module.default(req, res, next);
       };
       // Preserve the real mounted route stack for API/CLI discovery.

package/src/core/plugin-setup.mjs

@@ -1,13 +1,15 @@
 /** Run declared, enabled plugin setup through the normal isolated CLI runner. */
 import { discoverPlugins } from './plugin-loader.mjs';
-import { readPluginRecord } from './plugin-store.mjs';
+import { pluginExecutionEnabled } from './plugin-state.mjs';
 import { runPluginCommand } from './plugin-runner.mjs';
 
-export async function setupInstalledPlugins({root=process.cwd(),plugins=discoverPlugins(root),run=runPluginCommand,record=readPluginRecord}={}) {
+export async function setupInstalledPlugins({root=process.cwd(),plugins=discoverPlugins(root),run=runPluginCommand,activation=pluginExecutionEnabled}={}) {
   const results=[];
   for(const plugin of plugins) {
     const command=plugin.manifest?.runtime?.setup_command;
-    if(!plugin.valid || !command || record(plugin)?.runtime_enabled===false)continue;
+    if(!plugin.valid || !command)continue;
+    // Setup follows the repository's own setting for a shared plugin.
+    if(!activation(plugin,{projectRoot:root}))continue;
     if(!plugin.manifest.cli?.subcommands?.some(operation=>operation.name===command)) {
       results.push({id:plugin.id,ok:false,error:'Runtime setup must name a declared CLI operation'});continue;
     }

package/src/core/plugin-state-store.mjs

@@ -71,13 +71,23 @@ export async function executePluginState(request) {
   }
   // A guard serializes state read/compare/commit across native worker processes.
   const lock = path.join(root, '.mutation-lock');
+  const guardTimeoutMs = request.guardTimeoutMs ?? 5000;
+  if (!Number.isInteger(guardTimeoutMs) || guardTimeoutMs < 1 || guardTimeoutMs > 5000) throw new Error('Invalid plugin guard timeout');
+  const deadline = performance.now() + guardTimeoutMs;
+  for (;;) {
   try {
     fs.mkdirSync(lock, { mode: 0o700 });
+    break;
   } catch (err) {
     // Distinguish a genuine concurrent mutation from an environment failure so
     // callers are not told the store is busy when it is actually inaccessible.
     if (err && err.code === 'EEXIST') {
-      throw new Error('Plugin state mutation is busy; another mutation holds the guard');
+      const stat = fs.lstatSync(lock, { throwIfNoEntry: false });
+      if (!stat) continue;
+      if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error('Unsafe plugin mutation guard');
+      if (performance.now() >= deadline) throw new Error('Plugin state mutation is busy; timed out waiting for the guard');
+      await new Promise(resolve => setTimeout(resolve, 20));
+      continue;
     }
     if (err && (err.code === 'EACCES' || err.code === 'EPERM' || err.code === 'EROFS')) {
       throw new Error(
@@ -87,6 +97,7 @@ export async function executePluginState(request) {
     }
     throw new Error(`Plugin state mutation guard could not be created at ${lock}: ${err?.message || err}`);
   }
+  }
   try {
     const durableKeys = new FileIdempotencyStore(path.join(root, '.idempotency'));
     const intentHash = crypto.createHash('sha256').update(JSON.stringify({ path: relative, action, value, expectedVersion, format: request.format })).digest('hex');