total-recall-brain 3.36.0 → 3.37.0

package/frontend/dist/index.html

@@ -17,7 +17,7 @@
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
     <title>Total Recall — Portable Memory</title>
-    <script type="module" crossorigin src="/assets/index-DZ4ypNEl.js"></script>
+    <script type="module" crossorigin src="/assets/index-CpvEw3iA.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-C7_Xpk27.css">
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.36.0",
+  "version": "3.37.0",
   "description": "Personal AI system — database-free, SSSS-powered intelligence engine deployable to any POSIX host.",
   "type": "module",
   "workspaces": [

package/src/cli/agent.mjs

@@ -23,6 +23,14 @@ Options:
   --detach                  Spawn process detached in background (default: true)
   --name <label>            Assign a human-readable name to the agent session
   --tail <lines>            Number of log lines to inspect (default: 50)
+  --cwd <dir>               Working directory for the agent (on the target node with --node)
+  --tools <list>            Built-in tools for the harness: default (all), none, or e.g. "Bash,Read,WebFetch"
+                            (alias --allow-tools; --no-tools = none). Spawns default to all tools.
+  --setting-sources <list>  Settings layers the harness loads (e.g. local, or user,project)
+
+Auth:
+  Claude Code reads CLAUDE_CODE_OAUTH_TOKEN (from \`claude setup-token\`) from the environment,
+  else from the Total Recall secret store, so SSH/launchd sessions without a login keychain work.
 
 Available Harnesses:
   agy, claude, codex, gemini
@@ -31,11 +39,53 @@ Examples:
   npx total-recall agent list
   npx total-recall agent spawn claude "Refactor src/cli/harness.mjs error handling"
   npx total-recall agent spawn agy "Crawl recent preprints on quantum shuttling" --name "Quantum Scout"
+  npx total-recall agent spawn claude "Run the lead search workflow" --node build-box --cwd '~/code/app'
   npx total-recall agent logs agent-claude-xyz --tail 100
   npx total-recall agent kill agent-claude-xyz
 `);
 }
 
+const SPAWN_VALUE_FLAGS = {
+  '--node': 'targetNode',
+  '-n': 'targetNode',
+  '--name': 'name',
+  '--cwd': 'cwd',
+  '--tools': 'tools',
+  '--allow-tools': 'tools',
+  '--setting-sources': 'settingSources',
+};
+
+/**
+ * Parse `agent spawn` arguments. Option values are consumed with their flag, so
+ * they never leak into the task text; `--tools ""` is a real (empty) value.
+ */
+export function parseSpawnArgs(rest) {
+  const out = { detach: true, isJson: false, name: null, targetNode: null, cwd: undefined, tools: undefined, settingSources: undefined };
+  const positional = [];
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    const eq = arg.startsWith('--') ? arg.indexOf('=') : -1;
+    const flag = eq > 0 ? arg.slice(0, eq) : arg;
+    if (SPAWN_VALUE_FLAGS[flag]) {
+      let value;
+      if (eq > 0) value = arg.slice(eq + 1);
+      else {
+        if (i + 1 >= rest.length) throw new Error(`${flag} requires a value`);
+        value = rest[++i];
+      }
+      out[SPAWN_VALUE_FLAGS[flag]] = value;
+    } else if (arg === '--json') out.isJson = true;
+    else if (arg === '--no-detach') out.detach = false;
+    else if (arg === '--detach') out.detach = true;
+    else if (arg === '--no-tools') out.tools = 'none';
+    else if (arg.startsWith('--')) throw new Error(`Unknown option for agent spawn: ${arg}`);
+    else positional.push(arg);
+  }
+  out.harness = positional[0];
+  out.task = positional.slice(1).join(' ').trim();
+  return out;
+}
+
 export async function run(argv) {
   let args = argv;
   if (Array.isArray(args) && args[0]?.endsWith('node')) {
@@ -79,34 +129,25 @@ export async function run(argv) {
   }
 
   if (command === 'spawn') {
-    let targetNode = null;
-    const filteredRest = [];
-    for (let i = 0; i < rest.length; i++) {
-      if (rest[i] === '--node' || rest[i] === '-n') {
-        targetNode = rest[i + 1];
-        i++;
-      } else {
-        filteredRest.push(rest[i]);
-      }
+    let parsed;
+    try {
+      parsed = parseSpawnArgs(rest);
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
     }
-
-    const harness = filteredRest[0];
-    const task = filteredRest.filter(r => !r.startsWith('--')).slice(1).join(' ').trim();
-    const detach = !filteredRest.includes('--no-detach');
-    const isJson = filteredRest.includes('--json');
-    const nameIdx = filteredRest.indexOf('--name');
-    const name = nameIdx !== -1 ? filteredRest[nameIdx + 1] : null;
+    const { harness, task, detach, isJson, name, targetNode, cwd, tools, settingSources } = parsed;
 
     if (!harness || !task) {
       console.error('Error: Please specify harness ID and task prompt.');
-      console.error('Usage: npx total-recall agent spawn <harness> "<task>" [--name "..."] [--node <node>]');
+      console.error('Usage: npx total-recall agent spawn <harness> "<task>" [--name "..."] [--node <node>] [--cwd <dir>] [--tools <list|none|default>]');
       process.exit(1);
     }
 
     const nodeStr = targetNode ? ` on mesh node \x1b[1;33m${targetNode}\x1b[0m` : '';
     if (!isJson) console.log(`\n🚀 Spawning agent on harness: \x1b[1;36m${harness}\x1b[0m${nodeStr}...`);
     try {
-      const record = await spawnAgent(harness, task, { detach, name, node: targetNode });
+      const record = await spawnAgent(harness, task, { detach, name, node: targetNode, cwd, tools, settingSources });
       if (isJson) {
         console.log(JSON.stringify(record, null, 2));
         return;

package/src/cli/plugin/create.mjs

@@ -13,11 +13,104 @@ function toTitleCase(kebab) {
     .join(" ");
 }
 
+/** CLI token subcommands every API-key plugin starts with. */
+function tokenCliBlock(apiKeys) {
+  return `import { spawnSync } from "node:child_process";
+
+// The service API key lives in the Total Recall secrets store, never argv or logs.
+const TOKEN_KEY = ${JSON.stringify(apiKeys[0])};
+const TR = process.env.TOTAL_RECALL_BIN || "total-recall";
+
+function tokenValue() {
+  if (process.env[TOKEN_KEY]) return process.env[TOKEN_KEY].trim();
+  const run = spawnSync(TR, ["secret", "get", TOKEN_KEY], { encoding: "utf8" });
+  if (run.status !== 0) return "";
+  const lines = String(run.stdout || "").split("\\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("{"));
+  return lines.length ? lines[lines.length - 1] : "";
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8").trim();
+}
+
+// TODO(plugin author): call a cheap authenticated endpoint here and return
+// { valid: true } or { valid: false, message }. Never save a key that fails it.
+async function verifyToken(_value) {
+  return { valid: true };
+}
+
+async function tokenCommand(args) {
+  const [action = "status"] = args;
+  const json = args.includes("--json");
+  if (action === "status") {
+    const status = { present: Boolean(tokenValue()), secretKey: TOKEN_KEY };
+    console.log(json ? JSON.stringify(status) : \`API key: \${status.present ? "present" : "missing"} (\${TOKEN_KEY})\`);
+    if (!status.present) process.exitCode = 1;
+    return;
+  }
+  if (action === "set" && args.includes("--stdin")) {
+    const value = await readStdin();
+    if (!value) { console.error("No key received on stdin."); process.exitCode = 2; return; }
+    const check = await verifyToken(value);
+    if (!check.valid) { console.error(\`Key rejected, not saved: \${check.message || "verification failed"}\`); process.exitCode = 1; return; }
+    const saved = spawnSync(TR, ["secret", "set", TOKEN_KEY, "--stdin"], { input: value, encoding: "utf8" });
+    if (saved.status !== 0) { console.error("Could not save the key to the secrets store."); process.exitCode = 1; return; }
+    console.log(json ? JSON.stringify({ saved: true, valid: true }) : "API key verified and saved.");
+    return;
+  }
+  console.error("usage: token <status|set --stdin>");
+  process.exitCode = 2;
+}
+
+`;
+}
+
+/** UI panel with the paste-your-key form every API-key plugin starts with. */
+function tokenPanelSource(id, panelClass, pluginName, apiKeys) {
+  return `// Paste-your-key panel. Emits \`save-token\`; the host pipes it to
+// \`total-recall ${id} token set --stdin\` (stored in secrets, never shown again).
+class ${panelClass} extends HTMLElement {
+  set view(value) { this._view = value; this.render(); }
+  get view() { return this._view; }
+  connectedCallback() { this.render(); }
+  render() {
+    const root = this.shadowRoot || this.attachShadow({ mode: 'open' });
+    root.replaceChildren();
+    const present = Boolean(this._view && this._view.present);
+    const style = document.createElement('style');
+    style.textContent = ':host { display:block; color:var(--color-text); background:var(--color-surface); border:1px solid var(--color-border); border-radius:var(--radius-md); padding:var(--spacing-md); } .row { display:flex; gap:8px; margin-top:8px; } input { flex:1; padding:6px 8px; }';
+    const title = document.createElement('h3');
+    title.textContent = ${JSON.stringify(pluginName + ' API key')};
+    const state = document.createElement('p');
+    state.textContent = present ? 'A key is saved. Paste a new one to replace it.' : 'No key yet. Paste it to start using this plugin.';
+    const form = document.createElement('form');
+    form.className = 'row';
+    const input = document.createElement('input');
+    input.type = 'password'; input.autocomplete = 'off'; input.required = true;
+    input.placeholder = ${JSON.stringify(apiKeys[0])};
+    input.setAttribute('aria-label', ${JSON.stringify(pluginName + ' API key')});
+    const button = document.createElement('button');
+    button.type = 'submit'; button.textContent = 'Save and test';
+    form.append(input, button);
+    form.addEventListener('submit', (event) => {
+      event.preventDefault();
+      this.dispatchEvent(new CustomEvent('save-token', { detail: { key: ${JSON.stringify(apiKeys[0])}, token: input.value.trim() }, bubbles: true, composed: true }));
+      input.value = '';
+    });
+    root.append(style, title, state, form);
+  }
+}
+customElements.define('${id}-panel', ${panelClass});
+`;
+}
+
 export async function createPlugin(args = []) {
   const isGlobal = args.includes("--global") || args.includes("-g");
-  const withCli = args.includes("--with-cli");
+  let withCli = args.includes("--with-cli");
   const withGenerator = args.includes("--with-generator");
-  const withUi = args.includes("--with-ui");
+  let withUi = args.includes("--with-ui");
   const withTask = args.includes("--with-task");
   const createGithub = args.includes("--github");
   const publicRepo = args.includes("--public");
@@ -32,6 +125,7 @@ export async function createPlugin(args = []) {
   let taskSchedule = null;
   let taskIntent = null;
   const useCases = [];
+  const apiKeys = [];
 
   const cleanArgs = [];
   for (let i = 0; i < args.length; i++) {
@@ -39,6 +133,7 @@ export async function createPlugin(args = []) {
     if (["--global", "-g", "--with-cli", "--with-generator", "--with-ui", "--with-task", "--with-skill", "--capability", "--github", "--public", "--no-install"].includes(arg)) {
       continue;
     }
+    if (arg === "--api-key" && args[i + 1]) { apiKeys.push(args[++i]); continue; }
     if (arg === "--repo-dir" && args[i + 1]) { repoDirArg = args[++i]; continue; }
     if (arg === "--name" && args[i + 1]) {
       name = args[i + 1];
@@ -152,6 +247,14 @@ export async function createPlugin(args = []) {
   };
   if (useCases.length > 0) manifest.use_cases = useCases;
 
+  // House rule: a plugin for a service that needs an API key ships a UI to paste
+  // that key and a CLI to save it, so it works the moment the key is pasted.
+  if (apiKeys.length) {
+    withCli = true;
+    withUi = true;
+    manifest.secrets = apiKeys.map((key) => ({ key, description: `${pluginName} service API key (paste it in the plugin UI)`, required: true }));
+  }
+
   if (category) {
     manifest.ssss_schemas = {
       categories: [
@@ -183,7 +286,7 @@ export async function createPlugin(args = []) {
  */
 // Scaffold: report honestly what exists. Add each real subcommand to
 // IMPLEMENTED and to plugin.json "cli.subcommands" as it is built.
-const IMPLEMENTED = {};
+${apiKeys.length ? tokenCliBlock(apiKeys) : ''}const IMPLEMENTED = {};${apiKeys.length ? '\nIMPLEMENTED.token = tokenCommand;' : ''}
 
 export async function run(argv = []) {
   const args = Array.isArray(argv) ? argv.slice(3) : [];
@@ -221,7 +324,11 @@ export default run;
     const panelClass = `${id.split('-').map((part) => part[0].toUpperCase() + part.slice(1)).join('')}Panel`;
     fs.mkdirSync(path.join(pluginDir, 'ui'), { recursive: true });
     fs.writeFileSync(path.join(pluginDir, 'ui', 'DESIGN.md'), '---\ncolors:\n  text: "#20242a"\n  surface: "#ffffff"\n  border: "#dce2e8"\nspacing:\n  md: 12px\nrounded:\n  md: 8px\n---\n\n# Design tokens\n\nReplace these defaults with the host design tokens.\n');
-    fs.writeFileSync(path.join(pluginDir, 'ui', 'panel.js'), `class ${panelClass} extends HTMLElement {\n  connectedCallback() {\n    const root = this.shadowRoot || this.attachShadow({ mode: 'open' });\n    root.replaceChildren();\n    const style = document.createElement('style');\n    style.textContent = ':host { display:block; color:var(--color-text); background:var(--color-surface); border:1px solid var(--color-border); border-radius:var(--radius-md); padding:var(--spacing-md); }';\n    const text = document.createElement('p');\n    text.textContent = ${JSON.stringify(`${pluginName} panel scaffold. Add the actual capability before sharing.`)};\n    root.append(style, text);\n  }\n}\ncustomElements.define('${id}-panel', ${panelClass});\n`);
+    if (apiKeys.length) {
+      manifest.ui.elements[0].events = ['save-token'];
+      manifest.ui.elements[0].props = { view: { type: 'object', description: `Printed by \`total-recall ${id} token status --json\`: { present, secretKey }` } };
+    }
+    fs.writeFileSync(path.join(pluginDir, 'ui', 'panel.js'), apiKeys.length ? tokenPanelSource(id, panelClass, pluginName, apiKeys) : `class ${panelClass} extends HTMLElement {\n  connectedCallback() {\n    const root = this.shadowRoot || this.attachShadow({ mode: 'open' });\n    root.replaceChildren();\n    const style = document.createElement('style');\n    style.textContent = ':host { display:block; color:var(--color-text); background:var(--color-surface); border:1px solid var(--color-border); border-radius:var(--radius-md); padding:var(--spacing-md); }';\n    const text = document.createElement('p');\n    text.textContent = ${JSON.stringify(`${pluginName} panel scaffold. Add the actual capability before sharing.`)};\n    root.append(style, text);\n  }\n}\ncustomElements.define('${id}-panel', ${panelClass});\n`);
   }
 
   if (isCapability) {
@@ -348,6 +455,7 @@ export default generateContext;
   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 (withUi) lines.push('- **UI**: `ui/panel.js` custom element with DESIGN.md tokens');
+  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("");
 
   fs.writeFileSync(path.join(pluginDir, "README.md"), lines.join("\n"), "utf8");

package/src/cli/secret.mjs

@@ -81,10 +81,34 @@ import { agentDir as configuredAgentDir, getActiveBrains } from '../core/config.
 // pasted/piped value normally carries), not all whitespace, so a value that
 // legitimately starts or ends with a space round-trips intact.
 function readStdinValue() {
+  // A terminal never sends EOF on Enter, so readFileSync(0) would wait for a
+  // Ctrl-D on an empty line. Read one line (Enter ends it) with echo off.
+  if (process.stdin.isTTY) return readTtyLine();
   const raw = fs.readFileSync(0, 'utf8');
   return raw.endsWith('\n') ? raw.slice(0, -1) : raw;
 }
 
+function readTtyLine() {
+  const stty = (arg) => { try { execFileSync('stty', [arg], { stdio: ['inherit', 'ignore', 'ignore'] }); } catch { /* not a tty */ } };
+  process.stderr.write('Paste the value and press Enter: ');
+  stty('-echo');
+  let line = '';
+  try {
+    const chunk = Buffer.alloc(4096);
+    for (;;) {
+      let n;
+      try { n = fs.readSync(0, chunk, 0, chunk.length, null); } catch (err) { if (err.code === 'EAGAIN') continue; throw err; }
+      if (n === 0) break;
+      line += chunk.toString('utf8', 0, n);
+      if (/[\r\n]/.test(line)) break;
+    }
+  } finally {
+    stty('echo');
+    process.stderr.write('\n');
+  }
+  return line.split(/[\r\n]/)[0];
+}
+
 /**
  * Read the OS clipboard. Keeps a pasted credential inside this process rather
  * than routing it through argv, shell history, or an agent transcript.
@@ -133,13 +157,16 @@ function readSecretValue(label) {
     input.resume();
     input.setEncoding('utf8');
     let buf = '';
-    const onData = (ch) => {
+    // A paste arrives as one chunk (often with the Enter in it): walk it character by character.
+    const onData = (chunk) => { for (const ch of chunk) { if (onChar(ch)) return; } };
+    const onChar = (ch) => {
       if (ch === '\n' || ch === '\r' || ch === '\u0004') {
         input.setRawMode(false);
         input.pause();
         input.removeListener('data', onData);
         process.stdout.write('\n');
         resolve(buf.trim());
+        return true;
       } else if (ch === '\u0003') {
         input.setRawMode(false);
         process.stdout.write('\n');

package/src/core/agent-manager.mjs

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { spawn } from 'node:child_process';
-import { HARNESS_SPECS, detectHarnesses } from './meta-harness.mjs';
+import { HARNESS_SPECS, buildHarnessArgs, normalizeToolSelection, resolveHarnessEnv, shellQuote } from './meta-harness.mjs';
 import { findBinaryInPath } from './runtime.mjs';
 import { logger } from './logger.mjs';
 
@@ -81,14 +81,45 @@ export function listAgents() {
   return updated;
 }
 
+/** Tool selection as recorded in the agent registry. */
+function describeTools(tools) {
+  const selection = normalizeToolSelection(tools);
+  return selection === null ? 'default' : selection || 'none';
+}
+
+/**
+ * The `total-recall agent spawn` command line that recreates a spawn on another
+ * node. Every value is shell-quoted: the prompt, name and paths are caller data.
+ */
+export function buildRemoteSpawnCommand(harnessId, taskPrompt, options = {}) {
+  const parts = ['total-recall', 'agent', 'spawn', harnessId, taskPrompt];
+  if (options.name) parts.push('--name', options.name);
+  if (options.cwd) parts.push('--cwd', options.cwd);
+  if (options.tools !== undefined && options.tools !== null) {
+    parts.push('--tools', Array.isArray(options.tools) ? options.tools.join(',') : String(options.tools));
+  }
+  if (options.settingSources) parts.push('--setting-sources', options.settingSources);
+  if (options.detach === false) parts.push('--no-detach');
+  parts.push('--json');
+  return parts.map(shellQuote).join(' ');
+}
+
 /**
  * Spawn an agent harness headlessly or in background detach mode.
+ *
+ * A spawn runs a workflow, so the harness keeps its full built-in tool set and
+ * normal settings unless the caller narrows them:
+ *   options.tools           'none' | 'default' | 'Bash,Read' | ['Bash', 'Read']
+ *   options.settingSources  e.g. 'local' or 'user,project'
+ *   options.cwd             working directory (on the target node for --node)
  */
 export async function spawnAgent(harnessId, taskPrompt, options = {}) {
   const spec = HARNESS_SPECS[harnessId];
   if (!spec) {
     throw new Error(`Unknown harness ID "${harnessId}". Available: ${Object.keys(HARNESS_SPECS).join(', ')}`);
   }
+  // Validate the tool/settings selection before touching any node.
+  const harnessArgs = buildHarnessArgs(spec, { tools: options.tools, settingSources: options.settingSources });
 
   // Remote mesh execution branch
   if (options.node) {
@@ -102,9 +133,10 @@ export async function spawnAgent(harnessId, taskPrompt, options = {}) {
 
     if (!isSelf) {
       const id = `agent-${harnessId}-${Date.now().toString(36)}`;
-      const remoteCmd = `total-recall agent spawn ${harnessId} ${JSON.stringify(taskPrompt)} ${options.name ? `--name ${JSON.stringify(options.name)}` : ''} --json`;
+      const remoteCmd = buildRemoteSpawnCommand(harnessId, taskPrompt, options);
       const execResult = await execMeshCommand(options.node, remoteCmd, {
         vaultRoot: options.vaultRoot,
+        timeoutMs: options.timeoutMs,
       });
 
       let remoteRecord = null;
@@ -118,7 +150,8 @@ export async function spawnAgent(harnessId, taskPrompt, options = {}) {
         id: remoteRecord?.id || id,
         node: options.node,
         remote: true,
-        status: execResult.success ? 'running' : 'failed',
+        status: execResult.success ? (remoteRecord?.status || 'running') : 'failed',
+        ...(execResult.success ? {} : { error: (execResult.stderr || execResult.stdout || '').slice(-2000) }),
         startedAt: remoteRecord?.startedAt || new Date().toISOString(),
         task: taskPrompt,
         harness: harnessId,
@@ -136,20 +169,27 @@ export async function spawnAgent(harnessId, taskPrompt, options = {}) {
     throw new Error(`Binary "${spec.binary}" for harness "${spec.name}" not found on PATH.`);
   }
 
+  // A remote caller sends `~/…` unexpanded; it means this node's home.
+  const requestedCwd = options.cwd && /^~(?=$|\/)/.test(options.cwd) ? path.join(os.homedir(), options.cwd.slice(1)) : options.cwd;
+  const cwd = requestedCwd ? path.resolve(requestedCwd) : process.cwd();
+  if (!fs.existsSync(cwd) || !fs.statSync(cwd).isDirectory()) {
+    throw new Error(`Working directory does not exist: ${cwd}`);
+  }
+  const env = await resolveHarnessEnv(spec, process.env, options);
+
   const id = `agent-${harnessId}-${Date.now().toString(36)}`;
   const logDir = resolveLogDir();
   const logFile = path.join(logDir, `${id}.log`);
   const logFd = fs.openSync(logFile, 'a');
 
-  const args = [...spec.defaultFlags, taskPrompt];
-  const cwd = options.cwd || process.cwd();
+  const args = [...harnessArgs, taskPrompt];
 
   const child = spawn(binPath, args, {
     cwd,
     detached: options.detach !== false,
     stdio: options.detach !== false ? ['ignore', logFd, logFd] : 'pipe',
     env: {
-      ...process.env,
+      ...env,
       TR_AGENT_ID: id,
       TR_HARNESS: harnessId
     }
@@ -163,6 +203,7 @@ export async function spawnAgent(harnessId, taskPrompt, options = {}) {
     pid: child.pid,
     task: taskPrompt,
     cwd,
+    tools: describeTools(options.tools),
     logFile,
     startedAt: new Date().toISOString(),
     status: 'running',

package/src/core/cache-prune.mjs

@@ -154,6 +154,43 @@ export const DEFAULT_POLICIES = [
   },
 ];
 
+/**
+ * Logs written next to the brain rather than inside it. The installed
+ * LaunchAgents and `auto-pull.sh` send daemon/server/auto-pull output to
+ * `<agent home>/logs` (normally `~/.agent/logs`), which the brain policies above
+ * never saw: one node's `daemon.log` there reached 9 GB with the disk at 95%.
+ * Same rule as the brain log: truncate in place, never unlink.
+ *
+ * @type {Policy[]}
+ */
+export const AGENT_HOME_POLICIES = [
+  {
+    id: 'agent-logs',
+    dir: 'logs',
+    match: /\.log$/,
+    mode: 'size',
+    limit: 25 * 1024 * 1024,
+    keepBytes: 5 * 1024 * 1024,
+  },
+  {
+    id: 'agent-system-logs',
+    dir: 'logs',
+    match: /^system-\d{4}-\d{2}-\d{2}\.jsonl$/,
+    mode: 'age',
+    limit: 14,
+  },
+];
+
+/**
+ * The agent home that holds a conventionally placed brain
+ * (`<agent home>/skills/total-recall`), or null for any other layout.
+ */
+export function agentHomeFor(brainDir) {
+  const abs = path.resolve(brainDir);
+  if (path.basename(abs) !== 'total-recall' || path.basename(path.dirname(abs)) !== 'skills') return null;
+  return path.dirname(path.dirname(abs));
+}
+
 /** Is this path inside a protected directory? */
 export function isProtected(brainDir, target) {
   const root = path.resolve(brainDir);
@@ -219,10 +256,31 @@ function truncateKeepingTail(file, keepBytes) {
 /**
  * Apply every policy.
  *
- * @param {{brainDir: string, policies?: Policy[], dryRun?: boolean, now?: number}} opts
+ * `agentDir` (derived from a conventionally placed brain) also gets the
+ * AGENT_HOME_POLICIES; pass `agentDir: null` to skip it.
+ *
+ * @param {{brainDir: string, policies?: Policy[], agentDir?: string|null, agentPolicies?: Policy[], dryRun?: boolean, now?: number}} opts
  * @returns {{freed_bytes: number, removed: number, dry_run: boolean, results: object[]}}
  */
-export function pruneCaches({ brainDir, policies = DEFAULT_POLICIES, dryRun = false, now = Date.now() } = {}) {
+export function pruneCaches({
+  brainDir,
+  policies = DEFAULT_POLICIES,
+  agentDir = agentHomeFor(brainDir),
+  agentPolicies = AGENT_HOME_POLICIES,
+  dryRun = false,
+  now = Date.now(),
+} = {}) {
+  const report = runPolicies(brainDir, policies, { dryRun, now });
+  if (agentDir && path.resolve(agentDir) !== path.resolve(brainDir) && agentPolicies?.length) {
+    const extra = runPolicies(agentDir, agentPolicies, { dryRun, now });
+    report.freed_bytes += extra.freed_bytes;
+    report.removed += extra.removed;
+    report.results.push(...extra.results.map((r) => ({ ...r, root: 'agent-home' })));
+  }
+  return report;
+}
+
+function runPolicies(brainDir, policies, { dryRun, now }) {
   const results = [];
   let freed = 0;
   let removed = 0;