total-recall-brain 3.45.0 → 3.46.0

package/src/cli/plugin/chunks.mjs

@@ -0,0 +1,145 @@
+import { parseArgs } from 'node:util';
+import fs from 'node:fs';
+import path from 'node:path';
+import { auditUiChunkCoverage, getUiChunk, searchUiChunks, uiChunkRegistryPath, validateUiChunkFile } from '../../core/ui-chunks.mjs';
+import { chooseUiChunk } from '../../core/ui-chunk-choice.mjs';
+import { callApi } from '../api.mjs';
+
+const help = [
+  'Usage: total-recall plugin chunks [query] [--plugin ID] [--surface page|left|right|bottom] [--limit N] [--decision|--workspace] [--brain ID] [--json]',
+  '       total-recall plugin chunks get <plugin:id> [--surface SURFACE] [--workspace] [--brain ID] [--json]',
+  '       total-recall plugin chunks validate <file> [--plugin-dir DIR] [--json]',
+  '       total-recall plugin chunks registry',
+  '       total-recall plugin chunks coverage [--plugin ID] [--json]',
+  '       total-recall plugin chunks add <id.md> --plugin ID [--brain ID] [--json]',
+  '       total-recall plugin chunks page <id> --brain ID [--json]',
+  '       total-recall plugin chunks page <id> <plugin:block>... --brain ID (--title TITLE | --revision VERSION) [--json]',
+  '',
+  'Use --decision with a concise, non-sensitive query to request a ranked choice through the configured Decision plugin.',
+  'Search and validation run locally by default. Decision requests send only the query and up to 20 eligible metadata records.',
+  'Agents use total-recall decision compose to publish a Jev-selected page.',
+].join('\n');
+
+export async function runPluginChunks(args) {
+  const asJson = args.includes('--json');
+  try {
+    const { values, positionals } = parseArgs({
+      args,
+      allowPositionals: true,
+      options: {
+        json: { type: 'boolean' },
+        help: { type: 'boolean', short: 'h' },
+        decision: { type: 'boolean' },
+        workspace: { type: 'boolean' },
+        brain: { type: 'string' },
+        surface: { type: 'string' },
+        plugin: { type: 'string' },
+        limit: { type: 'string' },
+        'plugin-dir': { type: 'string' },
+        title: { type: 'string' },
+        revision: { type: 'string' },
+      },
+    });
+    if (values.help) return console.log(help);
+
+    const [verb, target, ...extra] = positionals;
+    if (verb === 'page') {
+      const { brain, title, revision } = values;
+      if (!target || !brain?.trim() || values.plugin || values.workspace || values.decision || values.surface || values.limit || values['plugin-dir']) throw new Error(help);
+      const writing = extra.length > 0;
+      const create = typeof title === 'string' && title.trim() && revision === undefined;
+      const edit = typeof revision === 'string' && revision.trim() && title === undefined;
+      if (writing ? !create && !edit : title !== undefined || revision !== undefined) throw new Error(help);
+      const collection = '/api/workspace/pages';
+      const detail = collection + '/' + encodeURIComponent(target);
+      const response = !writing
+        ? await callApi('GET', detail, { query: { brain } })
+        : await callApi(edit ? 'PUT' : 'POST', edit ? detail : collection, {
+          data: JSON.stringify({ id: target, brainId: brain, title, revision, keys: extra }),
+        });
+      if (!response.ok) throw new Error(response.body?.error || 'Could not access the saved page.');
+      const page = response.body;
+      if (asJson) return console.log(JSON.stringify({ ok: true, ...page }));
+      console.log(page.path || `${page.title} (${page.version})`);
+      for (const chunk of page.chunks) console.log(chunk.key);
+      return;
+    }
+    if (values.title !== undefined || values.revision !== undefined) throw new Error(help);
+    if (values.brain !== undefined && ((!values.workspace && verb !== 'add') || !values.brain.trim())) {
+      throw new Error('--brain requires a registered brain ID and --workspace, or an add operation.');
+    }
+    if (values.workspace && (values.decision || ['add', 'coverage', 'registry', 'validate'].includes(verb))) throw new Error(help);
+    if (verb === 'add') {
+      if (!target || !values.plugin || extra.length || values.decision || values.surface || values.limit || values['plugin-dir'] || path.extname(target) !== '.md') throw new Error(help);
+      const stat = fs.statSync(target);
+      if (!stat.isFile() || stat.size > 64 * 1024) throw new Error('Choose a Markdown block no larger than 64 KiB.');
+      const markdown = fs.readFileSync(target, 'utf8');
+      const { ok, body } = await callApi('POST', '/api/ui-chunks/pool', {
+        data: JSON.stringify({ plugin: values.plugin, id: path.basename(target, '.md'), markdown, brainId: values.brain }),
+      });
+      if (!ok) throw new Error(body?.error || 'The dashboard could not add the block.');
+      return console.log(asJson ? JSON.stringify({ ok, ...body }) : 'Added ' + body.chunk.key);
+    }
+    if (verb === 'coverage') {
+      if (target || values.decision || values.surface || values.limit || values['plugin-dir']) throw new Error(help);
+      const plugins = auditUiChunkCoverage({ plugin: values.plugin });
+      if (values.plugin && !plugins.length) throw new Error('Plugin is not installed.');
+      if (asJson) return console.log(JSON.stringify({ ok: true, plugins }));
+      for (const item of plugins) {
+        const bound = item.operations.total - item.operations.missing.length;
+        console.log(`${item.plugin}: ${item.pageBlocks} page blocks, ${bound}/${item.operations.total} operations, ${item.dataBindings.length} data bindings, design ${item.design || 'missing'}${item.partial ? ' (partial audit)' : ''}`);
+      }
+      return;
+    }
+    if (verb === 'registry') {
+      if (target || values.decision || values.surface || values.plugin || values.limit || values['plugin-dir']) throw new Error(help);
+      return console.log(asJson ? JSON.stringify({ ok: true, file: uiChunkRegistryPath }) : uiChunkRegistryPath);
+    }
+    if (verb === 'validate') {
+      if (!target || extra.length || values.decision || values.surface || values.plugin || values.limit) throw new Error(help);
+      const chunk = validateUiChunkFile(target, { pluginDir: values['plugin-dir'] });
+      return console.log(asJson ? JSON.stringify({ ok: true, chunk }) : 'Validated ' + chunk.key);
+    }
+    if (values['plugin-dir']) throw new Error('--plugin-dir is only available with validate.');
+    if (verb === 'get') {
+      if (!target || extra.length || values.decision || values.plugin || values.limit) throw new Error(help);
+      const [plugin, id, ...rest] = target.split(':');
+      if (!plugin || !id || rest.length) throw new Error('Specify a chunk as plugin:id.');
+      const query = values.surface ? { surface: values.surface } : {};
+      if (values.brain) query.brain = values.brain;
+      const chunk = values.workspace
+        ? (await callApi('GET', `/api/ui-chunks/${encodeURIComponent(plugin)}/${encodeURIComponent(id)}`, { query })).body?.chunk
+        : getUiChunk(plugin, id, { surface: values.surface });
+      if (!chunk) throw new Error('UI chunk unavailable.');
+      return console.log(asJson ? JSON.stringify({ ok: true, chunk }) : chunk.html);
+    }
+
+    const query = positionals.join(' ').trim();
+    const limit = values.limit === undefined ? undefined : Number(values.limit);
+    if (values.decision && !query) throw new Error('--decision requires an explicit query.');
+    let result;
+    if (values.workspace) {
+      const filters = Object.fromEntries(Object.entries({ plugin: values.plugin, surface: values.surface, q: query, limit, brain: values.brain }).filter(([, value]) => value !== undefined));
+      const response = await callApi('GET', '/api/ui-chunks', { query: filters });
+      if (!response.ok) throw new Error(response.body?.error || 'The dashboard could not read the workspace pool.');
+      result = response.body;
+    } else {
+      result = searchUiChunks({ plugin: values.plugin, surface: values.surface, query, limit });
+    }
+    if (values.decision) result.selection = await chooseUiChunk(result.chunks, query, values.surface);
+    if (asJson) return console.log(JSON.stringify({ ok: true, ...result }));
+    for (const chunk of result.chunks) console.log(chunk.key + '  ' + chunk.title + '  [' + chunk.surfaces.join(', ') + ']');
+    if (!result.chunks.length) console.log('No eligible UI chunks.');
+    for (const issue of result.diagnostics) {
+      console.error(issue.plugin + (issue.id ? ':' + issue.id : '') + '  ' + issue.message);
+    }
+    if (result.selection) {
+      const { key, source, reason } = result.selection;
+      console.log('Selection (' + source + '): ' + (key ?? 'none') + (reason ? ' (' + reason + ')' : ''));
+    }
+  } catch (error) {
+    process.exitCode = 1;
+    if (asJson) console.log(JSON.stringify({ ok: false, error: error.message }));
+    else console.error(error.message);
+  }
+}

package/src/cli/plugin/create.mjs

@@ -113,10 +113,7 @@ export async function createPlugin(args = []) {
   // Every plugin is installed in the shared folder; --global is accepted and changes nothing.
   let withCli = args.includes("--with-cli");
   const withGenerator = args.includes("--with-generator");
-  // A card face is bespoke owner code, authored by hand once the plugin's
-  // function is understood. The scaffold deliberately ships without one, so
-  // there is nothing to generate here; `--with-ui` is accepted only to explain
-  // that to anyone who asks for it.
+  // The owner authors the native Home after defining the plugin's workflows.
   const asksForUi = args.includes("--with-ui");
   const withTask = args.includes("--with-task");
   const createGithub = args.includes("--github");
@@ -251,17 +248,15 @@ export async function createPlugin(args = []) {
     version: "0.1.0",
     description: pluginDesc,
     license: "MIT",
-    // Declares this plugin as a fresh scaffold so it can install before its
-    // bespoke card face exists. Remove the flag when the face is authored.
+    auth: { plugin: "auth", methods: ["passkey", "google-oauth2"], session_verification: true },
+    // An unfinished scaffold can install while the owner writes its Home.
     scaffold: true,
     // How work reaches this plugin. `preflight coverage` reports it until tasks are written.
     gate: { tasks: [], owned_commands: [] }
   };
   if (useCases.length > 0) manifest.use_cases = useCases;
 
-  // House rule: a plugin for a service that needs an API key ships a CLI to save
-  // it, so it works the moment the key is pasted. Its card face is authored by
-  // hand later, like every other face.
+  // A plugin with a provider credential can save it through the shared Auth CLI.
   if (apiKeys.length) {
     withCli = true;
     manifest.secrets = apiKeys.map((key) => ({ key, description: `${pluginName} service API key (paste it in the plugin UI)`, required: true }));
@@ -301,8 +296,7 @@ export async function createPlugin(args = []) {
         ]
       });
     }
-    // The card contract reads the plugin's real state through a declared read
-    // command; a scaffold without this shows no live status.
+    // Give the Home a declared read operation for live status.
     manifest.status = { command: "status", refresh_seconds: 60 };
 
     const cliContent = `#!/usr/bin/env node
@@ -358,12 +352,6 @@ export default run;
     manifest.tasks = [{ intent: taskIntent, schedule: taskSchedule, command: taskCommand, placement: 'selected-node' }];
   }
 
-  // No UI is generated. Every plugin must have a card face, but a face is
-  // bespoke owner code authored by hand once the plugin's function is known:
-  // a generated stub is what produced a ecosystem of identical cards. The
-  // scaffold therefore reports the face as outstanding rather than faking one.
-  const cardOutstanding = true;
-
   if (isCapability) {
     manifest.deploy = {
       targets: ["ssss-app", "nextjs", "react", "flask"],
@@ -445,19 +433,12 @@ export default generateContext;
     fs.writeFileSync(path.join(pluginDir, "generator.mjs"), generatorContent, "utf8");
   }
 
-  manifest.capability = {
-    entry: "capability/index.mjs",
-    exports: ["getCapabilityStatus"]
-  };
-
   const validation = validatePluginManifest(manifest);
   if (!validation.valid) {
     console.error("❌ Validation failed for generated manifest:", validation.errors);
     fs.rmSync(pluginDir, { recursive: true, force: true });
     process.exit(1);
   }
-  // The scaffold installs without a card face, and says so. Its face is
-  // authored by hand next; the warning is the reminder, not a failure.
   if (validation.warnings?.length) {
     for (const warning of validation.warnings) console.log(`⚠️  ${warning}`);
   }
@@ -492,7 +473,7 @@ export default generateContext;
   if (category) lines.push(`- **SSSS Category**: \`${category}\``);
   if (withCli) lines.push(`- **CLI Command**: \`npx total-recall ${id}\``);
   if (withTask) lines.push(`- **Scheduled task**: \`${taskCommand}\` at \`${taskSchedule}\` (selected node; implement the command and choose a node before use)`);
-  if (asksForUi) lines.push('- **UI**: no card face is generated. Author `ui/card.js` and `ui/DESIGN.md` by hand for this plugin\'s own function, then declare the face in `ui.elements[]`');
+  if (asksForUi) lines.push('- **UI**: author the plugin workspace and its native panels for this plugin’s own function. Declare the panels in `ui.elements[]`.');
   if (apiKeys.length) lines.push('- **API key**: paste it in the plugin UI (`save-token` event) or pipe it to `npx total-recall ' + id + ' token set --stdin`; stored as `' + apiKeys[0] + '` in the secrets store');
   lines.push(
     "",
@@ -506,6 +487,24 @@ export default generateContext;
     ""
   );
 
+  lines.push(
+    "## Authoring generative UI",
+    "",
+    "Keep a bespoke `DESIGN.md` at the plugin root. Describe the palette, typography, layout, interaction and accessibility. Work with the user on the design and assets. Package this file and the authored blocks with the plugin.",
+    "",
+    "Author one SSSS Markdown document per reusable block at `ui/chunks/<id>.md`. Use `type: ui-chunk:chunk`, the manifest ID as `plugin`, the filename stem as `id`, a `title`, `description`, ISO `timestamp`, meaningful `intents` and supported `surfaces` from `page`, `left`, `right` and `bottom`. Use raw HTML for the body.",
+    "",
+    "Declare the native workspace entry in `ui.home` and its design in `ui.design_tokens`. Bind each block to exact manifest operation names in `operations` and verified fields in `data` using `operation:/json/pointer`. Declare browser-safe inputs so users can run the operation in place. Use a native `panel` for specialized editable controls. Keep credentials and private data out of routing metadata.",
+    "",
+    "Find the extension with `total-recall plugin chunks registry` and verify each block with `total-recall plugin chunks validate <file>`. Compare `total-recall plugin chunks coverage --plugin <id>` with the owner inventory. Use `total-recall plugin chunks <intent> --surface <surface>` to find blocks. Add `--decision` to request an explicit typed choice. The result identifies a block by its stable `plugin:id`.",
+    "",
+    "Keep packaged defaults in the owner repository. Users can choose and arrange installed blocks, provide their own HTML and edit the design with their agent. Submit broadly useful owner changes to the plugin repository.",
+    "",
+    "An agent can author any additional SSSS block for an enabled plugin. For a task-specific block, use `total-recall plugin chunks add <id.md> --plugin <owner> --brain <brain> --json` to validate and publish it. Read the result back by its stable `owner:id` key.",
+    "",
+    "For contextual selection, use `total-recall decision compose --plugin <owner> --intent <intent> --page <id> --title <title> --brain <brain>`. For exact placement, use `total-recall plugin chunks page <id> <owner:block>... --title <title> --brain <brain>`. To edit an existing page, read it with the same command without block keys, then pass its complete ordered keys and `--revision <version>` instead of `--title`. Reopen the saved page and verify each workflow against real data.",
+    ""
+  );
   fs.writeFileSync(path.join(pluginDir, "README.md"), lines.join("\n"), "utf8");
 
   // ── Standalone repository files ──────────────────────────────────────────
@@ -533,34 +532,7 @@ export default generateContext;
   fs.writeFileSync(path.join(pluginDir, '.gitignore'), 'node_modules/\n.env*\n.agent/skills/total-recall/\ndist/\nreports/\n.DS_Store\nINSTRUCTIONS.md\nAGENTS.md\n', 'utf8');
   fs.writeFileSync(path.join(pluginDir, 'LICENSE'), mitLicense(holder), 'utf8');
 
-  // Capability brick
-  fs.mkdirSync(path.join(pluginDir, 'capability'), { recursive: true });
-  fs.writeFileSync(path.join(pluginDir, 'capability', 'index.mjs'), `/**
- * Portable capability brick for ${pluginName}.
- * Zero host dependencies; pure portable JavaScript.
- */
-export async function getCapabilityStatus() {
-  return { ready: true, initialized: true };
-}
-`, 'utf8');
-  fs.writeFileSync(path.join(pluginDir, 'capability', 'BRICK.md'), `# ${pluginName} — Capability Brick
-
-Portable core capability for ${pluginName}.
-
-## Exported Functions
-- \`getCapabilityStatus()\`: Returns capability readiness and initialization status.
-`, 'utf8');
-
   fs.mkdirSync(path.join(pluginDir, 'test'), { recursive: true });
-  fs.writeFileSync(path.join(pluginDir, 'test', 'capability.test.mjs'), `import test from 'node:test';
-import assert from 'node:assert/strict';
-import { getCapabilityStatus } from '../capability/index.mjs';
-
-test('capability brick loads and exports status', async () => {
-  const status = await getCapabilityStatus();
-  assert.equal(status.ready, true);
-});
-`, 'utf8');
   fs.writeFileSync(path.join(pluginDir, 'test', 'manifest.test.mjs'), `import test from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';

package/src/cli/plugin/index.mjs

@@ -10,6 +10,7 @@ import { getPlugin, getPluginMonetization, globalPluginsDir, projectPluginsDir }
 import { describePlugin, pruneReplacementArchives, replacementArchiveDir } from '../../core/plugin-store.mjs';
 import { buildPluginCatalog } from '../../core/plugin-catalog.mjs';
 import { setPluginActive } from '../../core/plugin-activation.mjs';
+import { detectProjectBrain } from '../../core/brain-locate.mjs';
 
 function printHelp() {
   console.log(`
@@ -26,6 +27,7 @@ Usage:
 Commands:
   list                      Installed plugins (project & global) with source and sharing
   library [--plugin ID]      Installed CLI operation library (--json for agents)
+  chunks [query]            Search installed SSSS UI chunks and validate owner files
   refresh                   Rebuild installed command inventories and instruction surfaces
   copies [dir] [--apply]    Audit repository copies of shared defaults and shadow links. --apply
                             deletes bundled matches, unlinks shadows (on/off records are kept)
@@ -39,6 +41,7 @@ Commands:
   on <id> / off <id>         Enable/disable host execution for this repository alone
                               --all-repos   Change the shared setting for every repository
                               --clear       Drop this repository's override; follow the shared setting
+  on-use <id>                Activate when deliberately opened or used in this repository
   available [query]         Plugins bundled with this Total Recall package
   peers [query]             Plugins your mesh peers share (queried live)
   search <query>            Search bundled plugins and mesh peers
@@ -75,7 +78,7 @@ Commands:
                               --category <cat>      Declare an SSSS memory category
                               --with-cli            Generate CLI command handler
                               --with-generator      Generate context generator
-                              --with-ui             Generate token-driven panel element
+                              --with-ui             Include owner UI authoring instructions
                               --with-task           Declare a selected-node scheduled task
                               --task-command <cmd>  Task CLI subcommand (requires --with-task)
                               --task-schedule <cron> Five-field local-time schedule
@@ -116,33 +119,41 @@ export async function run(argv = []) {
     if (!result.ok || !setup.ok) process.exitCode = 1;
     return;
   }
-  if (command === 'on' || command === 'off') {
+  if (['on', 'off', 'on-use'].includes(command)) {
+    const projectRoot = detectProjectBrain(process.cwd())?.projectRoot ?? process.cwd();
     const id = rest.find(argument => !argument.startsWith('-'));
     if (!id) throw new Error(`Usage: total-recall plugin ${command} <id> [--all-repos|--clear]`);
     const flags = rest.filter(argument => argument.startsWith('-'));
+    if (command === 'on-use' && flags.some(flag => flag !== '--json')) throw new Error('Use on-use for one repository without --all-repos or --clear.');
     const unknown = flags.find(flag => !['--all-repos', '--clear', '--json'].includes(flag));
     if (unknown) throw new Error(`Unsupported plugin ${command} option: ${unknown}`);
     if (flags.includes('--all-repos') && flags.includes('--clear')) throw new Error('Choose --all-repos or --clear, not both');
     if (flags.includes('--clear')) {
       if (command === 'off') throw new Error('--clear removes a repository override; use it with on, not off');
-      const cleared = await setPluginActive(id, true, { clear: true });
+      const cleared = await setPluginActive(id, true, { clear: true, projectRoot });
       const activation = cleared.activation || {};
       console.log(flags.includes('--json') ? JSON.stringify(cleared)
         : `♻️  ${id} follows the shared setting again in this repository (${activation.state || 'unknown'})`);
       if (!cleared.compilation.ok) process.exitCode = 1;
       return;
     }
-    const result = await setPluginActive(id, command === 'on', { scope: flags.includes('--all-repos') ? 'shared' : 'project' });
+    const result = await setPluginActive(id, command === 'on-use' ? command : command === 'on', { projectRoot, scope: flags.includes('--all-repos') ? 'shared' : 'project' });
     const activation = result.activation || {};
     if (flags.includes('--json')) console.log(JSON.stringify(result));
-    else console.log(`${command === 'on' ? '✅' : '⛔'} ${id} ${command === 'on' ? 'enabled' : 'disabled'} for ${result.scope === 'shared' ? 'every repository' : 'this repository'} (${activation.state || 'unknown'})`);
-    if (!result.compilation.ok) process.exitCode = 1;
+    else if (command === 'on-use') console.log(`${id} will activate on use in this repository.`);
+    else {
+      console.log(`${command === 'on' ? '✅' : '⛔'} ${id} ${command === 'on' ? 'enabled' : 'disabled'} for ${result.scope === 'shared' ? 'every repository' : 'this repository'} (${activation.state || 'unknown'})`);
+      if (result.cleanup?.state === 'archived') console.log('Repository plugin state archived.');
+      if (result.cleanup?.state === 'restored') console.log('Repository plugin state restored.');
+      if (result.cleanup?.ok === false) console.error(`Cleanup pending. ${result.cleanup.error}`);
+    }
+    if (!result.compilation.ok || result.cleanup?.ok === false) process.exitCode = 1;
     return;
   }
 
-  if (command === 'card' || command === 'card-face' || command === 'skin') {
-    await managePluginCard(rest);
-    return;
+  if (command === 'chunks') {
+    const { runPluginChunks } = await import('./chunks.mjs');
+    return runPluginChunks(rest);
   }
 
   if (rest.includes('--help') || rest.includes('-h')) {

package/src/cli/setup.mjs

@@ -22,6 +22,7 @@ import path from 'node:path';
 import https from 'node:https';
 import { fileURLToPath } from 'node:url';
 import { resolveAgentDir, resolveBrainDir } from './agent-dir.mjs';
+import { writeBrainConnection } from '../core/memory-brain.mjs';
 const { loadSecrets, saveSecrets } = await __loadOwnedPlugin('auth', 'secrets-store');
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -375,15 +376,7 @@ async function getGitHubUser(githubToken) {
 // ─── Store brain config ───────────────────────────────────────────────────────
 
 async function storeBrainConfig(brDir, brainUrl, token, provider, apiKey, extra = {}) {
-  const configDir = path.join(brDir, 'config');
-  fs.mkdirSync(configDir, { recursive: true });
-
-  // brain.json
-  fs.writeFileSync(
-    path.join(configDir, 'brain.json'),
-    JSON.stringify({ url: brainUrl, token, provider, ...extra }, null, 2),
-    'utf8'
-  );
+  writeBrainConnection(brDir, { url: brainUrl, token, provider, ...extra });
 
   // secrets.enc
   let secrets = {};

package/src/cli/start.mjs

@@ -39,6 +39,7 @@ export default function start(args) {
     --help           Show this help
 
   The server reads config from ~/.agent/config/security.yml.
+  TR_DASHBOARD_BRAIN_DIR can select the dashboard's global memory and project registry.
   Use Cloudflare or Caddy in front for HTTPS when accessing remotely.
 `);
     return;

package/src/cli/startup.mjs

@@ -16,6 +16,23 @@ export async function inspectStartup(options = {}) {
   return startupHealth({ brainDir: globalBrain, brainUrl: url, token, brainId: cfg.layer === 'project' && cfg.name ? `project:${cfg.name}` : null, ...options });
 }
 
+/**
+ * One line per thing a session should see at start: a dashboard older than its
+ * sources, and each plugin startup check that needs attention or could not run.
+ */
+export function startupFindings(report) {
+  const lines = [];
+  const dashboard = report.dashboard;
+  if (dashboard && ['stale', 'missing'].includes(dashboard.status)) {
+    lines.push(`Dashboard: bundle ${dashboard.status}${dashboard.newer_source ? ` (${dashboard.newer_source} is newer)` : ''}; the server rebuilds it, see /health dashboard.`);
+  } else if (dashboard?.status === 'unknown') lines.push(`Dashboard: freshness unknown (${dashboard.reason}).`);
+  for (const check of report.plugin_checks || []) {
+    if (check.status === 'attention') lines.push(`${check.command}: ${check.summary}`);
+    else if (check.status === 'unavailable') lines.push(`${check.command}: unavailable (${check.reason})${check.summary ? ` ${check.summary}` : ''}`);
+  }
+  return lines;
+}
+
 export default async function startup(args = []) {
   if (!args.length || args.includes('--help') || args.includes('-h')) {
     console.log('Usage: total-recall startup check|ensure [--json] [--app-check <registered-repo-command>] [--app-start <registered-repo-command>]\ncheck is read-only. ensure starts only missing configured local managed services and an explicitly declared current-repo app command; never restarts running/unknown or remote services. SSSS is checked as tooling, not a fabricated daemon. App health JSON must contain ok:true and status:ready|healthy|running. No declaration means app readiness is unknown.');
@@ -39,6 +56,7 @@ export default async function startup(args = []) {
     if (report.server?.reason) console.log(`Server: ${report.server.reason}`);
     if (report.server?.stale) console.log(`Server: running ${report.server.stale.running} with ${report.server.stale.on_disk} on disk; it has not been replaced.`);
     for (const error of report.required_plugins?.errors || []) console.log(`Required plugin: ${error}`);
+    for (const line of startupFindings(report)) console.log(line);
     const harnesses = await queryHarnessUsage().catch(() => []);
     const availH = harnesses.filter(h => h.available);
     const readyH = availH.filter(h => h.authed);

package/src/core/app-deploy/design-tokens.mjs

@@ -62,38 +62,43 @@ export function extractFrontmatter(content) {
  * @returns {object}
  */
 export function resolveTokenReferences(tokens) {
+  let visits = 0;
+  function checkBudget(depth) {
+    if (++visits > 20_000 || depth > 64) throw new DesignTokenError(['token references exceed the expansion limit']);
+  }
+
   function getNested(obj, pathParts) {
     let curr = obj;
     for (const p of pathParts) {
-      if (curr === undefined || curr === null) return undefined;
+      if (!isPlainObject(curr) || !Object.hasOwn(curr, p)) return undefined;
       curr = curr[p];
     }
     return curr;
   }
 
-  function resolveVal(val, seen) {
+  function resolveVal(val, seen, depth) {
+    checkBudget(depth);
     if (typeof val !== 'string') return val;
     const whole = val.match(/^\{([a-zA-Z0-9_.-]+)\}$/);
     if (whole && !seen.has(whole[1])) {
       const target = getNested(tokens, whole[1].split('.'));
       // A whole-value reference may point at a composite (e.g. a typography style).
-      if (isPlainObject(target)) return walk(target, new Set([...seen, whole[1]]));
+      if (isPlainObject(target)) return walk(target, new Set([...seen, whole[1]]), depth + 1);
     }
     return val.replace(/\{([a-zA-Z0-9_.-]+)\}/g, (match, tokenPath) => {
       if (seen.has(tokenPath)) return match;
       const resolved = getNested(tokens, tokenPath.split('.'));
       if (typeof resolved === 'string' || typeof resolved === 'number') {
-        return String(resolveVal(resolved, new Set([...seen, tokenPath])));
+        return String(resolveVal(resolved, new Set([...seen, tokenPath]), depth + 1));
       }
       return match;
     });
   }
 
-  function walk(node, seen = new Set()) {
-    if (!isPlainObject(node)) return resolveVal(node, seen);
-    const out = {};
-    for (const [k, v] of Object.entries(node)) out[k] = walk(v, seen);
-    return out;
+  function walk(node, seen = new Set(), depth = 0) {
+    checkBudget(depth);
+    if (!isPlainObject(node)) return resolveVal(node, seen, depth);
+    return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, walk(v, seen, depth + 1)]));
   }
 
   return walk(tokens);

package/src/core/app-deploy/ui-elements.mjs

@@ -251,7 +251,7 @@ export function generateUiElements(manifest, { pluginDir, target, tokens, typesc
   };
   add(UI_MANIFEST_FILE, `${JSON.stringify(uiManifest, null, 2)}\n`);
 
-  const first = elements[0];
+  const first = elements.find(element => element.id === spec.home) ?? elements[0];
   const hasTokens = Boolean(tokenInfo.source);
   const usage = (target === 'react'
     ? [

package/src/core/brain-registry.mjs

@@ -24,6 +24,11 @@ export function globalBrainDirFor(env = process.env) {
   return path.join(agentDir, 'skills', 'total-recall');
 }
 
+/** The dashboard can read a host brain while preview plugin state stays isolated. */
+export function dashboardBrainDir(env = process.env, fallback = globalBrainDirFor(env)) {
+  return env.TR_DASHBOARD_BRAIN_DIR ? path.resolve(env.TR_DASHBOARD_BRAIN_DIR) : fallback;
+}
+
 function togglesPath(globalBrainDir) {
   return path.join(globalBrainDir, 'config', 'brain-toggles.json');
 }

package/src/core/brain-updates.mjs

@@ -340,7 +340,11 @@ export async function updateAllBrains(opts = {}) {
       // A lockfile-only update builds no tree, so it runs no lifecycle scripts: npm still
       // ran a checkout's own postinstall here, which fails in a repository that was never
       // installed (a postinstall calling a tool that is not yet installed, 2026-11-09).
-      else if (!needsInstall) args.push(group.manager === 'pnpm' ? '--lockfile-only' : '--package-lock-only', '--ignore-scripts');
+      // Only where no tree exists: npm's lockfile-only mode also rewrites the tree record
+      // (node_modules/.package-lock.json) to versions it never installs, and npm then reports the
+      // stale tree "up to date" forever (21 plugins on @ssss/cli 0.14.4 under 0.14.5, 2026-11-12).
+      // A tree that exists gets a real install, so the tree and its record agree.
+      else if (!needsInstall && noInstallTree(group.owner)) args.push(group.manager === 'pnpm' ? '--lockfile-only' : '--package-lock-only', '--ignore-scripts');
       const install = exec(group.manager, args, { cwd: group.owner, env: installEnv(), encoding: 'utf8',
         timeout: 600000, maxBuffer: 8 * 1024 * 1024 });
       if (install.status !== 0) throw new Error(install.error?.message || install.stderr?.trim().slice(-1500) || `Install exited ${install.status}`);

package/src/core/daemon-control.mjs

@@ -33,7 +33,11 @@ export function getDaemonObservation() { return observeDaemon(brainDir); }
  * @returns {'running'|'dead'|'not_started'|'conflict'|'unknown'}
  */
 export function getDaemonStatus() {
-  const { status } = getDaemonObservation();
+  // A supervised daemon can run from a different verified installation than the server.
+  const entry = process.env.TR_SUPERVISED_DAEMON_ENTRY;
+  const { status } = process.env.DISABLE_DAEMON === 'true' && entry && path.isAbsolute(entry)
+    ? observeDaemon(brainDir, { expectedEntry: entry })
+    : getDaemonObservation();
   return status === 'not-started' ? 'not_started' : status === 'stopped' ? 'dead' : status;
 }