total-recall-brain 3.44.0 → 3.46.0

package/src/core/lessons.mjs

@@ -0,0 +1,96 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { atomicWrite } from './vault.mjs';
+import { addTask, getTask, resolveQueueDir } from './task-envelope.mjs';
+import { readLessonEntries, countLessonTurns, selectLessonTurns } from './lesson-sessions.mjs';
+import { acquireBrainUpdateLock } from './brain-updates.mjs';
+
+export const DEFAULT_LESSON_INTERVAL = 10;
+const hash = value => crypto.createHash('sha256').update(value).digest('hex').slice(0, 12);
+
+/** A local hook only queues work. It never calls a model or elects a leader. */
+export function tickLessons({ brainDir, sessionId, transcriptPath, event = 'Stop', interval,
+  turnId, turnCount, harness = 'unknown', hold } = {}) {
+  if (!brainDir || !sessionId) throw new Error('Lesson review requires a brain and session id');
+  const sessionsDir = path.join(brainDir, 'sessions');
+  const configPath = path.join(brainDir, 'config', 'lessons.json');
+  if (fs.existsSync(configPath)) {
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    if (config.enabled === false) return { tasks: [], skipped: 'disabled' };
+    interval ??= config.interval;
+    if (hold === undefined) hold = config.holdWrites === true;
+  }
+  interval ??= DEFAULT_LESSON_INTERVAL;
+  if (!Number.isInteger(interval) || interval < 1) throw new Error('Lesson interval must be a positive integer');
+  hold ??= false;
+  const root = path.join(brainDir, 'lesson-reviews');
+  fs.mkdirSync(root, { recursive: true });
+  // Match writeSession's identity so native hooks and later ingest share a cursor.
+  const localTranscript = transcriptPath && path.dirname(path.resolve(transcriptPath)) === path.resolve(sessionsDir);
+  const key = transcriptPath ? (localTranscript ? path.basename(transcriptPath, '.jsonl') : hash(path.resolve(transcriptPath))) : hash(`${harness}:${sessionId}`);
+  const lock = path.join(root, `${key}.lock`);
+  const lockFd = acquireBrainUpdateLock(lock, { waitMs: 0 });
+  try {
+    const stateFile = path.join(root, `${key}.json`);
+    const state = fs.existsSync(stateFile) ? JSON.parse(fs.readFileSync(stateFile, 'utf8')) : { turns: 0, queuedThrough: 0 };
+    let entries;
+    const savedTranscript = path.join(sessionsDir, `${key}.jsonl`);
+    if (!transcriptPath && fs.existsSync(savedTranscript)) transcriptPath = savedTranscript;
+    if (transcriptPath) {
+      entries = readLessonEntries(transcriptPath);
+      turnCount = countLessonTurns(entries);
+      if (!localTranscript) {
+        fs.mkdirSync(sessionsDir, { recursive: true });
+        atomicWrite(path.join(sessionsDir, `${key}.jsonl`), entries.map(entry => JSON.stringify(entry)).join('\n') + '\n');
+      }
+    }
+    if (turnCount !== undefined) {
+      if (!Number.isInteger(turnCount) || turnCount < state.turns) throw new Error('Lesson transcript turn count went backwards');
+      state.turns = turnCount;
+    } else if (event === 'UserPromptSubmit' && (!turnId || turnId !== state.lastTurnId)) {
+      state.turns++;
+      state.lastTurnId = turnId;
+    }
+    const final = event === 'SessionEnd' || event === 'session-end';
+    const tasks = [];
+    // Prompt hooks count only. Stop has the completed response and tool results.
+    if (event !== 'UserPromptSubmit' && entries) {
+      while (state.turns - state.queuedThrough >= interval || (final && state.turns > state.queuedThrough)) {
+        const fromTurn = state.queuedThrough + 1;
+        const toTurn = Math.min(state.turns, state.queuedThrough + interval);
+        const slug = `lesson-review-${key}-${fromTurn}-${toTurn}`;
+        const queueDir = resolveQueueDir(brainDir);
+        if (!getTask(queueDir, slug) && !fs.existsSync(path.join(root, `${slug}.done`))) {
+          const snapshot = path.join(root, `${slug}.jsonl`);
+          atomicWrite(snapshot, selectLessonTurns(entries, { fromTurn, toTurn }).map(entry => JSON.stringify(entry)).join('\n') + '\n');
+          addTask({ slug, intent: `Review session ${sessionId}, turns ${fromTurn}–${toTurn}`,
+            kind: 'memory', executor: 'lesson-review', category: 'lesson-review', priority: 40,
+            origin: { agent: harness, session_id: sessionId },
+            payload: { sessionPath: snapshot, fromTurn, toTurn, hold, sessionId },
+          }, queueDir);
+        }
+        tasks.push(slug);
+        state.queuedThrough = toTurn;
+      }
+    }
+    atomicWrite(stateFile, JSON.stringify(state));
+    return { turns: state.turns, queuedThrough: state.queuedThrough, tasks };
+  } finally {
+    // Remove only the inode this process acquired. A dead hook's lock is reclaimed
+    // by the shared lock owner on the next tick.
+    try { if (fs.statSync(lock).ino === fs.fstatSync(lockFd).ino) fs.unlinkSync(lock); }
+    finally { fs.closeSync(lockFd); }
+  }
+}
+
+/** Session-ingest fallback for harnesses without a lifecycle hook. Every node calls this. */
+export function enqueueSessionReviews({ brainDir, now = Date.now(), quietMs = 5 * 60_000, interval, hold } = {}) {
+  const dir = path.join(brainDir, 'sessions');
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter(name => name.endsWith('.jsonl')).map(name => {
+    const transcriptPath = path.join(dir, name);
+    return tickLessons({ brainDir, sessionId: path.basename(name, '.jsonl'), transcriptPath, interval, hold,
+      event: now - fs.statSync(transcriptPath).mtimeMs >= quietMs ? 'SessionEnd' : 'Stop', harness: 'session-ingest' });
+  });
+}

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/meta-harness.mjs

@@ -1,11 +1,11 @@
-/** Compatibility facade only. Adapter contracts, auth, usage and execution belong to Meta Harness. */
+/** Compatibility facade only. Adapter contracts, auth, usage and execution belong to Metaharness. */
 import { loadPluginModule } from './plugin-runtime.mjs';
 
 let owner, ownerError;
 try { owner = await loadPluginModule('meta-harness', 'harness-compat'); }
 catch (error) { ownerError = error; }
 function implementation() {
-  if (!owner) throw new Error(`Meta Harness is unavailable: ${ownerError?.message || 'install the plugin'}`);
+  if (!owner) throw new Error(`Metaharness is unavailable: ${ownerError?.message || 'install the plugin'}`);
   return owner;
 }
 

package/src/core/optimizer.mjs

@@ -4,8 +4,8 @@ import crypto from 'crypto';
 import matter from './frontmatter.mjs';
 import { writeNode } from './vault.mjs';
 import { getNodes } from './vault-cache.mjs';
+import { readAccess, lastUsedMs, activeDaysSince } from './access-ledger.mjs';
 import { logger } from './logger.mjs';
-import { brainDir } from './config.mjs';
 
 /**
  * Total Recall Optimizer
@@ -166,129 +166,6 @@ export async function generateMemoryCleanupProposals(vaultDir) {
   return proposals;
 }
 
-/**
- * Scans skill execution logs (if available) and proposes improvements.
- */
-/**
- * Scan skill files for quality issues and propose improvements.
- * Looks at skill files that haven't been updated in >30 days and
- * checks for common issues: missing examples, vague instructions, outdated commands.
- */
-export async function generateSkillImprovementProposals(vaultDir) {
-  const agentDir = path.join(path.dirname(vaultDir));
-  const skillsDir = path.join(agentDir, 'skills');
-  const proposals = [];
-
-  if (!fs.existsSync(skillsDir)) return proposals;
-
-  const now = Date.now();
-  const staleCutoff = 30 * 24 * 60 * 60 * 1000; // 30 days
-
-  try {
-    const skillDirs = fs.readdirSync(skillsDir, { withFileTypes: true })
-      .filter(d => d.isDirectory())
-      .map(d => path.join(skillsDir, d.name, 'SKILL.md'))
-      .filter(p => fs.existsSync(p));
-
-    for (const skillFile of skillDirs) {
-      const stat = fs.statSync(skillFile);
-      const ageMs = now - stat.mtimeMs;
-      if (ageMs < staleCutoff) continue;
-
-      const raw = fs.readFileSync(skillFile, 'utf8');
-      const hasExamples = /##\s*example/i.test(raw);
-      const hasCaution = /caution|warning|never|must not/i.test(raw);
-      const lineCount = raw.split('\n').length;
-
-      const issues = [];
-      if (!hasExamples) issues.push('No examples section');
-      if (!hasCaution) issues.push('No caution/constraint section');
-      if (lineCount < 20) issues.push('Very short — may lack detail');
-
-      if (issues.length > 0) {
-        const skillName = path.basename(path.dirname(skillFile));
-        proposals.push(createProposal(
-          'skill-improvement',
-          `Improve skill: ${skillName} (${issues.join(', ')})`,
-          skillFile,
-          `Skill file is ${Math.floor(ageMs / 86400000)} days old. Issues: ${issues.join('; ')}`,
-        ));
-      }
-    }
-  } catch (err) {
-    logger.debug('optimizer: generateSkillImprovementProposals failed to read skillsDir', { err: err.message });
-  }
-
-  return proposals;
-}
-
-/**
- * Scan the task queue for stuck or stalled workflows.
- * Tasks that have been 'in-progress' for >1 hour are considered stalled.
- */
-export async function generateWorkflowRepairProposals(vaultDir) {
-  const queueDir = path.join(brainDir, 'scheduler', 'queue');
-  const proposals = [];
-
-  if (!fs.existsSync(queueDir)) return proposals;
-
-  const now = Date.now();
-  const stalledCutoff = 60 * 60 * 1000; // 1 hour
-
-  try {
-    const files = fs.readdirSync(queueDir).filter(f => f.endsWith('.md'));
-    for (const file of files) {
-      const raw = fs.readFileSync(path.join(queueDir, file), 'utf8');
-      const { data } = matter(raw);
-      if (data.status !== 'in-progress') continue;
-
-      const updatedAt = new Date(data.updated_at || data.created || 0).getTime();
-      if (now - updatedAt < stalledCutoff) continue;
-
-      proposals.push(createProposal(
-        'workflow-repair',
-        `Stalled task: ${data.slug || file}`,
-        path.join(queueDir, file),
-        `Task has been in-progress for ${Math.floor((now - updatedAt) / 60000)} minutes. May need retry or cancellation.`,
-      ));
-    }
-  } catch (err) {
-    logger.debug('optimizer: generateWorkflowRepairProposals failed to read queueDir', { err: err.message });
-  }
-
-  return proposals;
-}
-
-/**
- * Analyze the vault's model usage patterns and propose routing improvements.
- * Flags cases where high-priority tasks were sent to the local LLM
- * that should have used a frontier model.
- */
-export async function generateModelRoutingProposals(vaultDir) {
-  const proposals = [];
-  const nodes = getNodes(vaultDir);
-
-  // Find high-importance facts with low confidence — likely needed frontier model
-  const underconfident = nodes.filter(n =>
-    n.status === 'active' &&
-    n.category === 'facts' &&
-    n.importance >= 4 &&
-    n.confidence < 0.6 &&
-    n.source?.agent === 'fact-seeker',
-  );
-
-  for (const node of underconfident.slice(0, 5)) {
-    proposals.push(createProposal(
-      'model-routing',
-      `Re-research with frontier model: "${node.title}"`,
-      node.slug,
-      `High-importance fact (importance: ${node.importance}) has low confidence (${node.confidence}). Originally researched by local model. Frontier model may produce better synthesis.`,
-    ));
-  }
-
-  return proposals;
-}
-
 /**
  * Nodes that are important but have gone untouched — computed on demand.
  *
@@ -310,21 +187,6 @@ export function findStaleNodes(vaultDir, { days = 30, minImportance = 4 } = {})
     .sort((a, b) => new Date(a.last_accessed) - new Date(b.last_accessed));
 }
 
-/**
- * @deprecated Wrote tickets nothing reads. Retained because the dream cycle's
- * master switch (ENABLE_STALE_KNOWLEDGE_REFRESH, off) still references it.
- * Stale nodes are surfaced to a human via findStaleNodes instead; nothing
- * re-researches them automatically (RESEARCH_SYSTEM2).
- */
-export async function generateStaleKnowledgeRefreshProposals(vaultDir) {
-  return findStaleNodes(vaultDir, { days: 30, minImportance: 4 }).map(node => createProposal(
-    'stale-knowledge-refresh',
-    `Refresh stale high-importance memory: ${node.title}`,
-    node.slug,
-    'Node has not been accessed in over 30 days but maintains high importance. Requires verification against current state.',
-  ));
-}
-
 /**
  * Local Eval Gate for Proposal Promotion
  * Uses the local runtime to evaluate the validity of a proposal.
@@ -379,6 +241,14 @@ export async function evaluateProposalGate(proposal, runtimeConfig, vaultDir = n
     return stamp('accepted');
   }
 
+  // smart-decay is verified mechanically against live state: the memory still exists, is
+  // active and unprotected, and the access ledger shows no use since it was judged and for
+  // the full decay age. Only then may it reach `accepted` and auto-apply (DECAY-01).
+  if (proposal.category === 'smart-decay') {
+    const reason = verifySmartDecay(proposal, vaultDir);
+    return reason ? stamp('rejected', { rejection_reason: reason }) : stamp('accepted');
+  }
+
   // stale-knowledge-refresh no longer produces tickets at all — the work is
   // handed to the research queue, which can actually perform it. If one is
   // somehow generated, it is not something to auto-accept.
@@ -422,41 +292,67 @@ Output ONLY valid JSON.`;
  *
  * @param {string} vaultDir
  * @param {object} runtimeConfig
- * @param {number} [ageThresholdDays=60]  Minimum age before considering decay
+ * @param {number} [ageThresholdDays=60]  Active days of the brain without a use before considering decay
  * @returns {object[]} decay proposals
  */
-export async function runSmartDecay(vaultDir, runtimeConfig, ageThresholdDays = 60) {
-  const { callLocalRuntime } = await import('./runtime.mjs');
+/** Active days (days the brain was used), never calendar days: an idle brain never decays. */
+export const DECAY_AGE_DAYS = 60;
+
+/**
+ * Why a smart-decay proposal may not be applied, or null when live state supports it.
+ * Shared by the gate and the applier so both check the same facts.
+ */
+export function verifySmartDecay(proposal, vaultDir, { now = Date.now(), ageThresholdDays = DECAY_AGE_DAYS } = {}) {
+  if (!vaultDir) return 'No vault to verify against.';
+  const slug = String(proposal.target_path || '').trim();
+  const node = getNodes(vaultDir).find(n => n.slug === slug);
+  if (!node) return `Memory ${slug} no longer exists.`;
+  if (node.status !== 'active') return `Memory ${slug} is already ${node.status}.`;
+  if (isDecayProtected(node)) return `Memory ${slug} is protected from decay.`;
+  const ledger = readAccess(path.join(path.dirname(vaultDir), 'memory-derived'));
+  const used = lastUsedMs(node, ledger);
+  if (proposal.decay_last_used_at && used > new Date(proposal.decay_last_used_at).getTime()) return `Memory ${slug} was used after it was judged.`;
+  if (activeDaysSince(ledger, used) < ageThresholdDays) return `Memory ${slug} was used within the brain's last ${ageThresholdDays} active days.`;
+  return null;
+}
+
+/** Memories decay never touches: rules, absolute-priority and importance-5 memories. */
+export function isDecayProtected(node) {
+  return node.priority === 'absolute' || node.importance >= 5
+    || ['invariants', 'preferences', 'anti-patterns'].includes(node.category);
+}
+
+/** Active, unprotected memories unused for at least `ageThresholdDays` of the brain's active days. */
+export function decayCandidates(nodes, ledger, { now = Date.now(), ageThresholdDays = DECAY_AGE_DAYS } = {}) {
+  return nodes
+    .filter(n => n.status === 'active' && n.type !== 'proposal' && !isDecayProtected(n))
+    .filter(n => activeDaysSince(ledger, lastUsedMs(n, ledger)) >= ageThresholdDays)
+    .sort((a, b) => lastUsedMs(a, ledger) - lastUsedMs(b, ledger));
+}
+
+export async function runSmartDecay(vaultDir, runtimeConfig, ageThresholdDays = DECAY_AGE_DAYS, { derivedDir = path.join(path.dirname(vaultDir), 'memory-derived'), call } = {}) {
+  const callLocalRuntime = call || (await import('./runtime.mjs')).callLocalRuntime;
   const nodes = getNodes(vaultDir);
   const now = Date.now();
-  const ageThresholdMs = ageThresholdDays * 24 * 60 * 60 * 1000;
+  const ledger = readAccess(derivedDir);
   const proposals = [];
 
-  // Candidates: active, not absolute priority, not accessed recently
-  const candidates = nodes.filter(n => {
-    if (n.status !== 'active') return false;
-    if (n.priority === 'absolute') return false;
-    if (n.importance >= 5) return false;
-    const lastAccessed = new Date(n.last_accessed || n.updated || 0).getTime();
-    return (now - lastAccessed) > ageThresholdMs;
-  });
-
-  // Process up to 5 candidates per run to avoid excessive LLM calls
-  const batch = candidates.slice(0, 5);
+  // Oldest unused first, up to 5 per run to bound model calls.
+  const batch = decayCandidates(nodes, ledger, { now, ageThresholdDays }).slice(0, 5);
 
   for (const node of batch) {
-    const ageDays = Math.floor((now - new Date(node.last_accessed || node.updated || 0).getTime()) / (1000 * 60 * 60 * 24));
+    const ageDays = activeDaysSince(ledger, lastUsedMs(node, ledger));
 
     const prompt = [
       `## Memory Node: ${node.slug}`,
       `Title: "${node.title}"`,
-      `Category: ${node.category} | Importance: ${node.importance} | Age: ${ageDays} days`,
+      `Category: ${node.category} | Importance: ${node.importance} | Unused for ${ageDays} active days of its brain`,
       `Tags: ${(node.tags || []).join(', ')}`,
       '',
       '## Body',
       (node.body || '').slice(0, 800),
       '',
-      `This node has not been accessed in ${ageDays} days. Should it be retained, archived, or decayed?`,
+      `This node has not been used on the last ${ageDays} days its brain was active. Should it be retained, archived, or decayed?`,
     ].join('\n');
 
     try {
@@ -468,15 +364,20 @@ export async function runSmartDecay(vaultDir, runtimeConfig, ageThresholdDays =
       const verdict = result.verdict || 'RETAINED';
 
       if (verdict !== 'RETAINED') {
-        proposals.push(createProposal(
-          'smart-decay',
-          `Smart Decay [${verdict}]: "${node.title}"`,
-          node.slug,
-          `Age: ${ageDays} days. Reasoning: ${result.reasoning || 'No reasoning provided.'} Confidence adjustment: ${result.confidence_adjustment || 0}`,
-        ));
+        proposals.push({
+          ...createProposal(
+            'smart-decay',
+            `Smart Decay [${verdict}]: "${node.title}"`,
+            node.slug,
+            `Unused for ${ageDays} active days. Reasoning: ${result.reasoning || 'No reasoning provided.'} Confidence adjustment: ${result.confidence_adjustment || 0}`,
+          ),
+          // The gate re-checks that the memory has not been used since this judgement.
+          decay_verdict: verdict,
+          decay_last_used_at: new Date(lastUsedMs(node, ledger)).toISOString(),
+        });
       }
-    } catch {
-      // Skip failed evaluations silently
+    } catch (err) {
+      logger.warn('optimizer', `Smart decay could not evaluate ${node.slug}: ${err.message}`);
     }
   }
 

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