total-recall-brain 3.43.3 → 3.45.0

package/src/core/server-restart.mjs

@@ -12,9 +12,14 @@
  * Exiting an unsupervised server is not a restart, it is an outage, so
  * supervision is proven (the job's reported PID is ours) rather than assumed.
  */
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import { processIdentity } from './startup-health.mjs';
+import { runningServerStatus } from './running-server.mjs';
+
+const GLOBAL_PACKAGE = 'total-recall-brain';
+const HOLD_LIMIT_MS = 6 * 60 * 60 * 1000;
 
 const LAUNCHD_LABELS = ['com.totalrecall.brain', 'com.totalrecall.server'];
 const SYSTEMD_UNITS = ['total-recall-server', 'total-recall-server.service'];
@@ -47,30 +52,33 @@ function systemdPidFor(unit) {
 
 /**
  * Prove that a supervisor owns THIS process and will restart it.
- * @returns {{supervised: boolean, kind: string|null, label: string|null, reason: string}}
+ * `scope` says whose supervisor it is: `user` belongs to one login, `system` to the machine.
+ * @returns {{supervised: boolean, kind: string|null, label: string|null, scope: string|null, reason: string}}
  */
 export function detectSupervisor(pid = process.pid) {
   // An explicit opt-in for hosts running under a supervisor we cannot query
   // (docker restart policies, pm2, runit). The operator asserts respawn.
   if (process.env.TR_SUPERVISED === '1') {
-    return { supervised: true, kind: 'declared', label: 'TR_SUPERVISED=1', reason: 'declared by operator' };
+    return { supervised: true, kind: 'declared', label: 'TR_SUPERVISED=1', scope: null, reason: 'declared by operator' };
   }
   if (process.platform === 'darwin') {
     for (const label of LAUNCHD_LABELS) {
       const jobPid = launchdPidFor(label);
       if (jobPid === pid) {
-        return { supervised: true, kind: 'launchd', label, reason: `launchd job ${label} owns pid ${pid}` };
+        // launchctl answers for the caller's domain, so as root this is a system daemon.
+        const scope = process.getuid?.() === 0 ? 'system' : 'user';
+        return { supervised: true, kind: 'launchd', label, scope, reason: `launchd job ${label} owns pid ${pid}` };
       }
     }
-    return { supervised: false, kind: null, label: null, reason: 'no launchd job reports this pid' };
+    return { supervised: false, kind: null, label: null, scope: null, reason: 'no launchd job reports this pid' };
   }
   for (const unit of SYSTEMD_UNITS) {
     const found = systemdPidFor(unit);
     if (found && found.pid === pid) {
-      return { supervised: true, kind: 'systemd', label: unit, reason: `systemd ${found.scope} unit ${unit} owns pid ${pid}` };
+      return { supervised: true, kind: 'systemd', label: unit, scope: found.scope, reason: `systemd ${found.scope} unit ${unit} owns pid ${pid}` };
     }
   }
-  return { supervised: false, kind: null, label: null, reason: 'no systemd unit reports this pid' };
+  return { supervised: false, kind: null, label: null, scope: null, reason: 'no systemd unit reports this pid' };
 }
 
 /**
@@ -128,3 +136,116 @@ export function packageVersionOnDisk(rootDir) {
     return null;
   }
 }
+
+/**
+ * Can maintenance replace the server on this host, and how?
+ *
+ * `npm install --global` moves the files under a running server and nothing else
+ * moves the process, so a host that serves from that install stays on the release it
+ * booted on. Replacing it has a gap, so maintenance does it only where a gap is allowed
+ * and a restart is certain to help:
+ *   - a per-user supervisor owns the process. A LaunchAgent or user unit belongs to one
+ *     login; a system service is production, and `deploy release` replaces that with no gap.
+ *   - the process runs the global install's entry, and that install is not a checkout
+ *     (auto-pull owns a checkout) and is at the release. Otherwise a restart starts the
+ *     same old code, or code nobody released.
+ *
+ * @returns {{method: 'restart', kind: string, label: string, pid: number}|{method: 'deploy'|'none', reason: string}}
+ */
+export function planServerReplacement({ brainDir, globalRoot, latest, env = process.env, identity = processIdentity, supervisor = detectSupervisor, versionOnDisk = packageVersionOnDisk } = {}) {
+  const leave = (reason, method = 'none') => ({ method, reason });
+  if (env.TR_SERVER_AUTO_RESTART === '0') return leave('TR_SERVER_AUTO_RESTART=0 leaves this server to the operator.');
+  if (!globalRoot) return leave('The global npm root could not be read, so what a restart would start is unknown.');
+  const install = path.join(globalRoot, GLOBAL_PACKAGE);
+  const observed = identity(path.join(brainDir, 'server.pid'), path.join(install, 'src', 'server', 'index.mjs'));
+  if (!observed.pid) return leave('The process serving this brain could not be identified.');
+  const owner = supervisor(observed.pid);
+  if (owner.supervised && owner.scope === 'system') return leave(`${owner.label} is a system service: replace it with total-recall deploy release.`, 'deploy');
+  if (observed.status !== 'running') return leave(`The server does not run from the global install${observed.entry ? ` (it runs ${observed.entry})` : ''}, so a restart would not bring it to the release.`);
+  if (fs.existsSync(path.join(install, '.git'))) return leave('The global install is a link to a git checkout, which auto-pull keeps current.');
+  const onDisk = versionOnDisk(install);
+  if (onDisk !== latest) return leave(`The global install is ${onDisk ?? 'unreadable'} and the release is ${latest}.`);
+  if (!owner.supervised || owner.scope !== 'user') return leave(`Nothing maintenance can drive would bring the server back: ${owner.reason}.`);
+  return { method: 'restart', kind: owner.kind, label: owner.label, pid: observed.pid };
+}
+
+/** Connections open to the server right now, or null when that cannot be read. */
+export function openServerConnections({ pid, port, platform = process.platform, run = spawnSync } = {}) {
+  const options = { encoding: 'utf8', timeout: 10000 };
+  if (platform === 'linux') {
+    const result = run('ss', ['-tnH', 'state', 'established', 'sport', '=', `:${port}`], options);
+    if (result.error || result.status !== 0) return null;
+    return result.stdout.split('\n').filter((line) => line.trim()).length;
+  }
+  const result = run('lsof', ['-nP', '-a', '-p', String(pid), '-iTCP', '-sTCP:ESTABLISHED', '-Fn'], options);
+  if (result.error) return null;
+  // lsof exits 1 when nothing matches, and also on a real failure, which is the one that writes to stderr.
+  if (result.status !== 0 && (result.stdout?.trim() || result.stderr?.trim())) return null;
+  return (result.stdout || '').split('\n').filter((line) => line.startsWith('n') && line.split('->')[0].endsWith(`:${port}`)).length;
+}
+
+/** The command that stops the server and starts it again, or null when the job is not there. */
+function restartCommand(plan, { run, uid }) {
+  if (plan.kind === 'systemd') return ['systemctl', ['--user', 'restart', plan.label]];
+  // `gui` exists while the user is logged in; a Mac with no login session has only `user`.
+  const target = [`gui/${uid}/${plan.label}`, `user/${uid}/${plan.label}`]
+    .find((candidate) => run('launchctl', ['print', candidate], { encoding: 'utf8', timeout: 10000 }).status === 0);
+  // kickstart -k delivers SIGTERM and waits (measured, launchd does not document it), so the
+  // server drains and releases its PID lock, and it needs no KeepAlive to come back.
+  return target ? ['launchctl', ['kickstart', '-k', target]] : null;
+}
+
+/**
+ * Bring a stale server to the release, when `planServerReplacement` allows it.
+ *
+ * An open connection holds this back so nobody's work is cut off, for as long as
+ * `holdLimitMs`: an open dashboard tab must not keep a host on an old release forever.
+ * Replaced means /health reports the release, never that the command returned.
+ *
+ * @returns the server status to report, with `replacement` saying what happened.
+ */
+export async function replaceStaleServer({
+  brainDir, server, globalRoot, previous, uid = process.getuid?.(), plan = planServerReplacement, connections = openServerConnections,
+  run = spawnSync, observe = runningServerStatus, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = Date.now,
+  idleWaitMs = 30000, healthWaitMs = 120000, pollMs = 2000, holdLimitMs = HOLD_LIMIT_MS,
+} = {}) {
+  let replacement;
+  try {
+    replacement = plan({ brainDir, globalRoot, latest: server.latest });
+    if (replacement.method !== 'restart') return { ...server, replacement };
+
+    const port = new URL(server.url).port;
+    const idleBy = now() + idleWaitMs;
+    let open = connections({ pid: replacement.pid, port });
+    while (open !== 0 && now() < idleBy) {
+      await sleep(pollMs);
+      open = connections({ pid: replacement.pid, port });
+    }
+    if (open !== 0) {
+      const heldSince = previous?.replacement?.state === 'held' ? previous.replacement.held_since : now();
+      if (now() - heldSince < holdLimitMs) {
+        const reason = open === null ? 'Open connections could not be read.' : `${open} connection(s) are open on the server.`;
+        return { ...server, replacement: { ...replacement, state: 'held', held_since: heldSince, reason } };
+      }
+    }
+
+    const command = restartCommand(replacement, { run, uid });
+    if (!command) return { ...server, replacement: { ...replacement, state: 'failed', reason: `launchd has no job ${replacement.label} for this user.` } };
+    const restarted = run(command[0], command[1], { encoding: 'utf8', timeout: 60000 });
+    if (restarted.error || restarted.status !== 0) {
+      const reason = `${command[0]} ${command[1].join(' ')} failed: ${restarted.error?.message || restarted.stderr?.trim() || `exit ${restarted.status}`}`;
+      return { ...server, replacement: { ...replacement, state: 'failed', reason } };
+    }
+
+    const healthyBy = now() + healthWaitMs;
+    let after;
+    do {
+      await sleep(pollMs);
+      after = await observe({ brainDir, latest: server.latest, timeoutMs: 5000 });
+    } while (after.status !== 'current' && now() < healthyBy);
+    if (after.status === 'current') return { ...after, replacement: { ...replacement, state: 'replaced', from: server.running } };
+    return { ...after, replacement: { ...replacement, state: 'failed', reason: `/health did not report ${server.latest} within ${healthWaitMs / 1000} seconds of the restart.` } };
+  } catch (error) {
+    return { ...server, replacement: { ...replacement, state: 'failed', reason: error.message } };
+  }
+}

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,
@@ -235,9 +258,8 @@ export function isProtocolPath(vfsPath = '') {
 }
 
 function stringifyDocument(data, body) {
-  // Prefer gray-matter when available; fall back to simple frontmatter dump.
   try {
-    return matter.stringify(body || '', data);
+    return matter.stringify({ content: body || '', data });
   } catch {
     const yaml = Object.entries(data)
       .map(([key, value]) => `${key}: ${JSON.stringify(value)}`)
@@ -278,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;
@@ -393,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 = [

package/src/core/startup-health.mjs

@@ -148,7 +148,12 @@ export async function startupHealth({ cwd = process.cwd(), brainDir, brainUrl =
       remoteDaemon = { status: body.daemon === 'running' ? 'running' : ['dead', 'stopped', 'not-started'].includes(body.daemon) ? 'stopped' : 'unknown', source: 'remote-health' };
       if (local) {
         const own = identity(serverFile, path.join(packageRoot, 'src', 'server', 'index.mjs'));
-        if (own.status !== 'running') return { status: own.status === 'conflict' ? 'conflict' : 'unknown', reason: 'server-process-unverified' };
+        if (own.status !== 'running') {
+          const actualRoot = own.entry?.endsWith(path.join('src', 'server', 'index.mjs'))
+            ? path.resolve(path.dirname(own.entry), '../..') : null;
+          return { status: own.status === 'conflict' ? 'conflict' : 'unknown',
+            reason: actualRoot ? `server runs from ${actualRoot}; expected ${packageRoot}; run total-recall server ensure` : 'server-process-unverified' };
+        }
         if (!await listener(own.pid, new URL(brainUrl), { run, cwd })) return { status: 'unknown', reason: 'server-listener-unverified' };
       }
       const drift = local && verdict.status === 'ready' ? serverCodeDrift(verdict.version, onDiskVersion()) : null;