total-recall-brain 3.45.0 → 3.46.1

package/src/core/plugin-store.mjs

@@ -31,8 +31,8 @@ import {
 } from './plugin-bundle.mjs';
 import { writeVfsDocument, patchVfsDocument, deleteVfsDocument, appendVfsEvent } from './ssss-operation-service.mjs';
 import { findVfsDocumentByPath } from './vfs-documents.mjs';
-import { readActivationRecord, projectActivationOverride } from './plugin-state.mjs';
-import { REQUIRED_INSTALLATION_PLUGIN_IDS } from './default-plugins.mjs';
+import { readActivationRecord, projectActivationOverride, pluginActivation } from './plugin-state.mjs';
+import { DEFAULT_PLUGIN_IDS, REQUIRED_INSTALLATION_PLUGIN_IDS } from './default-plugins.mjs';
 
 const execFileAsync = promisify(execFile);
 const ID_PATTERN = /^[a-z][a-z0-9-]{1,63}$/;
@@ -183,7 +183,7 @@ export async function patchPluginRecord(plugin, patches) {
  * setting so it follows the shared one again. The overlay never installs the
  * plugin: a repository without it uses the shared folder's copy.
  */
-export async function patchProjectActivationRecord(id, projectRoot, runtimeEnabled, { manifest = null } = {}) {
+export async function patchProjectActivationRecord(id, projectRoot, runtimeEnabled, { manifest = null, onUse = false } = {}) {
   if (!ID_PATTERN.test(id)) throw new Error('Invalid plugin identity');
   const pluginsDir = projectPluginsDir(projectRoot);
   const vaultRoot = vaultForPluginsDir(pluginsDir);
@@ -194,7 +194,7 @@ export async function patchProjectActivationRecord(id, projectRoot, runtimeEnabl
   if (runtimeEnabled === null) {
     const existing = readProjectActivationRecord(id, projectRoot);
     if (!existing) return null;
-    const { runtime_enabled: _dropped, ...frontmatter } = { ...(existing.frontmatter || {}) };
+    const { runtime_enabled: _dropped, runtime_on_use: _onUse, ...frontmatter } = { ...(existing.frontmatter || {}) };
     await writeVfsDocument(recordPath(id), {
       ...frontmatter,
       type: 'plugin_record',
@@ -210,7 +210,7 @@ export async function patchProjectActivationRecord(id, projectRoot, runtimeEnabl
   if (typeof runtimeEnabled !== 'boolean') throw new Error('Plugin activation requires a boolean or null');
   const previous = readProjectActivationRecord(id, projectRoot);
   if (previous) {
-    return patchVfsDocument(recordPath(id), { runtime_enabled: runtimeEnabled, timestamp: now }, {
+    return patchVfsDocument(recordPath(id), { runtime_enabled: runtimeEnabled, runtime_on_use: onUse, timestamp: now }, {
       actorRole: 'system',
       intent: `Set repository activation for plugin ${id}`,
       vaultRoot
@@ -226,6 +226,7 @@ export async function patchProjectActivationRecord(id, projectRoot, runtimeEnabl
     category: 'plugins',
     tags: ['plugin', 'activation-override'],
     runtime_enabled: runtimeEnabled,
+    runtime_on_use: onUse,
     source: { kind: 'shared', ref: globalPluginsDir() }
   };
   await writeVfsDocument(recordPath(id), frontmatter, buildPluginDocumentBody(m, id), {
@@ -236,8 +237,19 @@ export async function patchProjectActivationRecord(id, projectRoot, runtimeEnabl
   return frontmatter;
 }
 
+function describeActivation(plugin, projectRoot) {
+  const required = REQUIRED_INSTALLATION_PLUGIN_IDS.includes(plugin.id);
+  try {
+    const { state, enabled, mode } = pluginActivation(plugin, { projectRoot });
+    return { state, enabled, required, ...(mode ? { mode } : {}) };
+  } catch {
+    // An unreadable repository policy is an error, never shared enablement.
+    return { state: 'error', enabled: false, required };
+  }
+}
+
 /** Facts about one installed plugin, merged with its record. */
-export function describePlugin(plugin) {
+export function describePlugin(plugin, projectRoot = process.cwd()) {
   const record = readPluginRecord(plugin);
   const m = plugin.manifest || {};
   let current = null;
@@ -248,6 +260,7 @@ export function describePlugin(plugin) {
   const taskRuns = record?.task_runs || {};
   return {
     id: plugin.id,
+    core: DEFAULT_PLUGIN_IDS.includes(plugin.id),
     name: m.name || plugin.id,
     version: m.version || '0.0.0',
     description: m.description || '',
@@ -284,13 +297,18 @@ export function describePlugin(plugin) {
     ui: m.ui || null,
     configuration: m.configuration || null,
     manifest: m,
-    card_face: record?.card_face || m.card_face || null,
-    activation: { state: plugin.valid && record?.runtime_enabled !== false ? 'active' : 'inactive', enabled: plugin.valid && record?.runtime_enabled !== false }
+    activation: describeActivation(plugin, projectRoot)
   };
 }
 
-export function listInstalledPlugins(projectRoot = process.cwd()) {
-  return discoverPlugins(projectRoot).map(describePlugin);
+export function listInstalledPlugins(projectRoot = process.cwd(), { descriptions } = {}) {
+  return discoverPlugins(projectRoot).map(plugin => {
+    const description = descriptions?.get(plugin.dir);
+    if (description) return { ...description, activation: describeActivation(plugin, projectRoot) };
+    const result = describePlugin(plugin, projectRoot);
+    descriptions?.set(plugin.dir, result);
+    return result;
+  });
 }
 
 /** Bundled plugins shipped in the package, flagged with whether they are installed here. */
@@ -344,7 +362,8 @@ export async function recompileAfterPluginMutation(projectRoot = process.cwd(),
     // read on demand at preflight, so a shared plugin change compiles no other repository
     // (ON-DEMAND-CONTEXT-01; one install used to rebuild all registered brains).
     await compileLayer(compileSurface, projectRoot, isGlobal);
-    if (isGlobal) {
+    // A shared change made from the dashboard's global brain has no repository to refresh.
+    if (isGlobal && projectRoot) {
       // The repository the command ran in refreshes its own catalog now, so its plugin library
       // never lags the change. That compile is cheap: entry files and vault indexes keep their
       // own triggers, so only the catalog and CLI index move.

package/src/core/project-id.mjs

@@ -7,6 +7,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
 function brainJsonPath(brainDir) {
   return path.join(brainDir, 'config', 'brain.json');
 }
@@ -35,21 +37,21 @@ export function readProjectId(brainDir) {
  * Return the project's id, creating a random UUID on first use.
  * @returns {{ project_id: string, created: boolean }}
  */
-export function ensureProjectId(brainDir) {
+export function ensureProjectId(brainDir, { fallbackId } = {}) {
   const file = brainJsonPath(brainDir);
   let cfg;
   try { cfg = JSON.parse(fs.readFileSync(file, 'utf8')); }
   catch (err) { if (err.code === 'ENOENT') cfg = {}; else throw new Error('Existing project identity is unreadable or malformed'); }
   if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) throw new Error('Existing project identity must be an object');
   if (cfg.project_id) return { project_id: cfg.project_id, created: false };
-  cfg.project_id = randomUUID();
+  cfg.project_id = fallbackId || randomUUID();
   writeJsonAtomic(file, cfg);
   return { project_id: cfg.project_id, created: true };
 }
 
 /**
- * Give every registered project an id and make the registry agree with each
- * project's brain.json (the brain.json id wins).
+ * Make the registry agree with each project's brain.json. If the disk identity
+ * is missing, preserve a unique valid UUID already published in the registry.
  * @returns {{ total: number, created: number, synced: number, missing_brain: number }}
  */
 export function repairProjectIds(globalBrainDir) {
@@ -57,13 +59,21 @@ export function repairProjectIds(globalBrainDir) {
   const list = readJson(registryPath, []);
   const out = { total: 0, created: 0, synced: 0, missing_brain: 0 };
   if (!Array.isArray(list)) return out;
+  const owners = new Map();
+  for (const row of list) {
+    const onDisk = typeof row?.brainDir === 'string' ? readProjectId(row.brainDir) : null;
+    for (const id of new Set([row?.project_id, onDisk])) {
+      if (typeof id === 'string' && UUID.test(id)) owners.set(id, (owners.get(id) || 0) + 1);
+    }
+  }
   for (const row of list) {
     out.total++;
     if (!row?.brainDir || !fs.existsSync(row.brainDir)) {
       out.missing_brain++;
       continue;
     }
-    const { project_id, created } = ensureProjectId(row.brainDir);
+    const fallbackId = owners.get(row.project_id) === 1 ? row.project_id : undefined;
+    const { project_id, created } = ensureProjectId(row.brainDir, { fallbackId });
     if (created) out.created++;
     if (row.project_id !== project_id) {
       row.project_id = project_id;

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

package/src/core/schema.mjs

@@ -1034,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/ssss-operation-service.mjs

@@ -46,6 +46,7 @@ export function patchVfsDocument(vfsPath, patches, options = {}) {
     type: 'patch',
     ...envelopeBase(vfsPath, options),
     patches,
+    ...(options.expectedBeforeHash === undefined ? {} : { expected_before_hash: options.expectedBeforeHash }),
   }, options);
 }
 

package/src/core/startup-health.mjs

@@ -10,6 +10,23 @@ import { CLI_COMMANDS } from './cli-commands.mjs';
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 export const cliEntry = path.join(packageRoot, 'bin/total-recall.mjs');
 
+/** Whether this package's dashboard bundle is as new as its frontend sources (the server rebuilds it). */
+async function defaultDashboardCheck() {
+  try {
+    const { checkDistFreshness, dashboardTargets } = await import('./dashboard-bundle.mjs');
+    if (!fs.existsSync(path.join(packageRoot, 'frontend', 'package.json'))) return { status: 'not-shipped' };
+    const result = await checkDistFreshness(dashboardTargets(packageRoot));
+    const status = result.ok ? 'current' : result.reason === 'missing-bundle' ? 'missing' : 'stale';
+    return {
+      status,
+      ...(result.bundle ? { built_at: new Date(result.bundle.mtimeMs).toISOString() } : {}),
+      ...(!result.ok && result.source ? { newer_source: path.relative(packageRoot, result.source.path) } : {}),
+    };
+  } catch (error) {
+    return { status: 'unknown', reason: error.message };
+  }
+}
+
 export function runBounded(binary, args, { cwd = process.cwd(), timeoutMs = 15000, maxBytes = 262144 } = {}) {
   return new Promise(resolve => {
     let child, output = '', stderr = '', size = 0, reason = null, settled = false, timer, escalation;
@@ -81,8 +98,8 @@ export function processIdentity(pidFile, hint, { alive = pid => { try { process.
 }
 
 /** The single installation-aware daemon observation for status and lifecycle. */
-export function observeDaemon(brainDir, { identity = processIdentity } = {}) {
-  const expected_entry = path.join(packageRoot, 'src', 'core', 'daemon-loop.mjs');
+export function observeDaemon(brainDir, { identity = processIdentity, expectedEntry = path.join(packageRoot, 'src', 'core', 'daemon-loop.mjs') } = {}) {
+  const expected_entry = expectedEntry;
   return { ...identity(path.join(brainDir, 'daemon.pid'), expected_entry), expected_entry, source: 'local-pid' };
 }
 
@@ -130,7 +147,8 @@ export async function fetchStartup(url, options = {}, fetchImpl = fetch) {
 }
 
 export async function startupHealth({ cwd = process.cwd(), brainDir, brainUrl = null, token = null, brainId = null, ensure = false,
-  appCheck = null, appStart = null, run = runBounded, fetchImpl = fetch, onDiskVersion = packageVersionOnDisk, listener = verifyListener, platform = process.platform, home = os.homedir(), identity = processIdentity } = {}) {
+  appCheck = null, appStart = null, run = runBounded, fetchImpl = fetch, onDiskVersion = packageVersionOnDisk, listener = verifyListener, platform = process.platform, home = os.homedir(), identity = processIdentity,
+  dashboardCheck = null, pluginChecks = null } = {}) {
   const actions = [];
   const serverFile = path.join(brainDir, 'server.pid');
   const report = { checked_at: new Date().toISOString(), server: { status: 'not-configured' }, brain: { status: 'unknown' }, daemon: { status: 'unknown' },
@@ -235,6 +253,13 @@ export async function startupHealth({ cwd = process.cwd(), brainDir, brainUrl =
   }
   const { inspectRequiredPlugins } = await import('./required-plugins.mjs');
   report.required_plugins = inspectRequiredPlugins(brainDir);
+  // Reported, not part of readiness: a stale dashboard or unfinished work still
+  // leaves the runtime usable, but neither may stay invisible.
+  report.dashboard = await (dashboardCheck ?? defaultDashboardCheck)();
+  report.plugin_checks = await (pluginChecks ?? (async () => {
+    const { runPluginStartupChecks } = await import('./plugin-startup-checks.mjs');
+    return runPluginStartupChecks({ cwd });
+  }))();
   report.shared_ready = report.required_plugins.status === 'ready' && report.server.status === 'ready' && report.brain.status === 'ready' && report.daemon.status === 'running' && report.ssss.status === 'available';
   report.ready_scope = appCheck ? 'shared-and-declared-current-repo-app' : 'shared-runtime-only';
   report.ready = report.shared_ready && (!appCheck || report.app.status === 'ready');

package/src/core/testing/plugin-fixture.mjs

@@ -1,13 +1,13 @@
 /**
- * Fixture manifests for specs that exercise plumbing rather than card design.
+ * Fixture manifests for specs that exercise plumbing rather than Home design.
  *
- * Every real plugin has a bespoke card face declared in `ui.elements[]`, and the
+ * Every real plugin has a bespoke native Home declared in `ui.elements[]`, and the
  * validator enforces it. Specs that install, copy, vendor, discover or compile a
  * plugin still need a manifest that satisfies that contract, or they fail on a
- * rule they are not testing. This module supplies the smallest honest face so
+ * rule they are not testing. This module supplies a minimal native Home so
  * those specs keep asserting what they mean to assert.
  *
- * The face here is deliberately generic and exists only in tests. Production
+ * The Home here is deliberately generic and exists only in tests. Production
  * plugin UI is always hand-authored per plugin (invariants-b6e8fcac).
  */
 import fs from 'node:fs';
@@ -16,45 +16,46 @@ import path from 'node:path';
 const nodeFs = fs;
 const nodePath = path;
 
-/** The smallest valid card face. Declared once, as every plugin declares one. */
-export const FIXTURE_CARD_FACE = Object.freeze({
+/** The smallest valid native Home. Declared once, as every plugin declares one. */
+export const FIXTURE_HOME = Object.freeze({
+  home: 'home',
   design_tokens: 'ui/DESIGN.md',
   elements: [
     {
-      id: 'card',
-      kind: 'card',
-      tag: 'tr-fixture-card',
-      module: 'ui/card.js',
-      description: 'Fixture card face',
+      id: 'home',
+      kind: 'panel',
+      tag: 'tr-fixture-home',
+      module: 'ui/home.js',
+      description: 'Fixture native Home',
     },
   ],
 });
 
-/** Source of the element module referenced by FIXTURE_CARD_FACE. */
-export const FIXTURE_CARD_SOURCE = 'export const tag = "tr-fixture-card";\n';
+/** Source of the element module referenced by FIXTURE_HOME. */
+export const FIXTURE_HOME_SOURCE = 'export const tag = "tr-fixture-home";\n';
 
 /**
- * Merge a bespoke face into a fixture manifest.
+ * Merge a native Home into a fixture manifest.
  *
- * Pass `ui: null` to omit the face deliberately, e.g. when asserting that a
+ * Pass `ui: null` to omit the Home deliberately, e.g. when asserting that a
  * plugin without one is rejected.
  */
-export function withFixtureFace(manifest = {}) {
+export function withFixtureHome(manifest = {}) {
   if (manifest.ui === null) {
     const { ui: _omitted, ...rest } = manifest;
     return rest;
   }
-  return { ...manifest, ui: manifest.ui ?? { ...FIXTURE_CARD_FACE } };
+  return { ...manifest, ui: manifest.ui ?? { ...FIXTURE_HOME } };
 }
 
 /**
- * Write `plugin.json` for a fixture plugin, declaring a face unless the manifest
+ * Write `plugin.json` for a fixture plugin, declaring a Home unless the manifest
  * explicitly opts out with `ui: null`.
  *
  * Returns the manifest that was written.
  */
 export function writeFixturePlugin(pluginDir, manifest, { fs = nodeFs, path = nodePath } = {}) {
-  const written = withFixtureFace(manifest);
+  const written = withFixtureHome(manifest);
   nodeFs.writeFileSync(
     nodePath.join(pluginDir, 'plugin.json'),
     JSON.stringify(written, null, 2),
@@ -62,8 +63,8 @@ export function writeFixturePlugin(pluginDir, manifest, { fs = nodeFs, path = no
   if (written.ui?.elements?.length) {
     const uiDir = nodePath.join(pluginDir, 'ui');
     nodeFs.mkdirSync(uiDir, { recursive: true });
-    nodeFs.writeFileSync(nodePath.join(uiDir, 'card.js'), FIXTURE_CARD_SOURCE);
-    nodeFs.writeFileSync(nodePath.join(uiDir, 'DESIGN.md'), '# Fixture card\n');
+    nodeFs.writeFileSync(nodePath.join(uiDir, 'home.js'), FIXTURE_HOME_SOURCE);
+    nodeFs.writeFileSync(nodePath.join(uiDir, 'DESIGN.md'), '# Fixture Home\n');
   }
   return written;
 }

package/src/core/throttled-fetch.mjs

@@ -135,31 +135,38 @@ export async function loadFirewallPolicy(brainDir) {
 
     applyPolicy();
 
-    // Watch the file directly if it exists.
-    if (!policyWatcher && fs.existsSync(policyPath)) {
-      policyWatcher = fs.watch(policyPath, (eventType) => {
-        if (eventType === 'change') applyPolicy();
-      });
-      // Unref so this watcher does not prevent one-shot CLI commands (e.g.
-      // `recall`) from exiting cleanly once their work is done.
-      policyWatcher.unref();
-    }
+    const watch = (target, onChange, clear) => {
+      try {
+        const watcher = fs.watch(target, onChange);
+        watcher.on('error', error => {
+          watcher.close();
+          clear(watcher);
+          logger.warn('throttled-fetch', `Network policy watcher unavailable: ${error.message}`);
+        });
+        watcher.unref();
+        return watcher;
+      } catch (error) {
+        logger.warn('throttled-fetch', `Network policy watcher unavailable: ${error.message}`);
+        return null;
+      }
+    };
+    const watchPolicy = () => {
+      if (policyWatcher || !fs.existsSync(policyPath)) return;
+      policyWatcher = watch(policyPath, event => {
+        if (event === 'change') applyPolicy();
+      }, watcher => { if (policyWatcher === watcher) policyWatcher = null; });
+    };
+    watchPolicy();
 
     // Also watch the parent directory so we pick up the policy file being
     // created after boot (e.g. first-run setups where the doc doesn't exist
     // yet). Attach the direct file watcher once it appears.
     if (!parentWatcher && fs.existsSync(systemDir)) {
-      parentWatcher = fs.watch(systemDir, (eventType, filename) => {
+      parentWatcher = watch(systemDir, (_event, filename) => {
         if (filename !== 'network-policy.md') return;
         applyPolicy();
-        if (!policyWatcher && fs.existsSync(policyPath)) {
-          policyWatcher = fs.watch(policyPath, (evt) => {
-            if (evt === 'change') applyPolicy();
-          });
-          policyWatcher.unref();
-        }
-      });
-      parentWatcher.unref();
+        watchPolicy();
+      }, watcher => { if (parentWatcher === watcher) parentWatcher = null; });
     }
   } catch (err) {
     logger.error('throttled-fetch', `Failed to load network policy: ${err.message}`);

package/src/core/ui-chunk-choice.mjs

@@ -0,0 +1,77 @@
+import { getPluginById } from './plugin-loader.mjs';
+import { pluginActivation } from './plugin-state.mjs';
+
+const decisionLimit = 20;
+
+async function requestChoice(state, questions, { projectRoot = process.cwd(), brainDir } = {}) {
+  const plugin = getPluginById('decision', projectRoot);
+  if (!plugin?.valid || !pluginActivation(plugin, { projectRoot }).enabled ||
+      !plugin.manifest.cli?.subcommands?.some(command => command.name === 'run')) return null;
+  const { runPluginCommand } = await import('./plugin-runner.mjs');
+  const run = await runPluginCommand(plugin, {
+    subcommand: 'run',
+    args: ['--state', JSON.stringify(state), '--questions', JSON.stringify(questions), '--json'],
+    timeoutMs: 15_000,
+    cwd: projectRoot ?? brainDir ?? process.cwd(),
+    projectRoot,
+  });
+  if ((!run.ok && run.exitCode !== 4) || run.truncated) return null;
+  return JSON.parse(run.stdout);
+}
+
+export async function chooseUiChunk(chunks, query, surface, decide = requestChoice) {
+  const result = await chooseBlocks(chunks, query, surface, ['selected_chunk'], decide);
+  const { keys, ...selection } = result;
+  return { ...selection, key: keys[0] ?? null };
+}
+
+export async function chooseUiComposition(chunks, query, decide, target) {
+  const choose = decide ?? ((state, questions) => requestChoice(state, questions, target));
+  return chooseBlocks(chunks, query, 'page', ['selected_chunk', 'supporting_chunk', 'reference_chunk'], choose, false);
+}
+
+const instructions = {
+  selected_chunk: 'Choose the primary block that best accomplishes the requested intent.',
+  supporting_chunk: 'Choose an additional block that helps accomplish the same task without repeating the primary block.',
+  reference_chunk: 'Choose an optional readout or reference block that gives useful context for the task.',
+};
+
+async function chooseBlocks(chunks, query, surface, slots, decide, skipSingle = true) {
+  const shortlist = chunks.slice(0, decisionLimit);
+  if (!shortlist.length) return { source: 'lexical', keys: [], reason: 'no-matches' };
+  const fallback = { source: 'lexical', keys: shortlist.slice(0, slots.length).map(chunk => chunk.key) };
+  if (skipSingle && shortlist.length === 1) return { ...fallback, reason: 'single-match' };
+
+  const criteria = Object.fromEntries(shortlist.map(chunk => {
+    const description = [chunk.title, chunk.description, ...chunk.intents, ...(chunk.operations || []), ...(chunk.data || [])].join(' ').slice(0, 600);
+    return [chunk.key, description];
+  }));
+  criteria.none = 'No eligible chunk fits this intent.';
+  const questions = Object.fromEntries(slots.slice(0, shortlist.length).map(slot => [slot, {
+    type: 'choice',
+    instructions: `${instructions[slot]} Choose none when nothing fits.`,
+    criteria,
+  }]));
+  let result;
+  try {
+    result = await decide({ intent: query, surface: surface ?? null }, questions);
+  } catch {
+    return { ...fallback, reason: 'decision-unavailable' };
+  }
+  if (result?.ok !== true) return { ...fallback, reason: 'decision-unavailable' };
+  const eligible = new Set(shortlist.map(chunk => chunk.key));
+  const primary = result.answers?.selected_chunk;
+  if (!confident(primary)) return { ...fallback, reason: 'decision-abstained' };
+  if (primary.choice === 'none') return { source: 'decision', keys: [], reason: 'no-fit', confidence: primary.confidence };
+  if (!eligible.has(primary.choice)) return { source: 'decision', keys: [], reason: 'invalid-choice' };
+  const keys = new Set([primary.choice]);
+  for (const slot of Object.keys(questions).slice(1)) {
+    const answer = result.answers?.[slot];
+    if (confident(answer) && eligible.has(answer.choice)) keys.add(answer.choice);
+  }
+  return { source: 'decision', keys: [...keys], confidence: primary.confidence };
+}
+
+function confident(answer) {
+  return answer?.act === true && Number.isFinite(answer.confidence) && answer.confidence >= 0.5 && answer.confidence <= 1;
+}

package/src/core/ui-chunk.registry.json

@@ -0,0 +1,23 @@
+{
+  "registry": "ui-chunk",
+  "extends": "ssss",
+  "version": "1.1.0",
+  "description": "Portable owner-authored HTML chunks for Total Recall workspace surfaces.",
+  "document_primitives": {
+    "chunk": {
+      "family": "capability",
+      "append_only": false,
+      "portability": "structural",
+      "filename_convention": "A kebab-case chunk ID under ui/chunks/ with the .md extension.",
+      "required_fields": ["type", "title", "description", "timestamp", "plugin", "id", "intents", "surfaces"],
+      "optional_fields": ["panel", "operations", "data"],
+      "immutable_fields": ["plugin", "id"],
+      "enums": { "surfaces": ["page", "left", "right", "bottom"] },
+      "patterns": {
+        "plugin": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+        "id": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+      },
+      "notes": "The body holds HTML. The host validates surface membership, file ownership and native panel bindings before publishing the catalog."
+    }
+  }
+}