total-recall-brain 3.44.0 → 3.46.0

package/src/core/required-plugins.mjs

@@ -10,7 +10,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
-import { readPluginsDir, globalPluginsDir, PACKAGE_ROOT, resolvePluginFile } from './plugin-loader.mjs';
+import { readPluginsDir, globalPluginsDir, PACKAGE_ROOT, resolvePluginFile, validatePluginManifest } from './plugin-loader.mjs';
 import { DEFAULT_PLUGIN_IDS, REQUIRED_INSTALLATION_PLUGIN_IDS } from './default-plugins.mjs';
 import { comparePackageVersions } from './package-version.mjs';
 import { preparePluginDependencies } from './plugin-dependencies.mjs';
@@ -113,14 +113,39 @@ export function inspectRequiredPlugins(brainDir, { pluginsDir, sharedBrainDir =
   return { status: errors.length ? 'failed' : 'ready', errors, source, installations };
 }
 
-/** Only a copy that declares an older release than the bundled one is refreshed; damaged same-release copies still fail. */
+const LEGACY_PRESENTATION_FIELDS = ['card', 'card_face', 'card_layout'];
+
+function hasLegacyPresentation(manifest) {
+  return LEGACY_PRESENTATION_FIELDS.some(field => Object.hasOwn(manifest, field))
+    || (Array.isArray(manifest.ui?.elements) && manifest.ui.elements.some(element => ['card', 'card-face'].includes(element?.kind)));
+}
+
+function hasPluginFiles(directory, files) {
+  return files.every(file => fs.statSync(resolvePluginFile(directory, file)).isFile());
+}
+
+function runtimeFiles(manifest) {
+  return ['package.json', ...(manifest.cli ? [manifest.cli.handler] : []), ...Object.values(manifest.runtime?.modules || {})];
+}
+
+/** Refresh older copies and migrate the retired presentation of an otherwise intact same-release copy. */
 function isStaleInstall(target, source) {
   try {
     // A link is its owner's checkout. Replacing it would delete that repository's files, .git included.
     if (fs.lstatSync(target).isSymbolicLink()) return false;
-    const installed = JSON.parse(fs.readFileSync(path.join(target, 'plugin.json'), 'utf8')).version;
-    const bundled = JSON.parse(fs.readFileSync(path.join(source, 'plugin.json'), 'utf8')).version;
-    return comparePackageVersions(installed, bundled) === -1;
+    const installed = JSON.parse(fs.readFileSync(path.join(target, 'plugin.json'), 'utf8'));
+    const bundled = JSON.parse(fs.readFileSync(path.join(source, 'plugin.json'), 'utf8'));
+    if (comparePackageVersions(installed.version, bundled.version) === -1) return true;
+    if (installed.version !== bundled.version || installed.id !== bundled.id || bundled.id !== path.basename(source)
+      || installed.cli?.command !== bundled.cli?.command || !hasLegacyPresentation(installed)
+      || hasLegacyPresentation(bundled) || !bundled.ui?.home || !validatePluginManifest(bundled).valid) return false;
+
+    const migrated = { ...installed, ui: bundled.ui };
+    for (const field of LEGACY_PRESENTATION_FIELDS) delete migrated[field];
+    if (!validatePluginManifest(migrated).valid || !hasPluginFiles(target, runtimeFiles(installed))) return false;
+    return hasPluginFiles(source, [
+      ...runtimeFiles(bundled), bundled.ui.design_tokens, ...bundled.ui.elements.map(element => element.module),
+    ]);
   } catch { return false; }
 }
 
@@ -165,7 +190,7 @@ function installDefaultsInto(brainDir, sourceDir) {
       fs.mkdirSync(path.dirname(target), { recursive: true });
       fs.cpSync(source, target, { recursive: true, force: false, errorOnExist: true });
     } else if (isStaleInstall(target, source)) {
-      // A vendored copy that no longer validates (or predates the bundled release) is replaced; node_modules stays.
+      // Keep installed dependencies when refreshing the bundled plugin files.
       for (const entry of fs.readdirSync(target)) if (entry !== 'node_modules') fs.rmSync(path.join(target, entry), { recursive: true, force: true });
       for (const entry of fs.readdirSync(source)) if (entry !== 'node_modules') fs.cpSync(path.join(source, entry), path.join(target, entry), { recursive: true });
     }
@@ -195,23 +220,45 @@ export function auditProjectPluginCopies(projectRoot, { sharedDir = globalPlugin
     return { copies: [], count: 0, sourceDir };
   }
   const copies = [];
-  for (const id of DEFAULT_PLUGIN_IDS) {
+  const realpath = (p) => { try { return fs.realpathSync(p); } catch { return null; } };
+  // A link in a repository that resolves to the same plugin as the shared
+  // install only shadows it: state and records split between brains and the
+  // repository can drift onto another checkout. Defaults never belong to a
+  // repository, so any linked default is a shadow too.
+  const isShadowLink = (id, copyDir, shared) => {
+    if (!fs.lstatSync(copyDir).isSymbolicLink() || !fs.existsSync(shared)) return false;
+    return DEFAULT_PLUGIN_IDS.includes(id) || realpath(copyDir) === realpath(shared);
+  };
+  const entries = fs.readdirSync(pluginsDir).filter((name) => !name.startsWith('.'));
+  const ids = [...new Set([...DEFAULT_PLUGIN_IDS, ...entries])];
+  for (const id of ids) {
     const copyDir = path.join(pluginsDir, id);
-    if (!fs.existsSync(copyDir)) continue;
+    if (!fs.lstatSync(copyDir, { throwIfNoEntry: false })) continue;
     const source = path.join(sourceDir, id);
     const shared = path.join(sharedDir, id);
+    const linked = fs.lstatSync(copyDir).isSymbolicLink();
+    // The source checkout a shared link points at is not a copy.
+    if (!linked && fs.existsSync(shared) && realpath(shared) === realpath(copyDir)) continue;
+    const shadow = isShadowLink(id, copyDir, shared);
+    // Nothing is installed per repository. A plugin found only here must be
+    // installed in the shared folder before its repository entry can go.
+    const repoOnly = !fs.existsSync(shared);
     const row = {
       id, dir: copyDir,
       sourceDir: fs.existsSync(source) ? source : null,
       sharedDir: fs.existsSync(shared) ? shared : null,
       edited: null, version: null, sourceVersion: null, sharedVersion: null,
-      linked: fs.lstatSync(copyDir).isSymbolicLink(),
+      linked,
+      shadow,
+      repoOnly,
+      target: fs.lstatSync(copyDir).isSymbolicLink() ? fs.readlinkSync(copyDir) : null,
     };
     const version = (dir) => { try { return JSON.parse(fs.readFileSync(path.join(dir, 'plugin.json'), 'utf8')).version; } catch { return null; } };
     row.version = version(copyDir);
     row.sourceVersion = row.sourceDir ? version(row.sourceDir) : null;
     row.sharedVersion = row.sharedDir ? version(row.sharedDir) : null;
-    row.edited = row.sourceDir ? !sameTree(copyDir, row.sourceDir) : null;
+    // A link is owned by its target checkout, so its tree is never "edited" here; a dangling link has no tree.
+    row.edited = row.linked || !fs.existsSync(copyDir) ? null : row.sourceDir ? !sameTree(copyDir, row.sourceDir) : null;
     // Older copies shadow the shared install. Version skew identifies stale
     // candidates for archival but does not prove the local source is disposable.
     row.stale = Boolean(row.version && row.sharedVersion && comparePackageVersions(row.version, row.sharedVersion) < 0);

package/src/core/rule-length.mjs

@@ -0,0 +1,23 @@
+/** Shared rule policy. Diagnostics contain counts and limits, never rule text. */
+export const RULE_SOFT_LIMIT = 300;
+export const RULE_HARD_LIMIT = 800;
+let rejections = 0;
+
+export function ruleLengthStats() {
+  return { rejections, scope: 'process' };
+}
+
+export function checkRuleLength(data, body, { allowLong = false } = {}) {
+  const errors = [], warnings = [];
+  const rule = data.type === 'rule' || (data.type === 'memory' &&
+    ['invariants', 'preferences', 'anti-patterns'].includes(data.category));
+  if (!rule || data.tags?.includes('context:policy')) return { errors, warnings };
+  const length = String(body || '').trim().length;
+  if (length > RULE_HARD_LIMIT && allowLong !== true) {
+    rejections++;
+    errors.push(`Rule is ${length} characters (limit ${RULE_HARD_LIMIT}). Shorten the rule. Save history and examples as a fact, or use the explicit allow-long exception.`);
+  } else if (length > RULE_SOFT_LIMIT) {
+    warnings.push(`Rule is ${length} characters. Keep rules brief (under ${RULE_SOFT_LIMIT} characters). Save history and examples as a fact.`);
+  }
+  return { errors, warnings };
+}

package/src/core/runtime.mjs

@@ -11,7 +11,7 @@ let configOwner, configError;
 try { configOwner = await loadPluginModule('meta-harness', 'reasoning-runtime'); }
 catch (error) { configError = error; }
 function reasoningConfigOwner() {
-  if (!configOwner) throw new Error(`Meta Harness reasoning is unavailable: ${configError?.message || 'install the plugin'}`);
+  if (!configOwner) throw new Error(`Metaharness reasoning is unavailable: ${configError?.message || 'install the plugin'}`);
   return configOwner;
 }
 

package/src/core/scheduler.mjs

@@ -7,14 +7,13 @@ import config from './config.mjs';
 import { getNodes } from './vault-cache.mjs';
 import { logger } from './logger.mjs';
 import { loadQueue, updateQueueItem } from './research-queue.mjs';
-import { transitionTaskStatus } from './task-envelope.mjs';
+import { transitionTaskStatus, getTask } from './task-envelope.mjs';
 
 /**
  * Total Recall Task Scheduler
  *
  * A priority queue that dispatches tasks to cognitive layer engines.
- * The queue is NEVER empty — when explicit tasks run out, the scheduler
- * auto-generates idle improvement tasks from vault analysis.
+ * An empty queue stays empty. Automations schedules maintenance explicitly.
  *
  * Task categories map to cognitive layers:
  *   conscious-enforcement  → Conscious Layer  (weight 1.0)
@@ -34,7 +33,6 @@ export const LAYER_WEIGHTS = Object.freeze({
   'skill-engineering': 0.5,
   'proactive-research': 0.4,
   'self-evaluation': 0.3,
-  'exploration': 0.2,
 });
 
 // ─── Priority Queue ─────────────────────────────────────────────────────────────
@@ -198,9 +196,8 @@ const RESEARCH_PHASE_COUNT = Object.keys(RESEARCH_PHASES).length;
 let _idleCycleCounter = 0;
 
 /**
- * Generate an idle improvement task when the explicit queue is empty.
- * Purely local maintenance, round-robin: inference, post-mortem, clarity
- * review, memory compaction. Idle ticks never research on their own; research
+ * Generate a maintenance candidate for an explicit scheduled run.
+ * Purely local maintenance: inference, clarity review and compaction. Research
  * only runs for topics a human asked for or the project gate approved.
  */
 export function generateIdleTask({ vaultDir, sessionsDir }) {
@@ -208,7 +205,6 @@ export function generateIdleTask({ vaultDir, sessionsDir }) {
   // Absolutely no automated/proactive web searches or staleness checks that make internet queries.
   const cleanStrategies = [
     () => generateInferenceTask(vaultDir),
-    () => generatePostMortemTask(sessionsDir),
     () => generateClarityReviewTask(vaultDir),
     () => generateMemoryCompactionTask(vaultDir),
   ];
@@ -224,6 +220,26 @@ export function generateIdleTask({ vaultDir, sessionsDir }) {
   }
 }
 
+/** Called by an automations manifest task, never by queue exhaustion. */
+export async function enqueueScheduledIdleTasks({ vaultDir, queueDir, now = new Date(),
+  leader = async () => (await import('./leader-election.mjs')).isLeader() } = {}) {
+  if (!await leader()) return { enqueued: [], skipped: 'not-leader' };
+  const tasks = [generateInferenceTask(vaultDir), generateClarityReviewTask(vaultDir), generateMemoryCompactionTask(vaultDir)];
+  const enqueued = [];
+  for (const task of tasks) {
+    if (task.slug.startsWith('idle-')) continue;
+    const kind = task.slug.startsWith('inference-') ? 'inference' : task.slug.startsWith('clarity-') ? 'clarity-review' : 'memory-compaction';
+    const identity = crypto.createHash('sha256').update(String(task.target)).digest('hex').slice(0, 12);
+    task.slug = `${kind}-${now.toISOString().slice(0, 10)}-${identity}`;
+    if (getTask(queueDir, task.slug) || fs.existsSync(path.join(queueDir, 'archive', `${task.slug}.md`))) continue;
+    task.created_by = 'automations';
+    task.payload = { scheduledIdle: true };
+    persistTaskToDisk(task, queueDir);
+    enqueued.push(task.slug);
+  }
+  return { enqueued };
+}
+
 /**
  * Pick a random active memory node and create a clarity review task.
  */
@@ -259,7 +275,7 @@ function generateMemoryCompactionTask(vaultDir) {
     status: 'pending',
     created_by: 'scheduler-idle',
     reason: `Idle task: scan vault for fragmented nodes to merge into comprehensive master documents.`,
-    body: `Scan for highly overlapping or fragmented memory nodes and fuse them into comprehensive master nodes, archiving the fragments.`,
+    body: `File memory-cleanup proposals for overlapping memory nodes. Keep canonical nodes unchanged until proposal review.`,
   };
 }
 
@@ -344,23 +360,6 @@ function generatePostMortemTask(sessionsDir) {
   };
 }
 
-/**
- * Generate a cutoff audit task — scans vault for nodes with intrinsic LLM
- * knowledge that may have drifted since the model's training cutoff.
- */
-function generateCutoffAuditTask() {
-  return {
-    type: 'task',
-    slug: `cutoff-audit-${Date.now().toString(36)}`,
-    priority: 60,
-    category: 'cutoff-audit',
-    status: 'pending',
-    created_by: 'scheduler-idle',
-    reason: 'Idle task: scan vault for training-cutoff assumption drift',
-    body: 'Identify memory nodes containing time-sensitive claims based on intrinsic LLM knowledge. Flag high-drift items (API versions, pricing, model specs, framework changes) for verification against current real-world sources.',
-  };
-}
-
 function makeFallbackTask(category, reason) {
   return {
     type: 'task',
@@ -385,7 +384,7 @@ function makeFallbackTask(category, reason) {
  * @param {string} opts.sessionsDir  Path to .agent/skills/total-recall/sessions/
  * @returns {{ queue: TaskQueue, stats: object }}
  */
-export function createScheduler({ queueDir, vaultDir, sessionsDir }) {
+export function createScheduler({ queueDir, vaultDir, sessionsDir, localOnly = false }) {
   const queue = new TaskQueue();
 
   // Load explicit tasks from disk
@@ -397,7 +396,7 @@ export function createScheduler({ queueDir, vaultDir, sessionsDir }) {
   // Optional remote vault sync job (env-configured only)
   try {
     const { remoteVaultSync } = config;
-    if (remoteVaultSync.enabled) {
+    if (!localOnly && remoteVaultSync.enabled) {
       const statusFile = path.join(path.dirname(remoteVaultSync.vaultDir), 'sync-status.json');
       let lastRunMs = 0;
       if (fs.existsSync(statusFile)) {
@@ -442,7 +441,7 @@ export function createScheduler({ queueDir, vaultDir, sessionsDir }) {
       : 60 * 60 * 1000; // 1 hour default
 
     let resetCount = 0;
-    for (const item of loadQueue()) {
+    for (const item of localOnly ? [] : loadQueue()) {
       if (item.status !== 'failed') continue;
       if ((item.attempts || 0) >= MAX_RESEARCH_ATTEMPTS) continue;
       const failedAt = new Date(item.updated_at || item.created_at || 0).getTime();
@@ -469,7 +468,7 @@ export function createScheduler({ queueDir, vaultDir, sessionsDir }) {
     }
 
     // User requests run before autonomous background research; oldest first within each.
-    const researchItems = loadQueue()
+    const researchItems = (localOnly ? [] : loadQueue())
       .filter((i) => i.status === 'pending' && RESEARCH_PHASES[i.research_phase || 'acquisition'])
       .sort((a, b) => {
         const ua = a.origin === 'autonomous' ? 1 : 0;
@@ -532,27 +531,20 @@ export function createScheduler({ queueDir, vaultDir, sessionsDir }) {
      * Get the next task.
      *
      * Default: only explicit (and research-queue) tasks — never invent work.
-     * Idle generation requires TR_IDLE_TASKS=1 or opts.allowIdle === true.
+     * Automations is the only recurring maintenance trigger.
      *
      * @param {{ allowIdle?: boolean }} [opts]
      * @returns {{ task: object|null, source: 'explicit'|'idle'|'empty' }}
      */
     next(opts = {}) {
+      if (opts.localOnly) {
+        const local = queue._items.findIndex(({ task }) => ['lesson-review', 'skill-manager'].includes(task.executor) || ['lesson-review', 'self-evaluation', 'skill-engineering'].includes(task.category));
+        return local < 0 ? { task: null, source: 'empty' } : { task: queue._items.splice(local, 1)[0].task, source: 'explicit' };
+      }
       const explicit = queue.dequeue();
       if (explicit) return { task: explicit, source: 'explicit' };
 
-      const allowIdle =
-        opts.allowIdle === true ||
-        process.env.TR_IDLE_TASKS === '1' ||
-        process.env.TR_IDLE_TASKS === 'true';
-
-      if (!allowIdle) {
-        return { task: null, source: 'empty' };
-      }
-
-      const idle = generateIdleTask({ vaultDir, sessionsDir });
-      persistTaskToDisk(idle, queueDir);
-      return { task: idle, source: 'idle' };
+      return { task: null, source: 'empty' };
     },
   };
 }

package/src/core/schema.mjs

@@ -41,8 +41,7 @@ export const TaskSchema = z.object({
     'system2-deliberation',
     'skill-engineering',
     'proactive-research',
-    'self-evaluation',
-    'exploration'
+    'self-evaluation'
   ]),
   status: z.enum(['pending', 'in_progress', 'done', 'failed']),
   target: z.string().optional(),
@@ -1035,6 +1034,8 @@ export const PluginRecordSchema = z.object({
   task_runs: z.record(z.string()).optional(),
   /** Explicit mesh node for commands with selected-node placement. */
   task_nodes: z.record(z.string().min(1)).optional(),
+  runtime_enabled: z.boolean().optional(),
+  runtime_on_use: z.boolean().optional(),
 }).passthrough();
 
 const SECRET_KEY_PATTERN = /^(.*_)?(secret|token|password|api[_-]?key|private[_-]?key|credentials|auth[_-]?header|bearer)$/i;

package/src/core/search.mjs

@@ -98,7 +98,8 @@ export async function semanticSearch(query, {
   tags = null,
   modality = null,
   importance = null,
-  priority = null
+  priority = null,
+  rankResults = null
 } = {}) {
   const k = Math.min(Number(top_k) || 5, 20);
 
@@ -234,7 +235,7 @@ export async function semanticSearch(query, {
   }
 
   // Slice top results
-  for (const { node, score } of blendedRanked.slice(0, k)) {
+  for (const { node, score } of blendedRanked.slice(0, rankResults ? undefined : k)) {
     if (node) {
       const similarity = similarityBySlug.get(node.slug);
       results.push({
@@ -297,7 +298,7 @@ export async function semanticSearch(query, {
   }
 
   results.sort((a, b) => b.score - a.score);
-  const finalResults = results.slice(0, k);
+  const finalResults = (rankResults ? rankResults(results) : results).slice(0, k);
   if (!queryEmbedding || vaultEntries.length === 0) {
     finalResults.degradedTextSearch = true;
     // Say WHICH failure this is. The caller renders remediation from it, and

package/src/core/server-service.mjs

@@ -0,0 +1,148 @@
+/** Repair this installation's macOS server LaunchAgent. Never manages systemd. */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { processIdentity } from './startup-health.mjs';
+
+const PACKAGE_ROOT = fileURLToPath(new URL('../..', import.meta.url));
+const LABEL = 'com.totalrecall.server';
+const corePathEnv = new Set(['AGENT_DIR', 'TR_SECRETS_BRAIN', 'TR_SERVER_PID_FILE']);
+const inside = (root, value) => value === root || value.startsWith(root + path.sep);
+const real = value => { try { return fs.realpathSync(value); } catch { return path.resolve(value); } };
+
+export function stableNodePath(env = process.env) {
+  for (const dir of (env.PATH || '').split(path.delimiter)) {
+    if (!dir || !path.isAbsolute(dir)) continue;
+    const candidate = path.join(dir, 'node');
+    if (candidate.split(path.sep).includes('Cellar')) continue;
+    try { fs.accessSync(candidate, fs.constants.X_OK); if (fs.statSync(candidate).isFile()) return candidate; } catch {}
+  }
+  throw new Error('No stable node executable on PATH. Add the node symlink directory to PATH.');
+}
+
+function convert(input, format, exec) {
+  const result = exec('plutil', ['-convert', format, '-o', '-', '-'], { input, encoding: 'utf8', timeout: 5000 });
+  if (result.status !== 0 || result.error) throw new Error(`Cannot convert server plist to ${format}.`);
+  return result.stdout;
+}
+
+/** Detect foreign installations without naming any operator repository. */
+function checkoutFor(value, oldRoot, packageRoot) {
+  if (inside(packageRoot, value) || inside(real(packageRoot), value)) return null;
+  if (oldRoot && real(oldRoot) !== real(packageRoot) && inside(oldRoot, value)) return oldRoot;
+  for (let dir = value; ; dir = path.dirname(dir)) {
+    try {
+      if (JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')).name === 'total-recall-brain'
+          && real(dir) !== real(packageRoot)) return dir;
+    } catch {}
+    if (dir === path.dirname(dir)) return null;
+  }
+}
+
+export function serverEnvironment(existing, { packageRoot, oldRoot }) {
+  const env = {};
+  for (const [key, value] of Object.entries(existing || {})) {
+    if (typeof value !== 'string') throw new Error(`Server environment ${key} must be a string.`);
+    if (key === 'PATH') {
+      env[key] = value.split(path.delimiter).map(part => {
+        const foreign = path.isAbsolute(part) && checkoutFor(part, oldRoot, packageRoot);
+        return foreign ? path.join(packageRoot, path.relative(foreign, part)) : part;
+      }).join(path.delimiter);
+      continue;
+    }
+    const foreign = path.isAbsolute(value) && checkoutFor(value, oldRoot, packageRoot);
+    if (!foreign) env[key] = value;
+    else if (corePathEnv.has(key)) env[key] = path.join(packageRoot, path.relative(foreign, value));
+    // Obsolete settings must not retain a path into another installation.
+  }
+  return env;
+}
+
+function publicPlist(plist) {
+  const copy = structuredClone(plist);
+  for (const key of Object.keys(copy.EnvironmentVariables || {})) {
+    if (/password|secret(?!s_brain)|token|api.?key|credential/i.test(key)) copy.EnvironmentVariables[key] = '[redacted]';
+  }
+  return copy;
+}
+
+function plistDiff(before, after) {
+  const lines = [];
+  const walk = (a, b, key) => {
+    if (JSON.stringify(a) === JSON.stringify(b)) return;
+    if (a && b && !Array.isArray(a) && !Array.isArray(b) && typeof a === 'object' && typeof b === 'object') {
+      for (const part of new Set([...Object.keys(a), ...Object.keys(b)])) walk(a[part], b[part], key ? `${key}.${part}` : part);
+    } else {
+      if (a !== undefined) lines.push(`- ${key}: ${JSON.stringify(a)}`);
+      if (b !== undefined) lines.push(`+ ${key}: ${JSON.stringify(b)}`);
+    }
+  };
+  walk(publicPlist(before), publicPlist(after), '');
+  return lines.join('\n') || 'No plist changes.';
+}
+
+export async function ensureServerService({ dryRun = false, platform = process.platform, home = os.homedir(),
+  packageRoot = PACKAGE_ROOT, env = process.env, exec = spawnSync, identity = processIdentity,
+  uid = process.getuid?.(), sleep = ms => new Promise(resolve => setTimeout(resolve, ms)), attempts = 40 } = {}) {
+  if (platform !== 'darwin') return { status: 'unchanged', reason: 'server-release owns the server on systemd hosts; no changes made.' };
+  packageRoot = path.resolve(packageRoot);
+  const plistPath = path.join(home, 'Library/LaunchAgents', `${LABEL}.plist`);
+  const oldBytes = fs.existsSync(plistPath) ? fs.readFileSync(plistPath) : null;
+  const existing = oldBytes ? JSON.parse(convert(oldBytes, 'json', exec)) : {};
+  const template = fs.readFileSync(path.join(packageRoot, 'templates', `${LABEL}.plist`), 'utf8');
+  const desired = JSON.parse(convert(template, 'json', exec));
+  const substitute = value => typeof value === 'string' ? value.replaceAll('__ROOT__', packageRoot).replaceAll('__HOME__', home)
+    : Array.isArray(value) ? value.map(substitute) : value && typeof value === 'object'
+      ? Object.fromEntries(Object.entries(value).map(([key, val]) => [key, substitute(val)])) : value;
+  const plist = substitute(desired);
+  plist.WorkingDirectory = packageRoot;
+  plist.ProgramArguments[0] = stableNodePath(env);
+  plist.EnvironmentVariables = { ...plist.EnvironmentVariables,
+    ...serverEnvironment(existing.EnvironmentVariables, { packageRoot, oldRoot: existing.WorkingDirectory }) };
+  const diff = plistDiff(existing, plist);
+  if (dryRun) return { status: 'dry_run', plistPath, diff };
+
+  const xml = convert(JSON.stringify(plist), 'xml1', exec);
+  const domain = `gui/${uid}`;
+  const service = `${domain}/${LABEL}`;
+  const run = args => exec('launchctl', args, { encoding: 'utf8', timeout: 10000 });
+  const ok = result => result.status === 0 && !result.error;
+  const must = args => { if (!ok(run(args))) throw new Error(`launchctl ${args[0]} failed for ${service}.`); };
+  const agentDir = plist.EnvironmentVariables.AGENT_DIR || path.join(home, '.agent');
+  const pidFile = plist.EnvironmentVariables.TR_SERVER_PID_FILE || path.join(agentDir, 'skills/total-recall/server.pid');
+  const entry = path.join(packageRoot, 'src/server/index.mjs');
+  const previous = identity(pidFile, entry);
+  if (previous.status === 'unknown') throw new Error('Server process identity is unknown. Nothing changed.');
+  const loaded = ok(run(['print', service]));
+  if (!loaded && ['running', 'conflict'].includes(previous.status)) throw new Error('A server runs outside this LaunchAgent. Nothing changed.');
+  fs.mkdirSync(path.dirname(plistPath), { recursive: true });
+  for (const log of [plist.StandardOutPath, plist.StandardErrorPath]) if (log) fs.mkdirSync(path.dirname(log), { recursive: true });
+  const pending = `${plistPath}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(pending, xml, { mode: 0o600 });
+    fs.renameSync(pending, plistPath);
+    if (loaded) {
+      must(['bootout', service]);
+      let retired = false;
+      for (let i = 0; i < attempts; i++) {
+        if (!ok(run(['print', service]))) { retired = true; break; }
+        await sleep(250);
+      }
+      if (!retired) throw new Error('LaunchAgent did not retire.');
+    }
+    must(['bootstrap', domain, plistPath]);
+    for (let i = 0; i < attempts; i++) {
+      const observed = identity(pidFile, entry);
+      if (observed.status === 'running' && (!loaded || observed.pid !== previous.pid)) return { status: 'ready', plistPath, pid: observed.pid, entry: observed.entry };
+      await sleep(250);
+    }
+    throw new Error('Server process verification failed after launchd reload.');
+  } catch (error) {
+    // Keep the previous definition available for operator recovery. Never report success.
+    if (oldBytes !== null) fs.writeFileSync(plistPath, oldBytes, { mode: 0o600 });
+    else fs.rmSync(plistPath, { force: true });
+    throw error;
+  } finally { fs.rmSync(pending, { force: true }); }
+}

package/src/core/session-watcher.mjs

@@ -4,6 +4,7 @@ import os from 'os';
 import crypto from 'crypto';
 import { atomicWrite } from './vault.mjs';
 import { logger } from './logger.mjs';
+import { readLessonEntries } from './lesson-sessions.mjs';
 
 /**
  * Total Recall Session Watcher
@@ -30,6 +31,12 @@ const HOME = os.homedir();
  * of unified SSSS session entries.
  */
 const SOURCES = [
+  {
+    name: 'openclaw',
+    root: path.join(HOME, '.openclaw', 'agents'),
+    filter: filename => filename.endsWith('.jsonl'),
+    adapter: file => parseClaudeCode(file).map(entry => ({ ...entry, source: 'openclaw' })),
+  },
   {
     name: 'claude-code',
     root: path.join(HOME, '.claude', 'projects'),
@@ -248,6 +255,15 @@ export function parseClaudeCode(filePath) {
  */
 export function parseCodex(filePath) {
   const raw = fs.readFileSync(filePath, 'utf8');
+  if (/"type"\s*:\s*"(?:response_item|event_msg)"/.test(raw)) {
+    let parentId = null;
+    return readLessonEntries(filePath).map(message => {
+      const entry = createSessionEntry({ ...message, parentId, source: 'codex',
+        type: message.role === 'user' ? 'task' : message.role === 'tool' ? 'tool_call' : 'observation' });
+      parentId = entry.id;
+      return entry;
+    });
+  }
   const lines = raw.split('\n').filter(Boolean);
   const entries = [];
   let prevId = null;
@@ -661,7 +677,9 @@ export function writeSession(entries, sessionsDir, sourceFile) {
   // Skip if already ingested and unchanged
   if (fs.existsSync(sessionFile)) {
     try {
-      if (fs.readFileSync(sessionFile, 'utf8') === jsonl) {
+      const previous = fs.readFileSync(sessionFile, 'utf8');
+      const semantic = rows => JSON.stringify(rows.map(({ role, type, content, source, cwd }) => ({ role, type, content, source, cwd })));
+      if (previous === jsonl || semantic(previous.trim().split('\n').filter(Boolean).map(line => JSON.parse(line))) === semantic(entries)) {
         return null;
       }
     } catch { /* ignore */ }

package/src/core/skill-gap.mjs

@@ -0,0 +1,16 @@
+import { discoverPlugins } from './plugin-loader.mjs';
+import { runPluginCommand } from './plugin-runner.mjs';
+
+/** Skill engineering belongs to skill-manager. Missing operations fail closed. */
+export async function requestSkillGap(topic, evidence, { projectRoot = process.cwd(), discover = discoverPlugins, run = runPluginCommand } = {}) {
+  if (typeof topic !== 'string' || !topic.trim() || typeof evidence !== 'string' || !evidence.trim()) {
+    throw new Error('Skill gap requires a topic and an evidence reference');
+  }
+  const plugin = discover(projectRoot).find(item => item.id === 'skill-manager' && item.valid);
+  if (!plugin?.manifest.cli?.subcommands?.some(item => item.name === 'gap')) {
+    throw new Error('Skill-manager gap is unavailable. Install an owner version that provides: total-recall skill-manager gap "<topic>" --evidence <ref>');
+  }
+  const result = await run(plugin, { subcommand: 'gap', args: [topic.trim(), '--evidence', evidence], cwd: projectRoot });
+  if (!result.ok || result.truncated) throw new Error(`Skill-manager gap failed: ${result.stderr || result.output || result.exitCode}`);
+  return { success: true, output: result.stdout || result.output, executor: 'skill-manager' };
+}

package/src/core/ssss-kernel-bridge.mjs

@@ -12,7 +12,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import matter from './frontmatter.mjs';
-import { createEngine } from '@ssss/cli/engine';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createEngine, resolveContainedPath } from '@ssss/cli/engine';
 import { createValidator } from '@ssss/cli/validator';
 import {
   composeRegistryLayers,
@@ -20,6 +21,7 @@ import {
   resolvePrimitiveDefinition,
 } from '@ssss/cli/registry';
 import { detectDirectWrites } from '@ssss/cli/guard';
+import { checkRuleLength } from './rule-length.mjs';
 import { validateMemoryNode } from './total-recall-memory-validator.mjs';
 import {
   TOTAL_RECALL_HOST_EXTENSION,
@@ -66,6 +68,7 @@ const DIRECT_WRITE_APPROVED = [
 
 let cachedEngine = null;
 let cachedRegistryKey = '';
+const writePolicy = new AsyncLocalStorage();
 
 export function getKernelMode() {
   // Default to package-kernel cutover for core types (memory/workflow/low-risk).
@@ -187,7 +190,27 @@ export function getTotalRecallEngine(options = {}) {
   const registrySet = createTotalRecallRegistrySet(options);
   const key = `${[...registrySet.types.keys()].sort().join(',')}|${options.leaseStore || ''}`;
   if (!cachedEngine || cachedRegistryKey !== key || options.forceNew) {
-    const validator = createValidator({ registrySet });
+    const baseValidator = createValidator({ registrySet });
+    const validator = {
+      ...baseValidator,
+      validateData(data, callOptions) {
+        const result = baseValidator.validateData(data, callOptions);
+        const context = writePolicy.getStore();
+        if (context?.envelope.type !== 'patch') return result;
+        // The kernel calls validateData with the merged frontmatter. Check the
+        // replacement body against that category and those exception tags.
+        // A metadata-only patch keeps the current document body.
+        const { envelope, vaultRoot, options } = context;
+        const body = envelope.patches.__body__ === undefined
+          ? matter(fs.readFileSync(resolveContainedPath(vaultRoot, envelope.path), 'utf8')).content
+          : String(envelope.patches.__body__);
+        const policy = checkRuleLength(data, body, options);
+        context.warnings.push(...policy.warnings);
+        return { ...result, valid: result.valid && !policy.errors.length,
+          errors: [...result.errors, ...policy.errors],
+          field_errors: [...result.field_errors, ...policy.errors.map(issue => ({ field: '__body__', issue }))] };
+      },
+    };
     cachedEngine = createEngine({
       registrySet,
       validator,
@@ -277,6 +300,9 @@ export function prepareEnvelopeForKernel(envelope, options = {}) {
       return { envelope: env, warnings, errors: [`Content parsing error: ${error.message}`] };
     }
     const data = { ...parsed.data };
+    const length = checkRuleLength(data, parsed.content, options);
+    errors.push(...length.errors);
+    warnings.push(...length.warnings);
 
     // Package 0.9 universal frontmatter.
     if (!data.title && data.name) data.title = data.name;
@@ -392,11 +418,13 @@ export async function processViaPackageKernel(envelope, vaultRoot, options = {})
 
   const eventsDir = path.join(vaultRoot, '.events');
   if (!env.dry_run && !fs.existsSync(eventsDir)) fs.mkdirSync(eventsDir, { recursive: true });
-  const response = await engine.processOperation(env, vaultRoot, {
+  const context = { envelope: env, vaultRoot, options, warnings: [] };
+  const response = await writePolicy.run(context, () => engine.processOperation(env, vaultRoot, {
     ...options,
     vaultRoot,
     principal: options.principal || mapTrPrincipal(env, options, vaultRoot),
-  });
+  }));
+  prepared.warnings.push(...context.warnings);
 
   if (prepared.warnings.length && response?.validation) {
     response.validation.warnings = [