total-recall-brain 3.45.0 → 3.46.0

package/src/core/dashboard-bundle.mjs

@@ -0,0 +1,261 @@
+/**
+ * The dashboard bundle a source checkout serves, kept as new as its sources.
+ *
+ * The server used to build `frontend/dist` only when `index.html` was missing,
+ * and auto-pull rebuilt it only when a pull from origin changed `frontend/`.
+ * A local merge or commit refreshed nothing, so the served dashboard silently
+ * stayed on an old build: the plugin workspace drawers committed on
+ * 2026-11-08 never appeared at localhost:3000 because the bundle there was
+ * built on 2026-11-09 from code without them, and nothing ever looked again.
+ *
+ * Here "stale" has one definition, shared with the publish gate
+ * (`scripts/check-dist-freshness.mjs`): a source file newer than the newest
+ * bundle file. The server checks on start and on an interval, rebuilds in the
+ * background with the frontend's own build script, and keeps serving the
+ * current bundle until the new one is complete. It never installs
+ * dependencies: missing build tools are reported, not repaired behind the
+ * operator's back. An npm tarball gives every file the same mtime, so an
+ * installed package is never stale and never builds.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+const IGNORED_DIRS = new Set(['node_modules', '.git', 'dist']);
+
+/** Sources must be untouched this long before a rebuild, so a half-written edit is not built. */
+export const QUIET_MS = 60_000;
+export const CHECK_INTERVAL_MS = 5 * 60_000;
+export const BUILD_TIMEOUT_MS = 10 * 60_000;
+const OUTPUT_TAIL_BYTES = 4096;
+
+/**
+ * Newest mtime under a file or directory, and the path carrying it.
+ * Missing paths contribute nothing rather than failing: vite.config.ts and
+ * friends are allowed not to exist.
+ */
+export async function newestUnder(target) {
+  let info;
+  try {
+    info = await stat(target);
+  } catch {
+    return null;
+  }
+
+  if (info.isFile()) return { path: target, mtimeMs: info.mtimeMs };
+
+  let best = null;
+  const entries = await readdir(target, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory() && IGNORED_DIRS.has(entry.name)) continue;
+    const found = await newestUnder(path.join(target, entry.name));
+    if (found && (!best || found.mtimeMs > best.mtimeMs)) best = found;
+  }
+  return best;
+}
+
+/**
+ * Whether the built bundle can be trusted to represent the sources.
+ * Returns { ok, reason, bundle, source }; never throws, never prints, so the
+ * decision can be tested apart from how it is reported.
+ */
+export async function checkDistFreshness({ distDir, sourcePaths }) {
+  const bundle = await newestUnder(distDir);
+  if (!bundle) return { ok: false, reason: 'missing-bundle', bundle: null, source: null };
+
+  let source = null;
+  for (const candidate of sourcePaths) {
+    const found = await newestUnder(candidate);
+    if (found && (!source || found.mtimeMs > source.mtimeMs)) source = found;
+  }
+
+  if (source && source.mtimeMs > bundle.mtimeMs) {
+    return { ok: false, reason: 'stale-bundle', bundle, source };
+  }
+  return { ok: true, reason: 'current', bundle, source };
+}
+
+/** Every input whose change changes the built dashboard. */
+export function dashboardTargets(root) {
+  const frontend = path.join(root, 'frontend');
+  let tsconfigs = [];
+  try {
+    tsconfigs = fs.readdirSync(frontend).filter(name => /^tsconfig.*\.json$/.test(name)).map(name => path.join(frontend, name));
+  } catch { /* no frontend directory: nothing to compare */ }
+  return {
+    distDir: path.join(frontend, 'dist'),
+    sourcePaths: [
+      path.join(frontend, 'src'),
+      path.join(frontend, 'public'),
+      path.join(frontend, 'index.html'),
+      path.join(frontend, 'vite.config.ts'),
+      path.join(frontend, 'package.json'),
+      ...tsconfigs,
+    ],
+  };
+}
+
+/** The build script needs vite and the TypeScript compiler, hoisted to the root or local to the frontend. */
+export function buildToolsPresent(root) {
+  const frontend = path.join(root, 'frontend');
+  const has = rel => [root, frontend].some(dir => fs.existsSync(path.join(dir, 'node_modules', rel)));
+  return fs.existsSync(path.join(frontend, 'package.json')) && has(path.join('vite', 'bin', 'vite.js')) && has(path.join('typescript', 'bin', 'tsc'));
+}
+
+/** npm installed beside the running node (Homebrew, nvm, system installs), else from PATH. */
+function npmBinary() {
+  const beside = path.join(path.dirname(process.execPath), process.platform === 'win32' ? 'npm.cmd' : 'npm');
+  return fs.existsSync(beside) ? beside : 'npm';
+}
+
+/**
+ * Run the frontend's own `build` script into `outDir`. npm appends the
+ * arguments after `--` to the script, so they reach `vite build`.
+ * @returns {Promise<{ code: number|null, output: string, timedOut: boolean }>}
+ */
+export function runFrontendBuild({ frontendDir, outDir, timeoutMs = BUILD_TIMEOUT_MS }) {
+  return new Promise(resolve => {
+    let output = '';
+    let timedOut = false;
+    const keep = chunk => { output = (output + chunk).slice(-OUTPUT_TAIL_BYTES); };
+    const env = { ...process.env, PATH: [path.dirname(process.execPath), process.env.PATH].filter(Boolean).join(path.delimiter) };
+    let child;
+    try {
+      child = spawn(npmBinary(), ['run', 'build', '--', '--outDir', outDir, '--emptyOutDir'], {
+        cwd: frontendDir, env, stdio: ['ignore', 'pipe', 'pipe'], shell: process.platform === 'win32', detached: process.platform !== 'win32',
+      });
+    } catch (error) {
+      resolve({ code: null, output: error.message, timedOut: false });
+      return;
+    }
+    child.stdout.on('data', keep);
+    child.stderr.on('data', keep);
+    const timer = setTimeout(() => {
+      timedOut = true;
+      // The build runs in its own process group: end tsc and vite with npm.
+      try { process.kill(-child.pid, 'SIGTERM'); } catch { child.kill('SIGTERM'); }
+    }, timeoutMs);
+    timer.unref?.();
+    child.on('error', error => { clearTimeout(timer); resolve({ code: null, output: `${output}\n${error.message}`.trim(), timedOut }); });
+    child.on('close', code => { clearTimeout(timer); resolve({ code, output, timedOut }); });
+  });
+}
+
+function processAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; }
+}
+
+/**
+ * Hold the build lock, or report who holds it. A lock left by a process that
+ * no longer exists is reclaimed once.
+ */
+function acquireLock(file) {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = fs.openSync(file, 'wx', 0o600);
+      fs.writeSync(fd, `${process.pid}\n`);
+      fs.closeSync(fd);
+      return { held: true, release: () => { try { if (Number(fs.readFileSync(file, 'utf8').trim()) === process.pid) fs.unlinkSync(file); } catch { /* already gone */ } } };
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const owner = Number(String(fs.readFileSync(file, 'utf8')).trim());
+      if (processAlive(owner)) return { held: false, owner };
+      fs.rmSync(file, { force: true });
+    }
+  }
+  return { held: false, owner: null };
+}
+
+/**
+ * Build the dashboard beside the served one and swap it in. The served bundle
+ * stays in place until the new one is complete; a failed build leaves it
+ * untouched.
+ * @returns {Promise<{ ok: boolean, status: string, reason?: string, durationMs?: number, output?: string }>}
+ */
+export async function rebuildDashboard({ root, run = runFrontendBuild, timeoutMs = BUILD_TIMEOUT_MS } = {}) {
+  const frontendDir = path.join(root, 'frontend');
+  const dist = path.join(frontendDir, 'dist');
+  const next = path.join(frontendDir, 'dist.next');
+  const prev = path.join(frontendDir, 'dist.prev');
+  const lock = acquireLock(path.join(frontendDir, '.dist-build.lock'));
+  if (!lock.held) return { ok: false, status: 'building-elsewhere', reason: `another process (pid ${lock.owner ?? 'unknown'}) is building the dashboard` };
+  const started = Date.now();
+  try {
+    fs.rmSync(next, { recursive: true, force: true });
+    const result = await run({ frontendDir, outDir: next, timeoutMs });
+    const built = result.code === 0 && !result.timedOut && fs.existsSync(path.join(next, 'index.html'));
+    if (!built) {
+      fs.rmSync(next, { recursive: true, force: true });
+      const reason = result.timedOut ? `build timed out after ${Math.round(timeoutMs / 1000)} s`
+        : result.code === 0 ? 'build finished without index.html' : `build exited ${result.code ?? 'without a status'}`;
+      return { ok: false, status: 'failed', reason, durationMs: Date.now() - started, output: result.output };
+    }
+    // Two renames: the served directory is absent only between them.
+    fs.rmSync(prev, { recursive: true, force: true });
+    const hadDist = fs.existsSync(dist);
+    if (hadDist) fs.renameSync(dist, prev);
+    try {
+      fs.renameSync(next, dist);
+    } catch (error) {
+      if (hadDist) fs.renameSync(prev, dist);
+      throw error;
+    }
+    fs.rmSync(prev, { recursive: true, force: true });
+    return { ok: true, status: 'built', durationMs: Date.now() - started };
+  } finally {
+    lock.release();
+  }
+}
+
+/**
+ * Check once and rebuild when needed. Returns the state to report and, when
+ * the sources are still being edited, how long to wait before checking again.
+ */
+export async function refreshDashboard({ root, now = Date.now, quietMs = QUIET_MS, rebuild = rebuildDashboard, toolsPresent = buildToolsPresent } = {}) {
+  const freshness = await checkDistFreshness(dashboardTargets(root));
+  if (freshness.ok) return { status: 'current', bundleBuiltAt: new Date(freshness.bundle.mtimeMs).toISOString() };
+  const state = freshness.reason === 'missing-bundle' ? 'missing' : 'stale';
+  if (!toolsPresent(root)) {
+    return { status: state, reason: `the build tools are not installed; run npm ci in ${root}`, source: freshness.source?.path ?? null };
+  }
+  if (freshness.source && now() - freshness.source.mtimeMs < quietMs) {
+    return { status: state, reason: 'sources are still changing', source: freshness.source.path, retryInMs: quietMs - (now() - freshness.source.mtimeMs) + 1000 };
+  }
+  const build = await rebuild({ root });
+  if (build.ok) return { status: 'current', rebuilt: true, durationMs: build.durationMs, was: state };
+  return { status: state, reason: build.reason, build };
+}
+
+/**
+ * Keep a serving checkout's bundle current: check now, after the sources go
+ * quiet, and every `intervalMs`. `report` receives each state change.
+ * @returns {{ state: () => object, check: () => Promise<object>, stop: () => void }}
+ */
+export function watchDashboardBundle({ root, report = () => {}, intervalMs = CHECK_INTERVAL_MS, refresh = refreshDashboard } = {}) {
+  let current = { status: 'unchecked' };
+  let running = null;
+  let retry = null;
+  let lastKey = '';
+  const check = () => {
+    if (running) return running;
+    running = (async () => {
+      try {
+        current = { ...await refresh({ root }), checkedAt: new Date().toISOString() };
+      } catch (error) {
+        current = { status: 'error', reason: error.message, checkedAt: new Date().toISOString() };
+      }
+      const key = `${current.status}|${current.reason ?? ''}|${current.rebuilt ?? ''}`;
+      if (key !== lastKey || current.rebuilt) report(current);
+      lastKey = key;
+      clearTimeout(retry);
+      if (current.retryInMs) { retry = setTimeout(check, current.retryInMs); retry.unref?.(); }
+      return current;
+    })().finally(() => { running = null; });
+    return running;
+  };
+  const interval = setInterval(check, intervalMs);
+  interval.unref?.();
+  return { state: () => current, check, stop: () => { clearInterval(interval); clearTimeout(retry); } };
+}

package/src/core/ensure-dependencies.mjs

@@ -22,25 +22,29 @@ const RUNNING_PACKAGE_ROOT = (() => {
 })();
 
 /**
- * npm records the tree it installed in node_modules/.package-lock.json. The tree matches the
- * lockfile when every installed package has the locked version and every required locked package
- * is installed (optional packages may be absent on this platform; workspace links are not copies).
+ * The tree matches the lockfile when every locked package is on disk at its locked version
+ * (optional packages may be absent on this platform; workspace links are not copies; an absent
+ * peer is npm's call). It reads each package's own package.json, never npm's record of the tree
+ * (node_modules/.package-lock.json): `npm install --package-lock-only`, which the brain updater
+ * runs, rewrites that record to the new versions without installing them. On 2026-11-12 21 linked
+ * plugins held @ssss/cli 0.14.4 under a record and lock that both said 0.14.5, so every check that
+ * trusted the record, and npm itself, reported the stale tree as current.
  */
 export function npmTreeMatchesLock(root) {
-  let lock, installed;
-  try {
-    lock = JSON.parse(fs.readFileSync(path.join(root, 'package-lock.json'), 'utf8')).packages;
-    installed = JSON.parse(fs.readFileSync(path.join(root, 'node_modules', '.package-lock.json'), 'utf8')).packages;
-  } catch { return false; }
-  if (!lock || !installed) return false;
-  for (const [key, entry] of Object.entries(installed)) {
-    if (!key || entry.link) continue;
-    if (!lock[key] || lock[key].version !== entry.version) return false;
-  }
+  let lock;
+  try { lock = JSON.parse(fs.readFileSync(path.join(root, 'package-lock.json'), 'utf8')).packages; }
+  catch { return false; }
+  if (!lock || !fs.existsSync(path.join(root, 'node_modules'))) return false;
   for (const [key, entry] of Object.entries(lock)) {
     if (!key.startsWith('node_modules/') && !key.includes('/node_modules/')) continue;
-    if (entry.optional || entry.link || entry.peer) continue;
-    if (!installed[key]) return false;
+    if (entry.optional || entry.link) continue;
+    let version;
+    try { version = JSON.parse(fs.readFileSync(path.join(root, key, 'package.json'), 'utf8')).version; }
+    catch {
+      if (entry.peer) continue;
+      return false;
+    }
+    if (entry.version && version !== entry.version) return false;
   }
   return true;
 }

package/src/core/memory-brain.mjs

@@ -5,6 +5,7 @@ import { writeFileSecure } from './secure-file.mjs';
 import { ensureProjectId } from './project-id.mjs';
 
 function ensureDir(dir) { fs.mkdirSync(dir, { recursive: true }); }
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 
 export const VAULT_CATEGORIES = Object.freeze([
   'invariants',
@@ -18,17 +19,33 @@ export const VAULT_CATEGORIES = Object.freeze([
   'lore',
 ]);
 
+function readBrainConfig(file) {
+  let current;
+  try { current = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (error) {
+    if (error.code === 'ENOENT') return {};
+    throw error;
+  }
+  if (!current || typeof current !== 'object' || Array.isArray(current)) {
+    throw new Error('Existing brain identity must be an object');
+  }
+  return current;
+}
+
+/** Update connection settings without replacing the existing brain identity. */
+export function writeBrainConnection(brainDir, fields) {
+  const file = path.join(brainDir, 'config', 'brain.json');
+  const current = readBrainConfig(file);
+  ensureDir(path.dirname(file));
+  writeFileSecure(file, JSON.stringify({ ...current, ...fields }, null, 2), { encoding: 'utf8', mode: 0o600 });
+  return file;
+}
+
 export function writeBrainIdentity(brainDir, { name, role = 'project', tags = [] } = {}) {
   const configDir = path.join(brainDir, 'config');
   ensureDir(configDir);
   const brainJsonPath = path.join(configDir, 'brain.json');
-  let current = {};
-  if (fs.existsSync(brainJsonPath)) {
-    current = JSON.parse(fs.readFileSync(brainJsonPath, 'utf8'));
-    if (!current || typeof current !== 'object' || Array.isArray(current)) {
-      throw new Error('Existing brain identity must be an object');
-    }
-  }
+  const current = readBrainConfig(brainJsonPath);
   const next = {
     ...current,
     name: name || current.name || path.basename(path.resolve(brainDir, '../../..')),
@@ -54,12 +71,17 @@ export function registerProjectBrain(globalBrainDir, entry) {
 
   const abs = path.resolve(entry.path);
   const idx = list.findIndex((p) => path.resolve(p.path || '') === abs);
+  const existing = list[idx];
+  const candidateId = existing?.project_id;
+  const fallbackId = typeof candidateId === 'string' && UUID.test(candidateId) &&
+    existing.brainDir === entry.brainDir && list.filter(record => record.project_id === candidateId).length === 1
+    ? candidateId : undefined;
   const now = new Date().toISOString();
   const row = {
     name: entry.name,
     path: abs,
     brainDir: entry.brainDir,
-    project_id: ensureProjectId(entry.brainDir).project_id,
+    project_id: ensureProjectId(entry.brainDir, { fallbackId }).project_id,
     full_brain: true,
     layer: 'project',
     tags: entry.tags || ['project-brain'],

package/src/core/plugin-activation.mjs

@@ -1,7 +1,10 @@
 /** Host activation policy; never pretends a provider or external daemon is healthy. */
-import { getPlugin } from './plugin-loader.mjs';
-import { patchPluginRecord, patchProjectActivationRecord, emit, vaultFor, recompileAfterPluginMutation } from './plugin-store.mjs';
-import { pluginActivation } from './plugin-state.mjs';
+import path from 'node:path';
+import { getPlugin, globalPluginsDir, projectPluginsDir, vaultForPluginsDir } from './plugin-loader.mjs';
+import { patchPluginRecord, patchProjectActivationRecord, recordPath, emit, vaultFor, recompileAfterPluginMutation } from './plugin-store.mjs';
+import { patchVfsDocument } from './ssss-operation-service.mjs';
+import { pluginActivation, readActivationRecord, usesSharedPluginPolicy } from './plugin-state.mjs';
+import { moveRepositoryPluginState, withRepositoryPluginLifecycle } from './plugin-lifecycle.mjs';
 import { REQUIRED_INSTALLATION_PLUGIN_IDS } from './default-plugins.mjs';
 export { pluginActivation };
 
@@ -14,38 +17,78 @@ export { pluginActivation };
  * following the shared setting (`clear: true`).
  */
 export async function setPluginActive(id, enabled, { projectRoot = process.cwd(), scope = 'project', clear = false } = {}) {
-  if (enabled === false && REQUIRED_INSTALLATION_PLUGIN_IDS.includes(id)) {
+  const onUse = enabled === 'on-use';
+  if (onUse && (scope !== 'project' || !projectRoot || projectPluginsDir(projectRoot) === globalPluginsDir() || clear)) {
+    throw new Error('On use is available for individual repository brains.');
+  }
+  if ((enabled === false || onUse) && REQUIRED_INSTALLATION_PLUGIN_IDS.includes(id)) {
     throw new Error('Required plugin ' + id + ' cannot be disabled');
   }
   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 });
+    await withRepositoryPluginLifecycle(projectRoot, id, async brain => {
+      if (!usesSharedPluginPolicy(plugin) || pluginActivation(plugin, { projectRoot: null }).enabled) {
+        moveRepositoryPluginState(brain, id, 'restore');
+      }
+      await patchProjectActivationRecord(id, projectRoot, null);
+      await emit(vaultForPluginsDir(projectPluginsDir(projectRoot)), id, 'activation-cleared', {});
+    });
     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');
+  if (onUse) enabled = false;
+  if (typeof enabled !== 'boolean') throw new Error('Plugin activation requires a boolean or On use');
   const plugin = getPlugin(id, projectRoot);
   if (!plugin?.valid) throw new Error(`Plugin ${id} is missing or invalid`);
   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 });
+    if (!usesSharedPluginPolicy(plugin)) throw new Error(`Plugin ${id} is a ${plugin.scope} copy without a shared setting to change`);
+    await patchPluginRecord(plugin, { runtime_enabled: enabled, runtime_on_use: false });
     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 event = onUse ? 'activation-on-use' : enabled ? 'activated' : 'deactivated';
+  const shared = usesSharedPluginPolicy(plugin);
+  const resultScope = shared ? 'project' : plugin.scope;
+  const vaultRoot = shared ? vaultForPluginsDir(projectPluginsDir(projectRoot)) : vaultFor(plugin);
+  const cleanup = await withRepositoryPluginLifecycle(projectRoot, id, async brain => {
+    if (onUse && !brain) throw new Error('On use is available for individual repository brains.');
+    let result = enabled ? moveRepositoryPluginState(brain, id, 'restore') : undefined;
+    if (shared) await patchProjectActivationRecord(id, projectRoot, enabled, { manifest: plugin.manifest, onUse });
+    else await patchPluginRecord(plugin, { runtime_enabled: enabled, runtime_on_use: onUse });
+    if (!enabled && !onUse) {
+      try { result = moveRepositoryPluginState(brain, id, 'archive'); }
+      catch (error) {
+        result = { ok: false, state: 'pending', error: error.code ? `Could not archive repository plugin state (${error.code}).` : error.message };
+      }
+    }
+    await emit(vaultRoot, id, event, { enabled, scope: resultScope, ...(result ? { cleanup: result.state } : {}) });
+    return result;
+  });
+  const compilation = await recompileAfterPluginMutation(projectRoot, false);
+  return { pluginId: id, activation: pluginActivation(plugin, { projectRoot }), scope: resultScope, compilation, ...(cleanup ? { cleanup } : {}) };
+}
+
+/** Claim one armed project policy through the SSSS compare-and-set writer. */
+export async function activatePluginOnUse(id, { projectRoot = process.cwd() } = {}) {
+  if (!projectRoot || projectPluginsDir(projectRoot) === globalPluginsDir()) return null;
+  const plugin = getPlugin(id, projectRoot);
+  if (!plugin?.valid || pluginActivation(plugin, { projectRoot }).mode !== 'on-use') return null;
+  const vaultRoot = usesSharedPluginPolicy(plugin) ? vaultForPluginsDir(projectPluginsDir(projectRoot)) : vaultFor(plugin);
+  const cleanup = await withRepositoryPluginLifecycle(projectRoot, id, async brain => {
+    if (!brain) return null;
+    const current = readActivationRecord(path.join(vaultRoot, recordPath(id)), id, { withHash: true });
+    if (current?.record.runtime_on_use !== true) return null;
+    const result = moveRepositoryPluginState(brain, id, 'restore');
+    await patchVfsDocument(recordPath(id), { runtime_enabled: true, runtime_on_use: false, timestamp: new Date().toISOString() }, {
+      vaultRoot, expectedBeforeHash: current.hash, intent: 'Activate plugin on deliberate use',
+    });
+    await emit(vaultRoot, id, 'activated-on-use', { enabled: true, scope: 'project', cleanup: result.state });
+    return result;
+  });
+  if (!cleanup) return null;
   const compilation = await recompileAfterPluginMutation(projectRoot, false);
-  return { pluginId: id, activation: pluginActivation(plugin, { projectRoot }), scope: 'project', compilation };
+  return { pluginId: id, activation: pluginActivation(plugin, { projectRoot }), scope: 'project', compilation, cleanup };
 }

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;