total-recall-brain 3.45.0 → 3.46.1

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/default-plugin-refresh.mjs

@@ -0,0 +1,39 @@
+/**
+ * A release that changes the plugin contract refuses the shared default plugins the previous release
+ * installed, and with them every command that loads one, `update` included: the very command that would
+ * replace them. So a machine moving to such a release could not update itself. When a command fails that
+ * way, refresh the defaults from this package's bundled copies (a link is its owner's checkout and is left
+ * alone) and run the command again, once.
+ */
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { ensureRequiredPlugins } from './required-plugins.mjs';
+import { globalPluginsDir } from './plugin-loader.mjs';
+
+const REFUSAL = /\bRequired (?:plugin [\w-]+|[\w-]+ plugin) is missing or invalid\b/;
+export const REFRESHED_ENV = 'TR_DEFAULT_PLUGINS_REFRESHED';
+
+export function isDefaultPluginRefusal(error) {
+  return REFUSAL.test(String(error?.message || ''));
+}
+
+/** Returns the rerun's exit status, or null when this error is not one a refresh can fix. */
+export function rerunAfterDefaultRefresh(error, {
+  env = process.env, argv = process.argv, execPath = process.execPath, ensure = ensureRequiredPlugins,
+  sharedBrainDir = path.dirname(globalPluginsDir()), run = spawnSync, log = (line) => console.error(line),
+} = {}) {
+  if (!isDefaultPluginRefusal(error) || env[REFRESHED_ENV] === '1') return null;
+  try {
+    ensure(sharedBrainDir, { sharedBrainDir });
+  } catch (refreshError) {
+    log(`The default plugins could not be refreshed from this release: ${refreshError.message}`);
+    return null;
+  }
+  log('Refreshed the default plugins from this release; running the command again.');
+  const result = run(execPath, argv.slice(1), { stdio: 'inherit', env: { ...env, [REFRESHED_ENV]: '1' } });
+  if (result.error) {
+    log(`The command could not be run again: ${result.error.message}`);
+    return 1;
+  }
+  return result.status ?? 1;
+}

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