total-recall-brain 3.44.0 → 3.46.0

package/src/cli/plugin/create.mjs

@@ -1,9 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-import { validatePluginManifest } from "../../core/plugin-loader.mjs";
+import { validatePluginManifest, isCronExpression } from "../../core/plugin-loader.mjs";
 import { installPlugin } from "../../core/plugin-store.mjs";
-import { parseCron } from "../../core/plugin-cron.mjs";
 
 function toTitleCase(kebab) {
   return kebab
@@ -111,13 +110,10 @@ customElements.define('${id}-panel', ${panelClass});
 }
 
 export async function createPlugin(args = []) {
-  const isGlobal = args.includes("--global") || args.includes("-g");
+  // 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");
@@ -212,7 +208,7 @@ export async function createPlugin(args = []) {
 
   if (!id) {
     console.error("❌ Error: Missing plugin id.");
-    console.error("   Usage: total-recall plugin create <id> [--from-skill <path>] [--capability] [--name <name>] [--description <desc>] [--category <cat>] [--global]\n");
+    console.error("   Usage: total-recall plugin create <id> [--from-skill <path>] [--capability] [--name <name>] [--description <desc>] [--category <cat>]\n");
     process.exit(1);
   }
 
@@ -226,7 +222,7 @@ export async function createPlugin(args = []) {
     if (!taskCommand || !/^[a-z][a-z0-9-]*$/.test(taskCommand) || !taskSchedule || !taskIntent) {
       throw new Error('--with-task requires --task-command <subcommand>, --task-schedule "<five-field cron>", and --task-intent <description>');
     }
-    parseCron(taskSchedule);
+    if (!isCronExpression(taskSchedule)) throw new Error(`--task-schedule must be a five-field cron expression, got "${taskSchedule}"`);
   } else if (taskCommand || taskSchedule || taskIntent) {
     throw new Error('--task-* options require --with-task');
   }
@@ -252,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 }));
@@ -302,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
@@ -359,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"],
@@ -446,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}`);
   }
@@ -493,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(
     "",
@@ -507,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 ──────────────────────────────────────────
@@ -534,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';
@@ -589,7 +560,7 @@ test('every file the manifest references exists', () => {
   // ── Install: a link to the repo, so the repo is what runs ───────────────
   let installed = false;
   if (!skipInstall) {
-    await installPlugin(pluginDir, { link: true, global: isGlobal, projectRoot: process.cwd() });
+    await installPlugin(pluginDir, { link: true, projectRoot: process.cwd() });
     installed = true;
   }
 
@@ -613,7 +584,7 @@ test('every file the manifest references exists', () => {
   if (withCli) {
     console.log(`   CLI Handler: \x1b[32m${path.join(pluginDir, "cli.mjs")}\x1b[0m`);
   }
-  console.log(`   Installed:  ${installed ? `linked into ${isGlobal ? 'the global' : 'this project\'s'} plugins` : 'no (--no-install)'}`);
+  console.log(`   Installed:  ${installed ? `linked into the shared plugin folder` : 'no (--no-install)'}`);
   console.log(`   GitHub:     ${githubUrl || (createGithub ? 'creation failed' : 'not created (re-run with --github, or: gh repo create tr-plugin-' + id + ' --private --source ' + pluginDir + ')')}`);
   console.log(`\nNext steps:`);
   console.log(`   Test:    \x1b[32mcd ${pluginDir} && npm test\x1b[0m`);

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,9 +27,13 @@ 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. --apply deletes only
-                            bundled matches. Add --archive-stale to preserve older differing copies.
+  copies [dir] [--apply]    Audit repository copies of shared defaults and shadow links. --apply
+                            deletes bundled matches, unlinks shadows (on/off records are kept)
+                            and removes install records of plugins installed nowhere.
+                            Add --archive-stale to preserve older differing copies, and
+                            --drop-repo-only to delete plugins that exist only in the repository.
   replacements [--prune] [--keep N] [--project] [--json]
                             Copies kept by install --replace (default: shared folder). Reports
                             the space; --prune keeps the newest N per plugin (default 1) and
@@ -36,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
@@ -49,7 +55,8 @@ Commands:
                               <path>              a local directory
                               --link, -l    Symlink a local directory instead of copying
                               --replace     Replace an install, retain previous source and restore on failure
-                              --global, -g  Install for every project on this machine
+                            Every plugin installs into the shared folder for all repositories;
+                            a repository switches it with 'plugin on|off <id>'.
   update [--check] [--json]  Reinstall every plugin whose git repo, mesh peer or source
                             directory moved ahead (--check only reports; also runs hourly
                             in 'update --automatic')
@@ -57,7 +64,7 @@ Commands:
   unshare <id>              Stop offering it
   publish <id>              Publish plugin to the Store and lock release (--no-lock)
   monetize <id>             Configure plugin pricing, period, and payout recipient
-  remove <id>               Uninstall (--global for the machine-wide copy)
+  remove <id>               Uninstall from the shared folder
   license <id> [cmd]        Check or activate plugin license (status, activate, checkout, verify)
   info <id>                 Manifest, provenance, hash and task history
   vendor <source> [dir]     Add a plugin to this project as a brick (default bricks/<id>); the
@@ -71,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
@@ -80,10 +87,10 @@ Commands:
 
 Examples:
   npx total-recall plugin available --use-case software-development
-  npx total-recall plugin install git-sentinel
-  npx total-recall plugin share git-sentinel
+  npx total-recall plugin install git
+  npx total-recall plugin share git
   npx total-recall plugin peers
-  npx total-recall plugin install peer:mac-mini/git-sentinel
+  npx total-recall plugin install peer:mac-mini/git
   npx total-recall plugin create reading-list --use-case research --with-cli
 `);
 }
@@ -112,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/plugin/install.mjs

@@ -2,18 +2,22 @@ import { installPlugin as install } from '../../core/plugin-distribution.mjs';
 import { syncPluginCommands } from '../command.mjs';
 
 export async function installPlugin(args = []) {
-  const isGlobal = args.includes('--global') || args.includes('-g');
+  // Every plugin installs into the shared folder; `--global` is accepted and changes nothing.
   const isLink = args.includes('--link') || args.includes('-l');
   const source = args.find(a => !a.startsWith('-'));
 
+  if (args.includes('--project')) {
+    console.error("❌ Plugins are installed only in the shared folder. In a repository, switch one with 'total-recall plugin on|off <id>'.");
+    process.exit(1);
+  }
   if (!source) {
     console.error('❌ Error: Missing plugin source.');
-    console.error('   Usage: total-recall plugin install <bundled-id | share-link | peer:<host>/<id> | git-url | path> [--link] [--global]\n');
+    console.error('   Usage: total-recall plugin install <bundled-id | share-link | peer:<host>/<id> | git-url | path> [--link]\n');
     process.exit(1);
   }
 
   try {
-    const result = await install(source, { projectRoot: process.cwd(), global: isGlobal, link: isLink, replace:args.includes('--replace') });
+    const result = await install(source, { projectRoot: process.cwd(), link: isLink, replace:args.includes('--replace') });
     const from = result.source.kind === 'peer' ? `peer ${result.source.peer_hostname}` : result.source.kind;
     console.log(`\n✅ Installed '${result.plugin.name}' (id: ${result.plugin.id}, v${result.plugin.version}) from ${from}`);
     console.log(`   Location: ${result.plugin.dir}`);
@@ -24,7 +28,7 @@ export async function installPlugin(args = []) {
     } else if (result.dependencies?.reason && !['no package.json', 'no dependencies declared'].includes(result.dependencies.reason)) {
       console.log(`   Dependencies: NOT installed (${result.dependencies.reason})`);
     }
-    const cmds = syncPluginCommands(result.plugin.dir, { global: isGlobal });
+    const cmds = syncPluginCommands(result.plugin.dir, { global: true });
     if (cmds.created.length) console.log(`   Commands: ${cmds.created.map((c) => `total-recall ${c}`).join(', ')}`);
     for (const c of cmds.skipped) console.log(`   Skipped command '${c.name}': ${c.reason}`);
     console.log('');
@@ -34,17 +38,8 @@ export async function installPlugin(args = []) {
       return;
     }
     const { autoCompileSurfaces } = await import('../../core/auto-compile.mjs');
-    // Compile the layer the plugin actually landed in. `scope` is not enough on
-    // its own: from a directory with no project brain, projectPluginsDir(cwd)
-    // resolves to the global plugins dir, so a plugin installed into the global
-    // brain still reports scope 'project'. Ask the resolver whether a project
-    // brain exists at all, and otherwise fall back to the global layer — the one
-    // that was really written. Assuming 'project' compiled nothing and printed
-    // "Auto-compile failed: No project brain found" after a successful install.
-    const { resolveBrainDir } = await import('../agent-dir.mjs');
-    let targetLayer = 'global';
-    try { resolveBrainDir('project'); targetLayer = 'project'; } catch { targetLayer = 'global'; }
-    if (!await autoCompileSurfaces({ layer: targetLayer, semantic: false, force: true })) process.exitCode = 1;
+    // The plugin landed in the shared folder, so the global layer is the one to compile.
+    if (!await autoCompileSurfaces({ layer: 'global', semantic: false, force: true })) process.exitCode = 1;
   } catch (err) {
     console.error(`❌ ${err.message}`);
     process.exit(1);

package/src/cli/plugin/remove.mjs

@@ -8,7 +8,7 @@ export async function removePlugin(args = []) {
 
   if (!id) {
     console.error('❌ Error: Missing plugin ID to remove.');
-    console.error('   Usage: total-recall plugin remove <id> [--global]\n');
+    console.error('   Usage: total-recall plugin remove <id>\n');
     process.exit(1);
   }
 

package/src/cli/plugin/search.mjs

@@ -22,7 +22,7 @@ function parseArgs(args) {
  * `includes` makes a short query match inside unrelated words: searching "git"
  * returned the signing plugin, whose description begins "Digital agreement…".
  * A hit inside a word is only accepted at a word start so that real substrings
- * still work ("sent" finds "git-sentinel") without matching "digital".
+ * still work ("qual" finds "code-quality") without matching "digital".
  */
 function matches(p, query, useCase) {
   if (useCase && !(p.use_cases || []).includes(useCase)) return false;
@@ -32,7 +32,7 @@ function matches(p, query, useCase) {
   const words = query.split(/\s+/).filter(Boolean);
   return words.every((word) => {
     const escaped = word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    // Anchor at a word start so "sent" matches "git-sentinel" but "git" does
+    // Anchor at a word start so "qual" matches "code-quality" but "git" does
     // not match "digital".
     const bounded = new RegExp(`(^|[^a-z0-9])${escaped}`, 'i');
     return haystacks.some((h) => bounded.test(h) || h.startsWith(word));

package/src/cli/preflight.mjs

@@ -1,16 +1,18 @@
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import { ensureDependencies } from '../core/ensure-dependencies.mjs';
 import { detectProjectBrain } from '../core/brain-locate.mjs';
 import { globalBrainDirFor, isBrainEnabled } from '../core/brain-registry.mjs';
 import { GATE_MODES, gateConfigPath, projectBrainDir, readGateLayers, resolveGateMode, writeGateMode } from '../core/gate-mode.mjs';
 import { installHarnessHooks, loadGateAdapters } from '../core/harness-hooks.mjs';
-import { ackDirectory, capsuleVerb, decide, isAckCommand, isCheckCommand, isRouteCommand, isSubagentPayload, nativeToolOf, sessionOf, SWEEP_CONSULT_MS, whenGateFails } from '../core/preflight-gate.mjs';
+import { ackDirectory, capsuleVerb, decide, gatePackageBroken, isAckCommand, isCheckCommand, isRouteCommand, isSubagentPayload, nativeToolOf, sessionOf, SWEEP_CONSULT_MS, whenGateFails } from '../core/preflight-gate.mjs';
 import { ACK_COMMAND, acknowledge, checkAgentReceipt, checkAnyReceipt, findRoot, forgetCapsuleDeliveries, lastArrivalMs, lastCapsuleDelivery, lastConsultMs, lastRoutedMs, lastRouteWarnedMs, lastSessionAck, markArrival, markDelegated, markRouted, markRouteWarned, markSessionAck, noteCaller, recordDecision, sessionHasStanding, sessionKey, readDecisions, takeCaller } from '../core/preflight-receipt.mjs';
 
 const USAGE = `Usage: total-recall preflight <command>
   ack --task "<task>" [--action read,edit,test] [--json]   Record a receipt after context ready:true and rules verify, and print the capsule.
                                                             Prints one line instead when this session received the same rules and skills within 2 hours
+                                                            Restores missing or stale locked dependencies for edit/test actions
   check [--json]                                            Exit 1 unless a fresh receipt covers this agent, wherever it acknowledged.
                                                             Run by hand, it reports this directory's receipt
   gate [--harness <id>]                                     Hook entry: read a call on stdin, answer allow or deny (exit 2 on deny)
@@ -81,12 +83,23 @@ async function ack(args) {
   const task = flag(args, '--task') || '';
   const actions = flag(args, '--action') || 'read,edit,test';
   const result = acknowledge({ root, task, actions, maxAgeMs: await configuredMaxAgeMs(), session: takeCaller(root, 'ack', { task }) });
+  const needsDependencies = actions.split(',').some(action => ['edit', 'test'].includes(action.trim()));
+  const dependencies = result.ok && needsDependencies ? await ensureDependencies(root, { reason: `preflight:${actions}` }) : null;
+  const ok = result.ok && dependencies?.ok !== false;
   if (args.includes('--json')) {
-    console.log(JSON.stringify({ ok: result.ok, problems: result.problems, receipt: result.file || null, capsule: result.capsule ?? null, unchanged: Boolean(result.unchanged) }));
-    if (!result.ok) process.exitCode = 1;
+    console.log(JSON.stringify({ ok, problems: [...result.problems, ...(dependencies?.ok === false ? [`dependencies: ${dependencies.error}`] : [])], receipt: result.file || null, capsule: result.capsule ?? null, unchanged: Boolean(result.unchanged), dependencies }));
+    if (!ok) process.exitCode = 1;
     return;
   }
   if (!result.ok) return printFailure(result.problems);
+  if (dependencies) {
+    const detail = dependencies.ok ? (dependencies.command?.join(' ') || dependencies.trigger) : dependencies.error;
+    console.log(`  dependencies: ${dependencies.status} — ${detail}`);
+    if (!dependencies.ok) {
+      console.error('✖ Dependency install failed. Repair dependencies before edit or test work. The instruction receipt is recorded.');
+      process.exitCode = 1;
+    }
+  }
   if (result.unchanged) {
     const age = result.unchanged.ageMs < 60000 ? 'less than a minute ago' : `${Math.round(result.unchanged.ageMs / 60000)} minutes ago`;
     console.log(`✔ tr-preflight recorded: rules and skills are unchanged since this session received the capsule ${age}, so there is nothing new to read. If your task is new, or you no longer have the capsule, run: total-recall context "<task>" --action ${actions}`);
@@ -398,6 +411,8 @@ function evaluate(call, options = {}) {
 }
 
 function judge(call, { harness, readablePaths, session = null, subagent = false, nativeTool = null } = {}) {
+  const broken = gatePackageBroken();
+  if (broken) return whenGateFails(call, new Error(broken));
   const root = findRoot(call.cwd || process.cwd());
   const limit = envMaxAgeMs();
   const declared = readGateDeclarations();
@@ -584,12 +599,10 @@ async function mode(args) {
 
 export default async function preflight(args = []) {
   const [first = '--help'] = args;
-  if (first === '--help' || first === '-h' || first === 'help') return console.log(USAGE);
+  if (first === '--help' || first === '-h' || first === 'help' || args.includes('--help') || args.includes('-h')) return console.log(USAGE);
   // Original `tr-preflight` forms.
   if (first === '--ack' || first === 'ack') return ack(args);
   if (first === '--check' || first === 'check') return check(args);
-  // Help never performs the subcommand: `install --help` once rewrote the harness settings (C-019).
-  if (args.includes('--help') || args.includes('-h')) return console.log(USAGE);
   if (first === 'gate') return gate(args.slice(1));
   if (first === 'remind') return remind(args);
   if (first === 'session-start') return sessionStart();

package/src/cli/proposals.mjs

@@ -208,7 +208,7 @@ export default async function proposals(args) {
         console.log(`  ${String(days).padStart(4)}d  [i${n.importance}]  ${n.slug}`);
       }
       if (stale.length > 40) console.log(`\n  … and ${stale.length - 40} more.`);
-      console.log('\n  The dream cycle queues these for research automatically.\n');
+      console.log('\n  This query is read-only. Request research explicitly for a node that needs verification.\n');
       return;
     }
 

package/src/cli/recall.mjs

@@ -1,5 +1,22 @@
 import { resolveAgentDir, resolveBrainDir, parseLayerFlag, getBothBrains } from './agent-dir.mjs';
 import path from 'node:path';
+import fs from 'node:fs';
+
+/** One brain search shared by recall and paired evaluation. Does not record access. */
+export async function searchRecallBrain(query, { semantic = false, forceFast = false, field = false, ...options } = {}) {
+  let rankResults = null;
+  if (field) {
+    const { loadField, rankWithField } = await import('../core/vector-field.mjs');
+    const compiled = loadField(options.derivedDir);
+    if (!compiled) throw new Error('Vector field missing or corrupt. Run total-recall recall --compile-field first.');
+    rankResults = results => rankWithField(results, { field: compiled, derivedDir: options.derivedDir });
+  }
+  const { fastSearch } = await import('../core/fast-recall.mjs');
+  const fastResults = fastSearch(query, { ...options, fullText: !forceFast, rankResults });
+  if (!semantic || fastResults.some(result => (result.base_score ?? result.score) === 1) || forceFast) return fastResults;
+  const { semanticSearch } = await import('../core/search.mjs');
+  return semanticSearch(query, { ...options, rankResults });
+}
 
 function printHelp() {
   console.log(`
@@ -20,8 +37,18 @@ function printHelp() {
     --fast                     Force frontmatter-only search without semantic fallback
     --local                    Search indexed body text without a provider (default)
     --semantic                 Opt into semantic enrichment
+    --field                    Re-rank candidates with the compiled field (opt-in, local)
+    --compile-field            Compile existing embeddings into the selected brain's field
+    --evaluate-field <file>     Compare local recall with/without field on fixed JSON queries
     --timings                  Print local stage timings on stderr
 
+  Field operations (support --project/--global, --top-k, --format):
+    total-recall recall --compile-field --project
+    total-recall recall --evaluate-field queries.json --project --format json
+    Query file: [{ "query": "search terms", "relevant": ["expected-slug"] }]
+    Overlap@k = shared slugs / k. Hit rate@k = queries with a relevant slug / queries.
+    Evaluation does not record access. It uses local recall and requires a compiled field.
+
   Examples:
     npx total-recall recall "Never run tsc directly"
     npx total-recall recall "Express server port" --top-k 3
@@ -55,6 +82,7 @@ export default async function recall(args) {
   let forceFast = false;
   let semantic = false;
   let timings = false;
+  let field = false;
 
   for (let i = 1; i < remainingArgs.length; i++) {
     const arg = remainingArgs[i];
@@ -111,8 +139,11 @@ export default async function recall(args) {
       semantic = false;
     } else if (arg === '--timings') {
       timings = true;
+    } else if (arg === '--field') {
+      field = true;
     }
   }
+  top_k = Math.max(1, Math.min(20, top_k));
 
   // Determine which brains to search
   const brains = getBothBrains();
@@ -152,6 +183,26 @@ export default async function recall(args) {
   }
 
   try {
+    if (query === '--compile-field' || query === '--evaluate-field') {
+      const reports = [];
+      const cases = query === '--evaluate-field'
+        ? JSON.parse(fs.readFileSync(remainingArgs[1], 'utf8')) : null;
+      for (const target of searchTargets) {
+        const options = { vaultDir: path.join(target.brainDir, 'memory-vault'),
+          derivedDir: path.join(target.brainDir, 'memory-derived'), top_k, includeSessions: false };
+        if (query === '--evaluate-field') {
+          const { evaluateField } = await import('../core/field-evaluation.mjs');
+          reports.push({ brain: target.label, ...await evaluateField(cases, {
+            topK: top_k, search: (q, enabled) => searchRecallBrain(q, { ...options, field: enabled }),
+          }) });
+        } else {
+          const { compileField } = await import('../core/vector-field.mjs');
+          reports.push({ brain: target.label, ...(await compileField(options)).meta });
+        }
+      }
+      console.log(JSON.stringify(reports, null, 2));
+      return;
+    }
     // Search all target brains and merge results
     let allResults = [];
     let isDegraded = false;
@@ -164,8 +215,7 @@ export default async function recall(args) {
 
       try {
         let results = [];
-        const { fastSearch } = await import('../core/fast-recall.mjs');
-        const fastResults = fastSearch(query, {
+        results = await searchRecallBrain(query, {
           derivedDir,
           vaultDir,
           top_k,
@@ -174,28 +224,12 @@ export default async function recall(args) {
           modality,
           importance,
           priority,
-          fullText: !forceFast,
+          forceFast, semantic, field,
+          includeSessions: includeSessions && target.label !== 'global',
         });
-        if (timings) console.error(JSON.stringify({ brain: target.label, ...fastResults.stats }));
-        if (['missing', 'corrupt', 'metadata-only'].includes(fastResults.stats.index) && !forceFast) {
-          console.error(`Local full-text index for ${target.label}: ${fastResults.stats.index}. Run total-recall compile to rebuild; available metadata results may be incomplete.`);
-        }
-
-        if (!semantic || fastResults.some(result => result.score === 1) || forceFast) {
-          results = fastResults;
-        } else {
-          const { semanticSearch } = await import('../core/search.mjs');
-          results = await semanticSearch(query, {
-            vaultDir,
-            derivedDir,
-            top_k,
-            includeSessions: includeSessions && target.label !== 'global', // sessions only in project/local
-            category,
-            tags,
-            modality,
-            importance,
-            priority
-          });
+        if (timings) console.error(JSON.stringify({ brain: target.label, ...results.stats }));
+        if (['missing', 'corrupt', 'metadata-only'].includes(results.stats?.index) && !forceFast) {
+          console.error(`Local full-text index for ${target.label}: ${results.stats.index}. Run total-recall compile to rebuild; available metadata results may be incomplete.`);
         }
         if (results.degradedTextSearch) {
           isDegraded = true;
@@ -226,6 +260,15 @@ export default async function recall(args) {
     allResults.sort((a, b) => (b.score || 0) - (a.score || 0));
     allResults = allResults.slice(0, top_k);
 
+    // DECAY-01: a recalled memory is a used memory; record it in the brain it came from.
+    try {
+      const { recordAccess } = await import('../core/access-ledger.mjs');
+      for (const target of searchTargets) {
+        const slugs = allResults.filter(r => r._layer === target.label).map(r => r.slug || r.id).filter(Boolean);
+        recordAccess(path.join(target.brainDir, 'memory-derived'), slugs);
+      }
+    } catch { /* access accounting never breaks recall */ }
+
     if (format === 'json') {
       for (const error of searchErrors) console.error(`Search failed for ${error.label}: ${error.message.split('\n')[0]}`);
       if (searchErrors.length && !allResults.length) process.exitCode = 1;