total-recall-brain 3.45.0 → 3.46.0

package/src/core/plugin-contracts/startup-check.mjs

@@ -0,0 +1,49 @@
+/**
+ * `startup_check`: a read command a plugin contributes to `startup check` and
+ * `brief`, so something the plugin owns that needs attention is visible when a
+ * session starts. Core runs it and prints what it says; it never inspects the
+ * plugin's domain itself.
+ *
+ *   "startup_check": { "command": "unmerged", "args": ["--json"], "timeout_ms": 15000 }
+ *
+ * The command prints one JSON object: { ok: boolean, outstanding: integer,
+ * summary: string }. `outstanding` above zero means attention is needed and
+ * `summary` says what and where, in one line.
+ */
+const plain = (v) => v && typeof v === 'object' && !Array.isArray(v);
+const ARG = /^[A-Za-z0-9][A-Za-z0-9._=:\/-]{0,127}$|^--?[a-z][a-z0-9-]{0,63}$/;
+export const STARTUP_CHECK_MAX_TIMEOUT_MS = 30000;
+
+/** @returns {string[]} errors */
+export function validateStartupCheck(manifest) {
+  const check = manifest?.startup_check;
+  if (check === undefined) return [];
+  if (!plain(check)) return ["'startup_check' must be an object"];
+  const errors = [];
+  const subs = Array.isArray(manifest.cli?.subcommands) ? manifest.cli.subcommands : [];
+  const sub = subs.find((s) => s?.name === check.command);
+  if (typeof check.command !== 'string' || !sub) errors.push("'startup_check.command' must name a declared cli subcommand");
+  else if (sub.effect && sub.effect !== 'read') errors.push("'startup_check.command' must be a read command");
+  if (check.args !== undefined && (!Array.isArray(check.args) || check.args.length > 8 || check.args.some((a) => typeof a !== 'string' || !ARG.test(a)))) {
+    errors.push("'startup_check.args' must be at most 8 plain arguments");
+  }
+  if (check.timeout_ms !== undefined && (!Number.isInteger(check.timeout_ms) || check.timeout_ms < 1000 || check.timeout_ms > STARTUP_CHECK_MAX_TIMEOUT_MS)) {
+    errors.push(`'startup_check.timeout_ms' must be an integer from 1000 to ${STARTUP_CHECK_MAX_TIMEOUT_MS}`);
+  }
+  return errors;
+}
+
+/**
+ * Read a startup check's output. Anything other than the declared shape is
+ * reported as unavailable, never as clean.
+ * @returns {{ status: 'ok'|'attention'|'unavailable', outstanding?: number, summary?: string, reason?: string }}
+ */
+export function readStartupCheckOutput(stdout) {
+  let body;
+  try { body = JSON.parse(String(stdout || '').trim()); } catch { return { status: 'unavailable', reason: 'output is not JSON' }; }
+  if (!plain(body) || typeof body.ok !== 'boolean' || !Number.isInteger(body.outstanding) || body.outstanding < 0 || typeof body.summary !== 'string') {
+    return { status: 'unavailable', reason: 'output is not { ok, outstanding, summary }' };
+  }
+  if (!body.ok) return { status: 'unavailable', outstanding: body.outstanding, summary: body.summary.slice(0, 500), reason: 'the check reported a failure' };
+  return { status: body.outstanding > 0 ? 'attention' : 'ok', outstanding: body.outstanding, summary: body.summary.slice(0, 500) };
+}

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

@@ -1,6 +1,6 @@
 /** Pure plugin UI manifest validation; rendering belongs to capability owners. */
 import path from 'node:path';
-export const UI_ELEMENT_KINDS = ['panel', 'form', 'list', 'detail', 'settings', 'widget', 'card', 'card-face'];
+export const UI_ELEMENT_KINDS = ['panel', 'form', 'list', 'detail', 'settings', 'widget'];
 const PROP_TYPES = ['string', 'number', 'boolean', 'object', 'array'];
 const ELEMENT_ID = /^[a-z][a-z0-9-]{0,63}$/;
 // Custom element names: lowercase, start with a letter, contain a hyphen.
@@ -117,13 +117,13 @@ function normalizeElement(raw, index, errors) {
 /**
  * Validates and normalizes a manifest `ui` block.
  * @param {object} ui
- * @returns {{ design_tokens?: string, elements: object[] }}
+ * @returns {{ design_tokens?: string, home?: string, elements: object[] }}
  * @throws {UiSpecError}
  */
 export function normalizeUiSpec(ui) {
   const errors = [];
   if (!isPlainObject(ui)) throw new UiSpecError(["'ui' must be an object"]);
-  unknownKeys(ui, ['design_tokens', 'elements'], 'ui', errors);
+  unknownKeys(ui, ['design_tokens', 'elements', 'home'], 'ui', errors);
   const spec = { elements: [] };
   if (ui.design_tokens !== undefined) {
     if (!isSafePluginPath(ui.design_tokens, /\.md$/)) {
@@ -142,6 +142,12 @@ export function normalizeUiSpec(ui) {
     tags.add(el.tag);
     spec.elements.push(el);
   });
+  if (ui.home !== undefined) {
+    if (!spec.elements.some(el => el.id === ui.home && ['panel', 'form', 'list', 'detail', 'widget'].includes(el.kind))) {
+      errors.push("'ui.home' must name a declared content element");
+    } else spec.home = ui.home;
+    if (!spec.design_tokens) errors.push("'ui.home' requires 'ui.design_tokens'");
+  }
   if (errors.length) throw new UiSpecError(errors);
   return spec;
 }

package/src/core/plugin-distribution.mjs

@@ -6,8 +6,8 @@ import { installPlugin as installLocal, readPluginRecord, patchPluginRecord, des
   findInstalled, emit, vaultFor } from './plugin-store.mjs';
 export * from './plugin-store.mjs';
 
-function describePluginWithShare(plugin) {
-  const result = describePlugin(plugin);
+function describePluginWithShare(plugin, projectRoot) {
+  const result = describePlugin(plugin, projectRoot);
   result.share_url = result.shared && result.sha256 ? publicPluginShareUrl(plugin.id, result.sha256) : null;
   return result;
 }
@@ -50,7 +50,7 @@ export async function setPluginShared(id, shared, options = {}) {
   if (shared && !plugin.valid) throw new Error(`Plugin '${id}' has an invalid manifest and cannot be shared`);
   await patchPluginRecord(plugin, { shared: !!shared, public_shared: !!shared });
   await emit(vaultFor(plugin), id, shared ? 'shared' : 'unshared', { scope: plugin.scope });
-  return describePluginWithShare(plugin);
+  return describePluginWithShare(plugin, options.projectRoot);
 }
 
 export async function setPluginBranding(id, branding, options = {}) {
@@ -68,7 +68,7 @@ export async function setPluginBranding(id, branding, options = {}) {
   };
   await patchPluginRecord(plugin, { branding: cleanBranding });
   await emit(vaultFor(plugin), id, 'branding_updated', { branding: cleanBranding, scope: plugin.scope });
-  return describePluginWithShare(plugin);
+  return describePluginWithShare(plugin, options.projectRoot);
 }
 
 export async function setPluginLocked(id, locked, options = {}) {
@@ -76,7 +76,7 @@ export async function setPluginLocked(id, locked, options = {}) {
   if (!plugin) throw new Error(`Plugin '${id}' is not installed`);
   await patchPluginRecord(plugin, { locked: !!locked });
   await emit(vaultFor(plugin), id, locked ? 'locked' : 'unlocked', { scope: plugin.scope });
-  return describePluginWithShare(plugin);
+  return describePluginWithShare(plugin, options.projectRoot);
 }
 
 export async function deployPluginToStore(id, options = {}) {
@@ -97,7 +97,7 @@ export async function deployPluginToStore(id, options = {}) {
     scope: plugin.scope,
     locked: autoLock
   });
-  return describePluginWithShare(plugin);
+  return describePluginWithShare(plugin, options.projectRoot);
 }
 
 /** What this node offers to mesh peers: valid installed plugins whose record says shared. */

package/src/core/plugin-lifecycle.mjs

@@ -0,0 +1,58 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { FileLeaseStore } from '@ssss/cli/leases';
+import { globalPluginsDir, projectPluginsDir } from './plugin-loader.mjs';
+
+/** Use only real directories below the repository, including any archive parents. */
+function directory(root, names, create = false) {
+  let target = root;
+  for (const name of names) {
+    target = path.join(target, name);
+    let stat = fs.lstatSync(target, { throwIfNoEntry: false });
+    if (!stat && create) {
+      try { fs.mkdirSync(target, { mode: 0o700 }); }
+      catch (error) { if (error.code !== 'EEXIST') throw error; }
+      stat = fs.lstatSync(target);
+    }
+    if (!stat) return null;
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('Plugin lifecycle paths must be real directories.');
+  }
+  return target;
+}
+
+export async function withRepositoryPluginLifecycle(projectRoot, id, change) {
+  if (!projectRoot) return change(null);
+  if (!/^[a-z][a-z0-9-]{1,63}$/.test(id)) throw new Error('Invalid plugin identity');
+  const root = fs.realpathSync(projectRoot);
+  const brainPath = path.dirname(projectPluginsDir(root));
+  const shared = path.dirname(globalPluginsDir());
+  if (brainPath === path.resolve(shared) ||
+      (fs.existsSync(brainPath) && fs.existsSync(shared) && fs.realpathSync(brainPath) === fs.realpathSync(shared))) {
+    return change(null);
+  }
+  const brain = directory(root, path.relative(root, brainPath).split(path.sep), true);
+  const store = new FileLeaseStore(directory(brain, ['config', 'plugin-activation-leases'], true));
+  const lease = await store.acquire({ workspace_id: 'plugin-activation', target: id, principal_id: 'total-recall', operation_id: crypto.randomUUID() }, 120_000);
+  try {
+    return await change(brain);
+  } finally {
+    await store.release(lease);
+  }
+}
+
+/** Move the complete local runtime directory without copying or traversing its contents. */
+export function moveRepositoryPluginState(brain, id, direction) {
+  if (!brain) return { ok: true, state: 'none' };
+  const live = ['plugin-state'];
+  const archive = ['config', 'plugin-state-archive'];
+  const restoring = direction === 'restore';
+  const source = directory(brain, [...(restoring ? archive : live), id]);
+  const destination = restoring ? live : archive;
+  const existing = directory(brain, [...destination, id]);
+  if (source && existing) throw new Error('Active and archived plugin state both exist. Both copies were preserved.');
+  if (!source) return { ok: true, state: !restoring && existing ? 'already-archived' : 'none' };
+  const parent = directory(brain, destination, true);
+  fs.renameSync(source, path.join(parent, id));
+  return { ok: true, state: restoring ? 'restored' : 'archived' };
+}

package/src/core/plugin-loader.mjs

@@ -5,7 +5,8 @@ import { fileURLToPath } from 'node:url';
 import { validateAppCliSpec } from './plugin-contracts/app-cli.mjs';
 import { validateUiSpec } from './plugin-contracts/ui.mjs';
 import { validateConfigurationSpec } from './plugin-contracts/configuration.mjs';
-import { validateCardContract } from './plugin-contracts/card.mjs';
+import { validateManifestContract } from './plugin-contracts/manifest.mjs';
+import { validateStartupCheck } from './plugin-contracts/startup-check.mjs';
 
 const ID_PATTERN = /^[a-z][a-z0-9-]{1,63}$/;
 const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
@@ -24,6 +25,8 @@ export function projectPluginsDir(projectRoot = process.cwd()) {
 }
 
 export function globalPluginsDir() {
+  // A staged server can use its matching plugin packages with the same brain and Auth store.
+  if (process.env.TR_RUNTIME_PLUGINS_DIR) return path.resolve(process.env.TR_RUNTIME_PLUGINS_DIR);
   const agentDir = process.env.AGENT_DIR || process.env._TR_TEST_AGENT_DIR || path.join(os.homedir(), '.agent');
   return path.join(agentDir, 'skills', 'total-recall', 'plugins');
 }
@@ -94,8 +97,9 @@ export function validatePluginManifest(manifest) {
     return { valid: false, errors: ['Manifest must be a non-null object'] };
   }
   if (manifest.configuration !== undefined) errors.push(...validateConfigurationSpec(manifest.configuration));
-  const cardContract = validateCardContract(manifest);
-  errors.push(...cardContract.errors);
+  const contract = validateManifestContract(manifest);
+  errors.push(...contract.errors);
+  errors.push(...validateStartupCheck(manifest));
 
   if (!manifest.id || typeof manifest.id !== 'string') {
     errors.push("Missing required field 'id'");
@@ -332,7 +336,7 @@ export function validatePluginManifest(manifest) {
   return {
     valid: errors.length === 0,
     errors,
-    warnings: cardContract.warnings
+    warnings: contract.warnings
   };
 }
 
@@ -412,7 +416,7 @@ export function readPluginsDir(dir, scope) {
 /**
  * Discover installed plugins across project and global directories.
  * A project plugin shadows a global plugin with the same id.
- * @param {string} [projectRoot] - Current project root directory
+ * @param {string|null} [projectRoot] - Current project root, or null for only shared and bundled plugins
  */
 export function discoverPlugins(projectRoot = process.cwd()) {
   const seen = new Set();

package/src/core/plugin-runner.mjs

@@ -9,10 +9,10 @@ import { manifestHelp } from './plugin-help.mjs';
 import { spawn } from 'node:child_process';
 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 { PACKAGE_ROOT, projectPluginsDir, resolvePluginFile } from './plugin-loader.mjs';
+import { readPluginRecord, recordPluginsDir } from './plugin-store.mjs';
 import { pluginExecutionEnabled } from './plugin-state.mjs';
-import { setPluginActive } from './plugin-activation.mjs';
+import { activatePluginOnUse, 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;
@@ -39,11 +39,12 @@ export function validatePluginSecretInput(plugin, subcommand, input) {
 
 /**
  * @param {object} plugin  A discovered plugin ({ id, dir, manifest }).
- * @param {{ subcommand?: string, args?: string[], cwd?: string, timeoutMs?: number }} [options]
+ * @param {{ subcommand?: string, args?: string[], cwd?: string, projectRoot?: string|null, timeoutMs?: number }} [options]
  * @returns {Promise<{ ok: boolean, exitCode: number|null, signal: string|null, timedOut: boolean, truncated: boolean, output: string, durationMs: number }>}
  */
 export function runPluginCommand(plugin, options = {}) {
   const { subcommand = '', args = [], cwd = process.cwd(), timeoutMs: requestedTimeoutMs, stdin = 'ignore', stdinText, stdinRequest, composable = false, secretsBrainDir } = options;
+  const { projectRoot = cwd } = options;
   const help = manifestHelp(plugin, { subcommand, args });
   if (help !== null) return Promise.resolve({ ok: true, exitCode: 0, stdout: help, stderr: '', output: help, durationMs: 0, timedOut: false });
   const maxOutputBytes = options.maxOutputBytes ?? (stdin === 'inherit' ? CLI_MAX_OUTPUT_BYTES : MAX_OUTPUT_BYTES);
@@ -58,19 +59,26 @@ export function runPluginCommand(plugin, options = {}) {
   const stdinPayload = stdinText ?? stdinRequest;
   const operation = subcommand || args[0];
   if (operation === 'on' || operation === 'off') {
-    return setPluginActive(plugin.id, operation === 'on', { projectRoot: cwd }).then(result => ({
-      ok: result.compilation.ok, exitCode: result.compilation.ok ? 0 : 1,
+    return setPluginActive(plugin.id, operation === 'on', { projectRoot: projectRoot ?? cwd }).then(result => ({
+      ok: result.compilation.ok && result.cleanup?.ok !== false, exitCode: result.compilation.ok && result.cleanup?.ok !== false ? 0 : 1,
       output: JSON.stringify(result), durationMs: 0, timedOut: false,
     }));
   }
-  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 passive = ['status', 'health', 'jobs', '--help', '-h', 'help'].includes(operation);
   // Manifests declare this as `timeoutMs`; the runner only read `timeout_ms`, so every declared
   // timeout was ignored and each command fell back to DEFAULT_TIMEOUT_MS (30s). That killed work
   // that legitimately takes longer — `mesh nodes` and `tr-transcribe transcribe` (model load) both
   // died at 30s while their manifests asked for far more. Accept both spellings.
   const declaration = plugin?.manifest?.cli?.subcommands?.find(item => item.name === operation);
+  if (!pluginExecutionEnabled(plugin, { projectRoot }) && !passive) {
+    if (options.activateOnUse && declaration && !args.includes('--help') && !args.includes('-h')) {
+      return activatePluginOnUse(plugin.id, { projectRoot }).then(result => {
+        if (result && !result.compilation.ok) throw new Error('Plugin was activated, but the repository instructions could not be refreshed.');
+        return runPluginCommand(plugin, { ...options, activateOnUse: false });
+      });
+    }
+    return Promise.reject(new Error(`Plugin ${plugin.id} is inactive; run total-recall plugin on ${plugin.id}`));
+  }
   const declaredTimeout = declaration?.timeout_ms ?? declaration?.timeoutMs;
   const timeoutMs = requestedTimeoutMs ?? declaredTimeout ?? DEFAULT_TIMEOUT_MS;
   if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 600000) return Promise.reject(new Error('Plugin timeout must be 1..600000 ms'));
@@ -85,6 +93,8 @@ export function runPluginCommand(plugin, options = {}) {
   const safeArgs = (Array.isArray(args) ? args : []).map(String);
   if (stdinPayload !== undefined && !safeArgs.includes('--stdin')) safeArgs.push('--stdin');
   const childArgv = [CHILD, handler, command, ...(subcommand ? [String(subcommand)] : []), ...safeArgs];
+  // Only an explicitly selected project owns repository state. The cwd fallback above preserves legacy activation.
+  const statePluginsDir = options.projectRoot ? projectPluginsDir(projectRoot) : recordPluginsDir(plugin);
 
   return new Promise((resolve) => {
     const started = Date.now();
@@ -101,10 +111,11 @@ export function runPluginCommand(plugin, options = {}) {
       env: {
         ...process.env,
         TR_PACKAGE_ROOT: PACKAGE_ROOT,
+        TOTAL_RECALL_BIN: path.join(PACKAGE_ROOT, 'bin', 'total-recall.mjs'),
         TR_PLUGIN_ID: plugin.id,
         TR_PLUGIN_DIR: plugin.dir,
         TR_PLUGIN_CONFIG: JSON.stringify(readPluginRecord(plugin)?.configuration || {}),
-        ...(plugin.pluginsDir ? { TR_PLUGIN_STATE_DIR: path.join(path.dirname(plugin.pluginsDir), 'plugin-state', plugin.id) } : {}),
+        ...(statePluginsDir ? { TR_PLUGIN_STATE_DIR: path.join(path.dirname(statePluginsDir), 'plugin-state', plugin.id) } : {}),
         ...(secretsBrainDir ? { TR_SECRETS_BRAIN: secretsBrainDir } : {}),
         TR_PLUGIN_COMMAND_MODE: composable ? 'composable' : 'cli',
         FORCE_COLOR: '0',

package/src/core/plugin-startup-checks.mjs

@@ -0,0 +1,44 @@
+/**
+ * Run the read commands installed plugins contribute to `startup check` and
+ * `brief` (`startup_check` in plugin.json). Core runs them and reports what
+ * they say; the domain knowledge stays in the plugin. A check that fails,
+ * times out or prints the wrong shape is reported as unavailable, never as
+ * clean.
+ */
+import { discoverPlugins } from './plugin-loader.mjs';
+import { runPluginCommand } from './plugin-runner.mjs';
+import { pluginExecutionEnabled } from './plugin-state.mjs';
+import { readStartupCheckOutput, STARTUP_CHECK_MAX_TIMEOUT_MS } from './plugin-contracts/startup-check.mjs';
+
+const DEFAULT_TIMEOUT_MS = 15000;
+
+/**
+ * @param {{ cwd?: string, plugins?: object[], run?: Function, enabled?: Function }} [options]
+ * @returns {Promise<Array<{ plugin: string, command: string, status: string, outstanding?: number, summary?: string, reason?: string }>>}
+ */
+export async function runPluginStartupChecks({ cwd = process.cwd(), plugins, run = runPluginCommand, enabled = pluginExecutionEnabled } = {}) {
+  let found;
+  try { found = plugins ?? discoverPlugins(cwd); } catch (error) { return [{ plugin: '*', command: 'plugin discovery', status: 'unavailable', reason: error.message }]; }
+  const declared = found.filter((plugin) => plugin.valid && plugin.manifest?.startup_check);
+  return Promise.all(declared.map(async (plugin) => {
+    const check = plugin.manifest.startup_check;
+    const command = `${plugin.manifest.cli?.command || plugin.id} ${check.command}`;
+    try {
+      if (!enabled(plugin, { projectRoot: cwd })) return { plugin: plugin.id, command, status: 'inactive' };
+    } catch (error) {
+      return { plugin: plugin.id, command, status: 'unavailable', reason: `activation policy unreadable: ${error.message}` };
+    }
+    const timeoutMs = Math.min(check.timeout_ms ?? DEFAULT_TIMEOUT_MS, STARTUP_CHECK_MAX_TIMEOUT_MS);
+    try {
+      const result = await run(plugin, { subcommand: check.command, args: check.args || [], cwd, timeoutMs });
+      if (result.timedOut) return { plugin: plugin.id, command, status: 'unavailable', reason: `timed out after ${timeoutMs} ms` };
+      const read = readStartupCheckOutput(result.stdout);
+      if (read.status !== 'unavailable' && result.exitCode !== 0) {
+        return { plugin: plugin.id, command, ...read, status: 'unavailable', reason: `exited ${result.exitCode}` };
+      }
+      return { plugin: plugin.id, command, ...read };
+    } catch (error) {
+      return { plugin: plugin.id, command, status: 'unavailable', reason: error.message };
+    }
+  }));
+}

package/src/core/plugin-state.mjs

@@ -1,9 +1,15 @@
 /** Read-only host activation, safe during configuration bootstrap. */
 import fs from 'node:fs';
+import crypto from 'node:crypto';
 import path from 'node:path';
 import matter from './frontmatter.mjs';
 import { globalPluginsDir, projectPluginsDir, vaultForPluginsDir } from './plugin-loader.mjs';
 
+/** Bundled fallback packages use the same shared policy as a global install. */
+export function usesSharedPluginPolicy(plugin) {
+  return plugin.scope === 'global' || plugin.scope === 'scaffold';
+}
+
 /**
  * Enablement has two layers. The plugin's own brain holds the shared setting —
  * the global brain, since a shared plugin lives in one folder per machine. A
@@ -26,14 +32,17 @@ export function pluginActivation(plugin, { projectRoot } = {}) {
   const record = readActivationRecord(file, plugin.id);
   // Only a plugin owned by the shared (global) folder has an override to read:
   // a project's own copy already is that repository's setting.
-  const override = plugin.scope === 'global' && projectRoot ? projectActivationOverride(plugin.id, projectRoot).record : null;
+  const override = usesSharedPluginPolicy(plugin) && projectRoot ? projectActivationOverride(plugin.id, projectRoot).record : null;
   const applied = override?.runtime_enabled;
   const source = typeof applied === 'boolean' ? 'project' : 'shared';
   const shared = record?.runtime_enabled !== false;
   const enabled = plugin.valid === true && (typeof applied === 'boolean' ? applied : shared);
+  const localRecord = usesSharedPluginPolicy(plugin) ? override : record;
+  const onUse = !!projectRoot && localRecord?.runtime_on_use === true && localRecord.runtime_enabled === false;
   const runtime = plugin.manifest?.runtime || {};
   return {
     state: enabled ? 'active' : 'inactive', enabled, source,
+    ...(onUse ? { mode: 'on-use' } : {}),
     overridden: source === 'project' && applied !== shared,
     evidence: 'Host activation policy, not external process or provider health',
     hasRuntime: Boolean(plugin.manifest?.tasks?.length || Object.keys(runtime).length),
@@ -55,13 +64,13 @@ export function pluginExecutionEnabled(plugin, { projectRoot } = {}) {
   if (!/^[a-z][a-z0-9-]{1,63}$/.test(plugin.id)) throw new Error('Invalid plugin identity');
   const file = path.join(vaultForPluginsDir(pluginsDir), 'system', 'plugins', `${plugin.id}.md`);
   const record = readActivationRecord(file, plugin.id);
-  const override = plugin.scope === 'global' && projectRoot ? projectActivationOverride(plugin.id, projectRoot).record : null;
+  const override = usesSharedPluginPolicy(plugin) && projectRoot ? projectActivationOverride(plugin.id, projectRoot).record : null;
   const applied = override?.runtime_enabled;
   return typeof applied === 'boolean' ? applied : record?.runtime_enabled !== false;
 }
 
 /** Pure bootstrap read, avoiding configuration/kernel cycles; malformed existing policy fails closed. */
-export function readActivationRecord(file, id) {
+export function readActivationRecord(file, id, { withHash = false } = {}) {
   if (!file) return null;
   let stat;
   try { stat = fs.lstatSync(file); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
@@ -71,7 +80,12 @@ export function readActivationRecord(file, id) {
     const directory = fs.lstatSync(parent);
     if (!directory.isDirectory() || directory.isSymbolicLink()) throw new Error('Plugin policy cannot follow a linked vault path');
   }
-  const record = matter(fs.readFileSync(file, 'utf8')).data;
+  const bytes = fs.readFileSync(file);
+  const record = matter(bytes.toString('utf8')).data;
   if (record.type !== 'plugin_record' || record.plugin_id !== id || ['title', 'description', 'timestamp'].some(key => typeof record[key] !== 'string' || !record[key].trim()) || record.runtime_enabled !== undefined && typeof record.runtime_enabled !== 'boolean') throw new Error('Plugin policy is malformed; repair it before execution');
-  return record;
+  if (record.runtime_on_use !== undefined &&
+      (typeof record.runtime_on_use !== 'boolean' || (record.runtime_on_use && record.runtime_enabled !== false))) {
+    throw new Error('Plugin on-use policy is malformed; repair it before execution');
+  }
+  return withHash ? { record, hash: 'sha256:' + crypto.createHash('sha256').update(bytes).digest('hex') } : record;
 }

package/src/core/plugin-store.mjs

@@ -31,8 +31,8 @@ import {
 } from './plugin-bundle.mjs';
 import { writeVfsDocument, patchVfsDocument, deleteVfsDocument, appendVfsEvent } from './ssss-operation-service.mjs';
 import { findVfsDocumentByPath } from './vfs-documents.mjs';
-import { readActivationRecord, projectActivationOverride } from './plugin-state.mjs';
-import { REQUIRED_INSTALLATION_PLUGIN_IDS } from './default-plugins.mjs';
+import { readActivationRecord, projectActivationOverride, pluginActivation } from './plugin-state.mjs';
+import { DEFAULT_PLUGIN_IDS, REQUIRED_INSTALLATION_PLUGIN_IDS } from './default-plugins.mjs';
 
 const execFileAsync = promisify(execFile);
 const ID_PATTERN = /^[a-z][a-z0-9-]{1,63}$/;
@@ -183,7 +183,7 @@ export async function patchPluginRecord(plugin, patches) {
  * setting so it follows the shared one again. The overlay never installs the
  * plugin: a repository without it uses the shared folder's copy.
  */
-export async function patchProjectActivationRecord(id, projectRoot, runtimeEnabled, { manifest = null } = {}) {
+export async function patchProjectActivationRecord(id, projectRoot, runtimeEnabled, { manifest = null, onUse = false } = {}) {
   if (!ID_PATTERN.test(id)) throw new Error('Invalid plugin identity');
   const pluginsDir = projectPluginsDir(projectRoot);
   const vaultRoot = vaultForPluginsDir(pluginsDir);
@@ -194,7 +194,7 @@ export async function patchProjectActivationRecord(id, projectRoot, runtimeEnabl
   if (runtimeEnabled === null) {
     const existing = readProjectActivationRecord(id, projectRoot);
     if (!existing) return null;
-    const { runtime_enabled: _dropped, ...frontmatter } = { ...(existing.frontmatter || {}) };
+    const { runtime_enabled: _dropped, runtime_on_use: _onUse, ...frontmatter } = { ...(existing.frontmatter || {}) };
     await writeVfsDocument(recordPath(id), {
       ...frontmatter,
       type: 'plugin_record',
@@ -210,7 +210,7 @@ export async function patchProjectActivationRecord(id, projectRoot, runtimeEnabl
   if (typeof runtimeEnabled !== 'boolean') throw new Error('Plugin activation requires a boolean or null');
   const previous = readProjectActivationRecord(id, projectRoot);
   if (previous) {
-    return patchVfsDocument(recordPath(id), { runtime_enabled: runtimeEnabled, timestamp: now }, {
+    return patchVfsDocument(recordPath(id), { runtime_enabled: runtimeEnabled, runtime_on_use: onUse, timestamp: now }, {
       actorRole: 'system',
       intent: `Set repository activation for plugin ${id}`,
       vaultRoot
@@ -226,6 +226,7 @@ export async function patchProjectActivationRecord(id, projectRoot, runtimeEnabl
     category: 'plugins',
     tags: ['plugin', 'activation-override'],
     runtime_enabled: runtimeEnabled,
+    runtime_on_use: onUse,
     source: { kind: 'shared', ref: globalPluginsDir() }
   };
   await writeVfsDocument(recordPath(id), frontmatter, buildPluginDocumentBody(m, id), {
@@ -236,8 +237,19 @@ export async function patchProjectActivationRecord(id, projectRoot, runtimeEnabl
   return frontmatter;
 }
 
+function describeActivation(plugin, projectRoot) {
+  const required = REQUIRED_INSTALLATION_PLUGIN_IDS.includes(plugin.id);
+  try {
+    const { state, enabled, mode } = pluginActivation(plugin, { projectRoot });
+    return { state, enabled, required, ...(mode ? { mode } : {}) };
+  } catch {
+    // An unreadable repository policy is an error, never shared enablement.
+    return { state: 'error', enabled: false, required };
+  }
+}
+
 /** Facts about one installed plugin, merged with its record. */
-export function describePlugin(plugin) {
+export function describePlugin(plugin, projectRoot = process.cwd()) {
   const record = readPluginRecord(plugin);
   const m = plugin.manifest || {};
   let current = null;
@@ -248,6 +260,7 @@ export function describePlugin(plugin) {
   const taskRuns = record?.task_runs || {};
   return {
     id: plugin.id,
+    core: DEFAULT_PLUGIN_IDS.includes(plugin.id),
     name: m.name || plugin.id,
     version: m.version || '0.0.0',
     description: m.description || '',
@@ -284,13 +297,18 @@ export function describePlugin(plugin) {
     ui: m.ui || null,
     configuration: m.configuration || null,
     manifest: m,
-    card_face: record?.card_face || m.card_face || null,
-    activation: { state: plugin.valid && record?.runtime_enabled !== false ? 'active' : 'inactive', enabled: plugin.valid && record?.runtime_enabled !== false }
+    activation: describeActivation(plugin, projectRoot)
   };
 }
 
-export function listInstalledPlugins(projectRoot = process.cwd()) {
-  return discoverPlugins(projectRoot).map(describePlugin);
+export function listInstalledPlugins(projectRoot = process.cwd(), { descriptions } = {}) {
+  return discoverPlugins(projectRoot).map(plugin => {
+    const description = descriptions?.get(plugin.dir);
+    if (description) return { ...description, activation: describeActivation(plugin, projectRoot) };
+    const result = describePlugin(plugin, projectRoot);
+    descriptions?.set(plugin.dir, result);
+    return result;
+  });
 }
 
 /** Bundled plugins shipped in the package, flagged with whether they are installed here. */
@@ -344,7 +362,8 @@ export async function recompileAfterPluginMutation(projectRoot = process.cwd(),
     // read on demand at preflight, so a shared plugin change compiles no other repository
     // (ON-DEMAND-CONTEXT-01; one install used to rebuild all registered brains).
     await compileLayer(compileSurface, projectRoot, isGlobal);
-    if (isGlobal) {
+    // A shared change made from the dashboard's global brain has no repository to refresh.
+    if (isGlobal && projectRoot) {
       // The repository the command ran in refreshes its own catalog now, so its plugin library
       // never lags the change. That compile is cheap: entry files and vault indexes keep their
       // own triggers, so only the catalog and CLI index move.

package/src/core/project-id.mjs

@@ -7,6 +7,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
 function brainJsonPath(brainDir) {
   return path.join(brainDir, 'config', 'brain.json');
 }
@@ -35,21 +37,21 @@ export function readProjectId(brainDir) {
  * Return the project's id, creating a random UUID on first use.
  * @returns {{ project_id: string, created: boolean }}
  */
-export function ensureProjectId(brainDir) {
+export function ensureProjectId(brainDir, { fallbackId } = {}) {
   const file = brainJsonPath(brainDir);
   let cfg;
   try { cfg = JSON.parse(fs.readFileSync(file, 'utf8')); }
   catch (err) { if (err.code === 'ENOENT') cfg = {}; else throw new Error('Existing project identity is unreadable or malformed'); }
   if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) throw new Error('Existing project identity must be an object');
   if (cfg.project_id) return { project_id: cfg.project_id, created: false };
-  cfg.project_id = randomUUID();
+  cfg.project_id = fallbackId || randomUUID();
   writeJsonAtomic(file, cfg);
   return { project_id: cfg.project_id, created: true };
 }
 
 /**
- * Give every registered project an id and make the registry agree with each
- * project's brain.json (the brain.json id wins).
+ * Make the registry agree with each project's brain.json. If the disk identity
+ * is missing, preserve a unique valid UUID already published in the registry.
  * @returns {{ total: number, created: number, synced: number, missing_brain: number }}
  */
 export function repairProjectIds(globalBrainDir) {
@@ -57,13 +59,21 @@ export function repairProjectIds(globalBrainDir) {
   const list = readJson(registryPath, []);
   const out = { total: 0, created: 0, synced: 0, missing_brain: 0 };
   if (!Array.isArray(list)) return out;
+  const owners = new Map();
+  for (const row of list) {
+    const onDisk = typeof row?.brainDir === 'string' ? readProjectId(row.brainDir) : null;
+    for (const id of new Set([row?.project_id, onDisk])) {
+      if (typeof id === 'string' && UUID.test(id)) owners.set(id, (owners.get(id) || 0) + 1);
+    }
+  }
   for (const row of list) {
     out.total++;
     if (!row?.brainDir || !fs.existsSync(row.brainDir)) {
       out.missing_brain++;
       continue;
     }
-    const { project_id, created } = ensureProjectId(row.brainDir);
+    const fallbackId = owners.get(row.project_id) === 1 ? row.project_id : undefined;
+    const { project_id, created } = ensureProjectId(row.brainDir, { fallbackId });
     if (created) out.created++;
     if (row.project_id !== project_id) {
       row.project_id = project_id;