total-recall-brain 3.45.0 → 3.46.1

package/src/core/plugin-contracts/{card.mjs → manifest.mjs}

@@ -1,15 +1,4 @@
-/**
- * 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.
- */
+/** Cross-field validation for plugin manifests and their command contracts. */
 const plain = (v) => v && typeof v === 'object' && !Array.isArray(v);
 const COMMAND = /^[a-z][a-z0-9-]{0,63}$/;
 const ARG_NAME = /^[a-z][a-zA-Z0-9]{0,63}$/;
@@ -19,11 +8,10 @@ export const COMMAND_EFFECTS = ['read', 'write', 'destructive', 'send'];
 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_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'];
+const BRAND_FONTS = ['system', 'inter', 'ibm-plex', 'space-grotesk', 'jetbrains-mono', 'dm-sans', 'outfit', 'fraunces', 'newsreader', 'chivo-mono'];
+const BRAND_DENSITIES = ['compact', 'comfortable', 'spacious'];
+const BRAND_RADII = ['none', 'sm', 'md', 'lg', 'pill'];
+const BRAND_HEADERS = ['plain', 'ledger-rule', 'band', 'tab-strip', 'badge-left'];
 export const WORKSPACE_PERMISSIONS = ['microphone', 'camera', 'notifications'];
 const HEX = /^#[0-9a-fA-F]{6}$/;
 
@@ -41,7 +29,7 @@ function validateArg(arg, where, errors) {
   if (arg.secret === true && arg.type !== 'string') errors.push(`${where}: a secret stdin argument must be a string`);
 }
 
-export function validateCardContract(manifest) {
+export function validateManifestContract(manifest) {
   const errors = [];
   const warnings = [];
   const subs = manifest.cli?.subcommands;
@@ -55,6 +43,13 @@ export function validateCardContract(manifest) {
       else names.add(sub.name);
       if (sub.effect !== undefined && !COMMAND_EFFECTS.includes(sub.effect)) errors.push(`${where}.effect must be one of: ${COMMAND_EFFECTS.join(', ')}`);
       if (sub.output !== undefined && !OUTPUT_KINDS.includes(sub.output)) errors.push(`${where}.output must be one of: ${OUTPUT_KINDS.join(', ')}`);
+      const terminalFlags = sub.terminal_only_args;
+      if (sub.terminal_only !== undefined && typeof sub.terminal_only !== 'boolean') errors.push(`${where}.terminal_only must be a boolean`);
+      if (terminalFlags !== undefined && (!Array.isArray(terminalFlags) ||
+          terminalFlags.some(flag => typeof flag !== 'string' || !FLAG.test(flag)) ||
+          new Set(terminalFlags).size !== terminalFlags.length)) {
+        errors.push(`${where}.terminal_only_args must contain unique long flags`);
+      }
       // The runner refuses anything outside this range, so a manifest that
       // declares it must fail validation rather than every call at run time.
       if (sub.timeout_ms !== undefined && (!Number.isInteger(sub.timeout_ms) || sub.timeout_ms < 1 || sub.timeout_ms > 600000)) errors.push(`${where}.timeout_ms must be an integer from 1 to 600000`);
@@ -91,7 +86,7 @@ export function validateCardContract(manifest) {
       if (!LICENSE_CLASSES.includes(manifest.distribution.license)) errors.push(`'distribution.license' must be one of: ${LICENSE_CLASSES.join(', ')}`);
     }
   }
-  validateCardFace(manifest, errors, warnings);
+  validatePresentation(manifest, errors, warnings);
   validateBranding(manifest.branding, errors, warnings);
   validateWorkspace(manifest.workspace, errors);
   if (Array.isArray(manifest.secrets)) {
@@ -99,30 +94,15 @@ export function validateCardContract(manifest) {
       if (!plain(s) || typeof s.key !== 'string' || !/^[A-Z][A-Z0-9_]{0,63}$/.test(s.key)) errors.push(`secrets[${i}].key must be an uppercase identifier`);
     });
   }
-  if (plain(manifest.card_face) && Array.isArray(manifest.card_face.metrics)) {
-    warnings.push("card_face.metrics are fixed text and cannot reflect real state; declare a 'status' command instead");
-  }
-  return { errors, warnings, states: STATUS_STATES };
+  return { errors, warnings };
 }
 
-/**
- * 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");
+function validatePresentation(manifest, errors, warnings) {
+  for (const field of ['card', 'card_face', 'card_layout']) {
+    if (manifest[field] !== undefined) errors.push(`'${field}' is not supported: declare a native ui.home instead`);
   }
   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.
+  // A brick is distributed as capability code alone and has no UI.
   if (manifest.brick === true) {
     validateCapability(manifest, errors);
     if (manifest.ui !== undefined && Array.isArray(elements) && elements.length > 0) {
@@ -131,23 +111,9 @@ function validateCardFace(manifest, errors, warnings) {
     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;
-    }
-    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'");
+  if (manifest.ui?.home !== undefined) return;
+  if (manifest.scaffold === true) warnings.push("Scaffold needs an owner-authored 'ui.home' and DESIGN.md before shipping");
+  else errors.push("A plugin must declare a native 'ui.home'");
 }
 
 /**
@@ -188,7 +154,7 @@ function validateBranding(branding, errors, warnings) {
   if (branding.icon !== undefined) {
     warnings.push('branding.icon is deprecated: show the real logo with branding.logo instead of an emoji or generic icon');
   }
-  const enums = { font: CARD_FONTS, density: CARD_DENSITIES, radius: CARD_RADII, header: CARD_HEADERS };
+  const enums = { font: BRAND_FONTS, density: BRAND_DENSITIES, radius: BRAND_RADII, header: BRAND_HEADERS };
   for (const [key, allowed] of Object.entries(enums)) {
     const value = branding[key];
     if (value === undefined || allowed.includes(value)) continue;

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;
 }