total-recall-brain 3.44.0 → 3.46.0

package/scaffold/.agent/skills/total-recall/plugins/automations/adapters.mjs

@@ -0,0 +1,247 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { pathToFileURL } from 'node:url';
+import { collectSources } from './capability/index.mjs';
+
+const exec = promisify(execFile);
+export const SOURCES = Object.freeze(['plugin-tasks', 'task-queue', 'research-queue', 'daemon', 'workflows', 'composed-commands', 'operating-system', 'agent-platforms']);
+export const coreModule = (root, name) => import(pathToFileURL(path.join(root, 'src/core', `${name}.mjs`)).href);
+const digest = text => crypto.createHash('sha256').update(text).digest('hex').slice(0, 20);
+export const recordId = (node, source, key) => `${source}:${digest(`${node}\0${key}`)}`;
+const text = (value, max = 240) => typeof value === 'string' ? value.slice(0, max) : '';
+const credentialLine = /\b(?:authorization|bearer|password|token|credential|secret|api[-_ ]?key)\b|(?:_KEY|_TOKEN|_SECRET|_PASSWORD)\b|\b(?:sk[-_]|gh[pousr]_|github_pat_|eyJ)[a-z0-9_-]{12,}/i;
+
+function failureReceipt(event) {
+  const output = text(event.output_tail, 2000).split('\n')
+    .map(line => credentialLine.test(line) ? '[credential diagnostic omitted]' : line)
+    .join('\n');
+  return {
+    timed_out: Boolean(event.timed_out),
+    duration_ms: Number.isFinite(event.duration_ms) ? event.duration_ms : null,
+    output_tail: output || null,
+  };
+}
+const canCancelPending = async (tasks, queueDir) =>
+  tasks.TASK_CANCELLATION_SUPPORTS_EXPECTED_STATUS === true
+  && typeof tasks.supportsPendingTaskCancellation === 'function'
+  && await tasks.supportsPendingTaskCancellation(queueDir) === true;
+export function automation(ctx, source, key, data) {
+  return { id: recordId(ctx.node_id, source, key), node_id: ctx.node_id, source,
+    name: key, origin: source, trigger: { kind: 'unknown', summary: 'Not reported' },
+    enabled: null, state: 'unknown', runner_available: null, last_run: null, actions: [], ...data };
+}
+export function scheduledTasks(plugins = [], ctx = { node_id: 'local' }) {
+  return plugins.flatMap(plugin => (Array.isArray(plugin.tasks) ? plugin.tasks : []).map(task => {
+    const selected_node = typeof plugin.task_nodes?.[task.command] === 'string' ? plugin.task_nodes[task.command].trim() || null : null;
+    const placement_state = task.placement !== 'selected-node' ? 'per-node'
+      : !Object.hasOwn(plugin, 'task_nodes') ? 'unknown' : selected_node ? 'selected' : 'unplaced';
+    return automation(ctx, 'plugin-tasks', `${plugin.id}:${task.command}`, {
+      name: text(task.intent || `${plugin.name || plugin.id} · ${task.command}`), origin: `plugin:${plugin.id}`,
+      plugin_id: plugin.id, plugin_name: plugin.name, command: task.command, intent: text(task.intent), schedule: task.schedule,
+      trigger: { kind: 'cron', summary: text(task.schedule) }, placement: task.placement || 'per-node',
+      selected_node, placement_state,
+      enabled: plugin.activation?.enabled ?? null, state: plugin.valid === false ? 'invalid' : plugin.activation?.enabled === false ? 'disabled' : placement_state === 'unplaced' ? 'unplaced' : 'declared',
+      runner_available: placement_state === 'unplaced' ? false : null,
+      valid: plugin.valid, last_handled_slot: task.last_run || null,
+      last_handled_outcome: task.last_run ? { slot: task.last_run, state: 'unknown' } : null,
+    });
+  }));
+}
+
+export async function boundedCommand(file, args, options = {}) {
+  try { const result = await exec(file, args, { timeout: 4000, maxBuffer: 2 * 1024 * 1024, encoding: 'utf8', windowsHide: true, ...options }); return result.stdout; }
+  catch (error) { const failure = new Error(error.code === 'ENOENT' ? `${file} is unavailable` : `${file} inventory failed (${error.killed ? 'timeout' : error.code || 'error'})`); failure.code = error.code; throw failure; }
+}
+
+/** Read only scheduler facts; never return commands, environments or secret-bearing arguments. */
+export async function operatingSystem(ctx) {
+  const run = ctx.runCommand || boundedCommand;
+  const records = [], warnings = [];
+  if (ctx.platform === 'darwin') {
+    const dirs = [path.join(ctx.home, 'Library/LaunchAgents'), '/Library/LaunchAgents', '/Library/LaunchDaemons', '/System/Library/LaunchAgents', '/System/Library/LaunchDaemons'];
+    let loaded = new Map();
+    try { loaded = new Map((await run('/bin/launchctl', ['list'])).split('\n').slice(1).map(line => line.trim().split(/\s+/)).filter(parts => parts.length >= 3).map(([pid, exit, label]) => [label, { pid, exit }])); }
+    catch (error) { warnings.push(error.message); }
+    for (const dir of dirs) {
+      let entries;
+      try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (error) { if (error.code !== 'ENOENT') warnings.push(`Cannot inspect ${dir}`); continue; }
+      const jobs = entries.filter(item => item.isFile() && item.name.endsWith('.plist'));
+      let cursor = 0;
+      await Promise.all(Array.from({ length: Math.min(4, jobs.length) }, async () => { while (cursor < jobs.length) {
+        const entry = jobs[cursor++];
+        const file = path.join(dir, entry.name);
+        try {
+          if (fs.statSync(file).size > 1024 * 1024) throw new Error('Job definition exceeds size limit');
+          const job = JSON.parse(await run('/usr/bin/plutil', ['-convert', 'json', '-o', '-', file]));
+          const label = text(job.Label || entry.name), runtime = loaded.get(label);
+          const kinds = [job.StartCalendarInterval && 'calendar', job.StartInterval && 'interval', job.WatchPaths && 'file-change', job.QueueDirectories && 'directory', job.KeepAlive && 'keep-alive', job.RunAtLoad && 'boot'].filter(Boolean);
+          // Socket/on-demand jobs are automations too; absence of a timer is not absence of a job.
+          records.push(automation(ctx, 'operating-system', file, { name: label, origin: `launchd:${label}`,
+            trigger: { kind: kinds[0] || 'on-demand', summary: job.StartInterval ? `Every ${Number(job.StartInterval)} seconds${kinds.length > 1 ? `; ${kinds.filter(kind => kind !== 'interval').join(', ')}` : ''}` : kinds.length ? kinds.join(', ') : 'On demand' },
+            enabled: job.Disabled === true ? false : null, state: runtime?.pid !== '-' && runtime?.pid ? 'running' : runtime ? 'loaded' : 'declared',
+            runner_available: runtime ? true : null, last_exit_code: runtime && runtime.exit !== '-' ? Number(runtime.exit) : null }));
+        } catch { warnings.push(`Cannot inspect launchd definition ${entry.name}`); }
+      } }));
+    }
+  } else if (ctx.platform === 'linux') {
+    for (const scope of ['system', 'user']) {
+      const scopeArgs = scope === 'user' ? ['--user'] : [];
+      try {
+        const [installed, loaded] = await Promise.all([
+          run('systemctl', [...scopeArgs, 'list-unit-files', '--type=timer', '--no-legend', '--no-pager']),
+          run('systemctl', [...scopeArgs, 'list-units', '--type=timer', '--all', '--no-legend', '--no-pager', '--plain']),
+        ]);
+        const active = new Map(loaded.trim().split('\n').map(line => line.trim().split(/\s+/)).filter(parts => parts[0]?.endsWith('.timer')).map(parts => [parts[0], parts[2]]));
+        for (const line of installed.trim().split('\n')) {
+          const [name, state] = line.trim().split(/\s+/); if (!name?.endsWith('.timer')) continue;
+          records.push(automation(ctx, 'operating-system', `${scope}:${name}`, { name, origin: `systemd:${scope}:${name}`, trigger: { kind: 'timer', summary: 'System timer' }, enabled: ['enabled', 'enabled-runtime', 'linked', 'linked-runtime'].includes(state) ? true : ['disabled', 'masked'].includes(state) ? false : null, state: active.get(name) || state, runner_available: active.has(name) ? true : null }));
+        }
+      } catch (error) { warnings.push(`${scope}: ${error.message}`); }
+    }
+  } else return { status: 'unsupported', records: [], error: `No operating-system adapter for ${ctx.platform}` };
+  try {
+    const cron = await run('crontab', ['-l']);
+    for (const [index, line] of cron.split('\n').entries()) {
+      const clean = line.trim(); if (!clean || clean.startsWith('#') || /^[A-Za-z_][A-Za-z0-9_]*\s*=/.test(clean)) continue;
+      const match = clean.match(/^(@\w+|(?:\S+\s+){4}\S+)\s+.+$/); if (!match) { warnings.push(`Unrecognized crontab line ${index + 1}`); continue; }
+      records.push(automation(ctx, 'operating-system', `crontab:${digest(clean)}`, { name: `Crontab job ${index + 1}`, origin: 'crontab:current-user', trigger: { kind: 'cron', summary: match[1] }, enabled: true, state: 'declared' }));
+    }
+  } catch (error) {
+    // Exit 1 means either no crontab or an access error; never claim empty coverage without evidence.
+    warnings.push(error.message);
+  }
+  records.sort((left, right) => left.id.localeCompare(right.id));
+  return { records, status: warnings.length ? 'partial' : 'ok', ...(warnings.length ? { error: [...new Set(warnings)].slice(0, 12).join('; ') } : {}) };
+}
+
+export async function createContext(packageRoot, options = {}) {
+  const config = options.config || await coreModule(packageRoot, 'config');
+  const active = config.getActiveBrains(options.projectRoot || process.cwd());
+  const brains = [active.global, active.project].filter(Boolean);
+  const unique = [...new Map(brains.map(brain => [path.resolve(brain.brainDir), brain])).values()];
+  return { packageRoot, projectRoot: options.projectRoot || process.cwd(), node_id: options.node_id || os.hostname(), home: options.home || os.homedir(), platform: options.platform || process.platform, brains: unique, config, ...options };
+}
+
+export async function sourceAdapters(ctx) {
+  const load = name => ctx.modules?.[name] || coreModule(ctx.packageRoot, name);
+  return {
+    'plugin-tasks': async () => {
+      const store = await load('plugin-store');
+      const plugins = store.listInstalledPlugins(ctx.projectRoot).map(plugin => ({ ...plugin }));
+      if (plugins.some(plugin => plugin.tasks?.some(task => task.placement === 'selected-node'))) {
+        const loader = await load('plugin-loader');
+        const discovered = new Map(loader.discoverPlugins(ctx.projectRoot).map(plugin => [plugin.id, plugin]));
+        for (const plugin of plugins) {
+          if (!plugin.tasks?.some(task => task.placement === 'selected-node')) continue;
+          const source = discovered.get(plugin.id);
+          if (source) plugin.task_nodes = store.readPluginRecord(source)?.task_nodes || {};
+        }
+      }
+      const records = scheduledTasks(plugins, ctx);
+      const events = await load('ssss-operation-service');
+      const payloads = [];
+      for (const brain of ctx.brains) for (const event of await events.listVfsEvents({ vaultRoot: path.join(brain.brainDir, 'memory-vault') })) {
+        let payload = event?.payload || event?.content; if (typeof payload === 'string') { try { payload = JSON.parse(payload); } catch { continue; } }
+        if (payload?.kind === 'plugin.task_run' && (!payload.node_id || payload.node_id === ctx.node_id)) payloads.push({ ...payload, at: event.timestamp || event.created_at || payload.at || null });
+      }
+      const eventTime = event => Date.parse(event.at || event.slot || '') || 0;
+      const outcome = event => ({ at: event.at || event.slot || null, slot: event.slot || null,
+        state: event.ok === true ? 'success' : event.ok === false ? 'failed' : 'unknown', exit_code: event.exit_code ?? null });
+      for (const record of records) {
+        const matching = payloads.filter(event => event.plugin_id === record.plugin_id && event.command === record.command)
+          .sort((a, b) => eventTime(a) - eventTime(b));
+        const last = matching.at(-1);
+        if (last) {
+          record.last_run = outcome(last);
+          // The failure receipt is shown only for the record the operator asked about.
+          if (last.ok === false && ctx.receiptId === record.id) record.last_run.receipt = failureReceipt(last);
+        }
+        const handled = record.last_handled_slot && matching.filter(event => event.slot === record.last_handled_slot).at(-1);
+        if (handled) record.last_handled_outcome = outcome(handled);
+      }
+      return records;
+    },
+    'task-queue': async () => {
+      const tasks = await load('task-envelope');
+      const queues = await Promise.all(ctx.brains.map(async (brain) => {
+        const queueDir = tasks.resolveQueueDir(brain.brainDir);
+        const canCancel = await canCancelPending(tasks, queueDir);
+        return tasks.listTasks(queueDir, { status: 'all' }).map((task) => {
+          const record = automation(ctx, 'task-queue', `${brain.layer}:${task.slug}`, { name: text(task.intent || task.slug), origin: `task:${brain.layer}:${task.slug}`, trigger: { kind: 'queue', summary: 'Queued work' }, enabled: !['completed', 'cancelled'].includes(task.status), state: task.status, owner_ref: { layer: brain.layer, slug: task.slug }, last_run: task.completed_at || task.failed_at ? { at: task.completed_at || task.failed_at, state: task.status, exit_code: null } : null });
+          if (canCancel && task.status === 'pending') record.actions = [{ command: 'cancel', label: 'Cancel task', args: [record.id], effect: 'write' }];
+          return record;
+        });
+      }));
+      return queues.flat();
+    },
+    'research-queue': async () => {
+      const research = await load('research-queue');
+      const records = [];
+      for (const brain of ctx.brains) {
+        let offset = 0;
+        while (true) {
+          const page = research.listQueue({ brainDir: brain.brainDir, limit: 500, offset });
+          if (!Array.isArray(page.items)) throw new Error('Invalid research queue response');
+          records.push(...page.items.map(task => automation(ctx, 'research-queue', `${brain.layer}:${task.id}`, { name: text(task.topic), origin: `research:${brain.layer}:${task.id}`, trigger: { kind: 'queue', summary: task.research_phase || 'Research queue' }, enabled: ['pending', 'in_progress'].includes(task.status), state: task.status, last_run: task.completed_at ? { at: task.completed_at, state: task.status, exit_code: null } : null })));
+          offset += page.items.length;
+          if (offset >= page.total) break;
+          if (!page.items.length) throw new Error('Research pagination made no progress');
+          if (records.length >= 10000) return { records, status: 'partial', error: 'Research queue exceeded 10000 records' };
+        }
+      }
+      return records;
+    },
+    daemon: async () => {
+      const [health, update] = await Promise.all([load('startup-health'), load('automatic-brain-updates')]);
+      return ctx.brains.flatMap(brain => {
+        const observation = health.observeDaemon(brain.brainDir), running = observation.status === 'running';
+        const maintenance = update.automaticUpdateStatus(brain.brainDir);
+        return [automation(ctx, 'daemon', `${brain.layer}:daemon`, { name: `${brain.layer} background worker`, origin: `daemon:${brain.layer}`, trigger: { kind: 'queue', summary: 'Durable queue and maintenance loop' }, state: observation.status, runner_available: running, enabled: null }),
+          automation(ctx, 'daemon', `${brain.layer}:package-updates`, { name: `${brain.layer} package maintenance`, origin: `automatic-brain-updates:${brain.layer}`, trigger: { kind: 'interval', summary: `Every ${maintenance.intervalMs / 60000} minutes; failed checks retry` }, enabled: maintenance.enabled, state: maintenance.enabled ? 'configured' : 'disabled', runner_available: running, last_run: maintenance.last ? { at: maintenance.last.checkedAt ? new Date(maintenance.last.checkedAt).toISOString() : null, state: maintenance.last.failed ? 'failed' : 'success', exit_code: null } : null }),
+          ...['vault-watch', 'source-watch', 'session-ingest', 'cli-surfaces', 'repo-sync', 'github-sync', 'obsidian-watch'].map(name => automation(ctx, 'daemon', `${brain.layer}:${name}`, { name: `${brain.layer} ${name}`, origin: `daemon:${brain.layer}:${name}`, trigger: { kind: name.includes('watch') ? 'file-change' : name === 'session-ingest' ? 'boot' : 'maintenance', summary: 'Daemon-managed; individual registration is not reported by owner' }, state: 'unknown', runner_available: running }))];
+      });
+    },
+    workflows: async () => {
+      const vfs = await load('vfs-documents');
+      return ctx.brains.flatMap(brain => vfs.listVfsDocuments(path.join(brain.brainDir, 'memory-vault')).filter(doc => ['workflow', 'trigger'].includes(doc.type)).flatMap(doc => {
+        const triggers = doc.type === 'trigger' ? [{ ...doc, type: doc.source }] : Array.isArray(doc.triggers) && doc.triggers.length ? doc.triggers : [{ type: 'manual' }];
+        return triggers.map((trigger, index) => automation(ctx, 'workflows', `${brain.layer}:${doc.vfs_path}:${trigger.id || trigger.trigger_id || index}`, { name: text(doc.title || doc.name || doc.id || doc.slug), origin: `vfs:${brain.layer}:${doc.vfs_path}`, trigger: { kind: text(trigger.type), summary: text(trigger.cron || trigger.interval || trigger.event_type || trigger.type || 'Unknown trigger'), ...(trigger.timezone ? { timezone: text(trigger.timezone) } : {}) }, enabled: doc.type === 'trigger' ? doc.status === 'active' ? true : ['disabled', 'paused'].includes(doc.status) ? false : null : typeof doc.isActive === 'boolean' ? doc.isActive : null, state: 'declared', runner_available: null }));
+      }));
+    },
+    'composed-commands': async () => {
+      const commands = await load('command-surface');
+      const dirs = commands.commandScopeDirectories(ctx.projectRoot, ctx.config.globalAgentDir);
+      return commands.listSurfaceCommands(dirs).map(command => automation(ctx, 'composed-commands', `${command.scope}:${command.name}`, { name: command.name, origin: `composable-cli:${command.scope}:${command.name}`, trigger: { kind: 'manual', summary: 'Reusable command; requires explicit automation binding' }, state: 'definition', enabled: null }));
+    },
+    'operating-system': () => operatingSystem(ctx),
+    'agent-platforms': async () => ({ status: 'unsupported', records: [], error: 'No authenticated agent-platform inventory contract is configured; provider automations cannot be inferred from local command definitions.' }),
+  };
+}
+
+export async function collectLocalAutomations(packageRoot, options = {}) {
+  const ctx = await createContext(packageRoot, options), checked_at = new Date().toISOString();
+  const adapters = options.adapters || await sourceAdapters(ctx);
+  return { node_id: ctx.node_id, ...await collectSources({ sources: SOURCES, adapters, checkedAt: checked_at }) };
+}
+
+export async function cancelAutomation(packageRoot, id, options = {}) {
+  const ctx = await createContext(packageRoot, options);
+  const tasks = ctx.modules?.['task-envelope'] || await coreModule(packageRoot, 'task-envelope');
+  for (const brain of ctx.brains) {
+    const queueDir = tasks.resolveQueueDir(brain.brainDir);
+    const task = tasks.listTasks(queueDir, { status: 'all' })
+      .find((candidate) => recordId(ctx.node_id, 'task-queue', `${brain.layer}:${candidate.slug}`) === id);
+    if (!task) continue;
+    if (task.status !== 'pending') throw new Error('Task is no longer pending');
+    if (!await canCancelPending(tasks, queueDir)) throw new Error('This host cannot safely cancel a pending task');
+    const result = await tasks.cancelTask(queueDir, task.slug, { expectedStatus: 'pending' });
+    if (!result.success) throw new Error(result.error || 'Task cancellation failed');
+    if (tasks.getTask(queueDir, task.slug)?.status !== 'cancelled') throw new Error('Task owner did not confirm cancellation');
+    return { success: true, id, state: 'cancelled' };
+  }
+  throw new Error('Cancellable local automation not found');
+}

package/scaffold/.agent/skills/total-recall/plugins/automations/capability/index.mjs

@@ -0,0 +1,16 @@
+/** Source collection for an application-owned automation inventory. No host or transport assumptions. */
+export async function collectSources({ sources, adapters, checkedAt, limit = 10000 }) {
+  if (!Array.isArray(sources) || !sources.every(source => typeof source === 'string') || new Set(sources).size !== sources.length) throw new Error('Unique source ids are required');
+  if (!adapters || typeof adapters !== 'object' || !checkedAt || !Number.isSafeInteger(limit) || limit < 1) throw new Error('Adapters, checkedAt and a positive record limit are required');
+  const results = await Promise.all(sources.map(async source => {
+    try {
+      if (typeof adapters[source] !== 'function') return { source, status: 'unsupported', checked_at: checkedAt, records: [], error: 'Source adapter is unavailable' };
+      const value = await adapters[source]();
+      const result = Array.isArray(value) ? { records: value, status: 'ok' } : value;
+      if (!result || !Array.isArray(result.records) || !['ok', 'partial', 'unsupported', 'disabled', 'error', 'unauthorized'].includes(result.status)) throw new Error('Invalid source result');
+      if (result.records.length > limit) return { source, status: 'partial', checked_at: checkedAt, records: result.records.slice(0, limit), error: `Source inventory exceeded ${limit} records` };
+      return { ...result, source, checked_at: checkedAt };
+    } catch (error) { return { source, status: 'error', checked_at: checkedAt, records: [], error: `Source discovery failed${typeof error.code === 'string' && /^[A-Z_0-9]+$/.test(error.code) ? ` (${error.code})` : ''}` }; }
+  }));
+  return { automations: results.flatMap(result => result.records), coverage: results.map(({ records, ...coverage }) => coverage), checked_at: checkedAt };
+}

package/scaffold/.agent/skills/total-recall/plugins/automations/cli.mjs

@@ -0,0 +1,130 @@
+import { meshAutomationInventory, filterInventory } from './inventory.mjs';
+import { cancelAutomation, SOURCES } from './adapters.mjs';
+import { spawnSync } from 'node:child_process';
+
+export const HELP = `Usage: total-recall automations <command> [options]
+
+Commands:
+  list                 List automation records and source coverage across the mesh
+  status               Report node/source coverage and observed automation states
+  show <id>            Inspect one source-owned automation record
+  cancel <id>          Cancel a pending local durable task through its owner
+  dream --all-brains   Run dream, including decay, for every brain on this node
+
+Options:
+  --local              Inspect this node only (also used by authenticated peers)
+  --node <id|hostname>  Select one known mesh node
+  --source <source>    Filter records by source
+  --trigger <kind>     Filter records by trigger kind
+  --state <state>      Filter records by observed state
+  --receipt            Include a failed plugin task receipt (show --local, terminal only)
+  --json               Machine-readable output (also the default)
+  --help, -h           Show this help
+
+Sources: ${SOURCES.join(', ')}
+Declarations, runner availability and observed outcomes remain separate.
+Unsupported or failed sources are reported explicitly; they are never empty success.`;
+
+export function parseArgs(argv) {
+  const args = argv[2] === 'automations' ? argv.slice(3) : [...argv];
+  if (!args.length || args.includes('--help') || args.includes('-h')) return { help: true };
+  const command = args.shift();
+  if (!['list', 'status', 'show', 'cancel', 'dream'].includes(command)) throw new Error(`Unknown command: ${command}`);
+  if (command === 'dream') {
+    if (args.filter(arg => arg === '--all-brains').length !== 1 || args.some(arg => !['--all-brains', '--json'].includes(arg))) {
+      throw new Error('dream requires --all-brains and accepts only --json');
+    }
+    return { command };
+  }
+  const result = { command, filters: {}, localOnly: false };
+  if (['show', 'cancel'].includes(command)) {
+    result.id = args.shift(); if (!result.id || !/^[a-z-]+:[a-f0-9]{20}$/.test(result.id)) throw new Error('A valid automation id is required');
+  }
+  while (args.length) {
+    const flag = args.shift();
+    if (flag === '--json') continue;
+    if (flag === '--local') { result.localOnly = true; continue; }
+    if (flag === '--receipt') { result.receipt = true; continue; }
+    const name = { '--node': 'node', '--source': 'source', '--trigger': 'trigger', '--state': 'state' }[flag];
+    if (!name) throw new Error(`Unknown option: ${flag}`);
+    const value = args.shift(); if (!value || value.startsWith('-')) throw new Error(`Missing value for ${flag}`);
+    if (result.filters[name]) throw new Error(`Duplicate option: ${flag}`);
+    result.filters[name] = value;
+  }
+  if (result.filters.source && !SOURCES.includes(result.filters.source)) throw new Error('Unknown source');
+  if (result.receipt && (command !== 'show' || !result.localOnly || !result.id.startsWith('plugin-tasks:'))) {
+    throw new Error('--receipt requires show <plugin-task-id> --local');
+  }
+  if (command === 'cancel' && (Object.keys(result.filters).length || result.localOnly)) throw new Error('cancel accepts only a local automation id and --json');
+  return result;
+}
+
+/** Core owns dream execution. Check support before an old core can ignore the flag. */
+export function runDream(spawn = spawnSync) {
+  const options = { shell: false, encoding: 'utf8', timeout: 30000, maxBuffer: 4 * 1024 * 1024, windowsHide: true };
+  const failure = (error, child = {}, results = []) => ({
+    ok: false, exit_code: Number.isInteger(child.status) && child.status !== 0 ? child.status : 1,
+    child_exit_code: child.status ?? null, signal: child.signal || null, results, error,
+  });
+  try {
+    const help = spawn('total-recall', ['dream', '--help'], options);
+    if (help.error || help.signal || help.status !== 0) return failure(`Cannot check core dream support: ${help.error?.message || help.stderr || help.signal || 'help failed'}`, help);
+    if (!String(help.stdout).includes('--all-brains')) return failure('Core dream does not support --all-brains. Update Total Recall before this task can run.', help);
+    const child = spawn('total-recall', ['dream', '--all-brains', '--json'], { ...options, timeout: 1800000 });
+    if (child.error || child.signal) return failure(`Core dream did not complete: ${child.error?.message || child.signal}`, child);
+    let report;
+    try {
+      report = JSON.parse(child.stdout);
+    } catch {
+      // Core log lines may surround one JSON report.
+      const reports = String(child.stdout || '').split('\n').flatMap(line => {
+        try { const value = JSON.parse(line); return Array.isArray(value) || Array.isArray(value?.results) || Array.isArray(value?.brains) ? [value] : []; } catch { return []; }
+      });
+      if (reports.length === 1) report = reports[0];
+    }
+    const results = Array.isArray(report) ? report : report?.results ?? report?.brains;
+    if (!Array.isArray(results) || !results.length || results.some(result => !result || typeof result !== 'object' || Array.isArray(result)
+      || !(typeof result.ok === 'boolean' || typeof result.success === 'boolean' || ['ok', 'success', 'completed', 'failed', 'error', 'skipped'].includes(result.status) || ['ok', 'success', 'completed', 'failed', 'error', 'skipped'].includes(result.state)))) {
+      return failure(`Core dream returned no per-brain results (exit ${child.status}). Update Total Recall if --all-brains is unavailable. ${String(child.stderr || '').trim()}`.trim(), child);
+    }
+    if (child.status !== 0 || report?.ok === false || report?.success === false || results.some(result => result.ok === false || result.success === false || result.error
+      || (Number.isInteger(result.exit_code) && result.exit_code !== 0) || ['failed', 'error'].includes(result.status) || ['failed', 'error'].includes(result.state))) {
+      return failure(`Core dream failed (exit ${child.status}). ${String(child.stderr || '').trim()}`.trim(), child, results);
+    }
+    return { ok: true, exit_code: 0, child_exit_code: 0, results };
+  } catch (error) {
+    return failure(`Cannot run core dream: ${error.message}`);
+  }
+}
+
+export async function run(argv = [], dependencies = {}) {
+  const parsed = parseArgs(argv), write = dependencies.write || (output => process.stdout.write(output));
+  if (parsed.help) { write(`${HELP}\n`); return; }
+  if (parsed.command === 'dream') {
+    const result = runDream(dependencies.spawnSync);
+    write(`${JSON.stringify(result)}\n`);
+    if (!result.ok) (dependencies.setExitCode || (code => { process.exitCode = code; }))(result.exit_code);
+    return result;
+  }
+  if (parsed.receipt && !process.stdin.isTTY) throw new Error('--receipt requires a local terminal');
+  const root = dependencies.packageRoot || process.env.TR_PACKAGE_ROOT;
+  if (!root) throw new Error('TR_PACKAGE_ROOT is required');
+  if (parsed.command === 'cancel') {
+    const result = await (dependencies.cancel || cancelAutomation)(root, parsed.id);
+    write(`${JSON.stringify(result)}\n`); return result;
+  }
+  let inventory = await (dependencies.inventory || meshAutomationInventory)(root, {
+    localOnly: parsed.localOnly,
+    ...(parsed.receipt ? { receiptId: parsed.id } : {}),
+  });
+  inventory = filterInventory(inventory, parsed.filters);
+  let result = inventory;
+  if (parsed.command === 'show') {
+    const records = inventory.nodes.flatMap(node => node.automations).filter(record => record.id === parsed.id);
+    if (records.length !== 1) throw new Error(records.length ? 'Automation id is ambiguous' : 'Automation not found');
+    result = { schema_version: 1, checked_at: inventory.checked_at, automation: records[0] };
+  }
+  if (parsed.command === 'status') result = { ...inventory, nodes: inventory.nodes.map(node => ({ ...node, counts: node.automations.reduce((counts, record) => ({ ...counts, [record.state]: (counts[record.state] || 0) + 1 }), {}), automations: undefined })) };
+  write(`${JSON.stringify(result)}\n`); return result;
+}
+export default run;

package/{src/core/plugin-cron.mjs → scaffold/.agent/skills/total-recall/plugins/automations/cron.mjs}

@@ -1,4 +1,4 @@
-/** Pure cron parsing shared by plugin authoring and scheduling. */
+/** Five-field cron parsing and matching for manifest plugin tasks. */
 const FIELD_RANGES = [
   [0, 59], // minute
   [0, 23], // hour
@@ -53,5 +53,3 @@ export function cronMatches(cron, date) {
   if (cron.dowStar) return domOk;
   return domOk || dowOk;
 }
-
-

package/scaffold/.agent/skills/total-recall/plugins/automations/inventory.mjs

@@ -0,0 +1,88 @@
+import os from 'node:os';
+import { collectLocalAutomations, coreModule, SOURCES, scheduledTasks, recordId } from './adapters.mjs';
+export { scheduledTasks } from './adapters.mjs';
+
+const MAX_PEER_BYTES = 4 * 1024 * 1024;
+export function parseInventoryOutput(output) {
+  if (typeof output !== 'string' || Buffer.byteLength(output) > MAX_PEER_BYTES) throw new Error('Invalid inventory output');
+  try { return JSON.parse(output); } catch {
+    // Host logs may surround command output. Accept one versioned inventory,
+    // never guess between multiple command results or parse a logger payload.
+    const values = output.trim().split('\n').flatMap(line => { try { const value = JSON.parse(line); return value?.schema_version === 1 && Array.isArray(value.nodes) ? [value] : []; } catch { return []; } });
+    if (values.length !== 1) throw new Error('Expected one versioned inventory result');
+    return values[0];
+  }
+}
+const unavailableCoverage = (status, checked_at) => SOURCES.map(source => ({ source, status, checked_at }));
+function verifyLocalResult(value) {
+  if (!value || !Array.isArray(value.automations) || !Array.isArray(value.coverage)) throw new Error('Invalid local inventory');
+  if (value.automations.length > 10000 * SOURCES.length) throw new Error('Peer inventory exceeds record limit');
+  const statuses = new Set(['ok', 'partial', 'unsupported', 'disabled', 'error', 'unauthorized', 'offline']);
+  for (const coverage of value.coverage) if (!SOURCES.includes(coverage.source) || !statuses.has(coverage.status)) throw new Error('Invalid peer coverage');
+  for (const record of value.automations) if (typeof record.id !== 'string' || !SOURCES.includes(record.source) || typeof record.name !== 'string') throw new Error('Invalid peer automation');
+  return value;
+}
+function nodeResult(base, value) {
+  const missing = SOURCES.filter(source => !value.coverage.some(item => item.source === source));
+  const coverage = [...value.coverage, ...missing.map(source => ({ source, status: 'unsupported', checked_at: base.checked_at, error: 'Peer did not report this source' }))];
+  // Remote mutation is never advertised through a local-only control.
+  const automations = value.automations.map(record => ({ ...record, node_id: base.node_id, actions: base.self ? record.actions || [] : [] }));
+  return { ...base, status: coverage.every(source => ['ok', 'disabled'].includes(source.status)) ? 'ok' : 'partial', automations, coverage };
+}
+
+/** The plugin owns composition; every source and peer failure remains visible. */
+export async function meshAutomationInventory(packageRoot, options = {}) {
+  const checked_at = new Date().toISOString();
+  const mesh = options.mesh || await coreModule(packageRoot, 'mesh');
+  const self = options.self || mesh.getMeshSelf?.() || { hostname: os.hostname(), self: true };
+  const selfId = self.ip || self.hostname || os.hostname();
+  let nodes = options.localOnly ? [{ ...self, self: true }] : options.nodes || mesh.listEnrichedMeshNodes();
+  if (!nodes.some(node => node.self || (node.ip && node.ip === self.ip))) nodes = [{ ...self, self: true }, ...nodes];
+  nodes = [...new Map(nodes.map(node => [node.ip || node.hostname, node])).values()];
+  const local = options.local || await collectLocalAutomations(packageRoot, { ...options, node_id: selfId });
+  const execPeer = options.execPeer || mesh.execMeshCommand;
+  let authorization = options.authorization;
+  if (!options.localOnly && authorization === undefined) {
+    try { authorization = await (await coreModule(packageRoot, 'mesh-auth')).getMeshSyncAuthorization(); } catch { authorization = null; }
+  }
+  const peerUrl = options.peerUrl || (await coreModule(packageRoot, 'plugin-peers')).meshPeerUrl;
+  const fetchImpl = options.fetchImpl || (await coreModule(packageRoot, 'throttled-fetch')).throttledFetch;
+  const records = await Promise.all(nodes.map(async node => {
+    const node_id = node.ip || node.hostname;
+    const base = { node_id, hostname: node.hostname, ip: node.ip, self: Boolean(node.self || node_id === selfId), online: Boolean(node.self || node.online), checked_at, automations: [], coverage: [] };
+    if (base.self) return nodeResult(base, verifyLocalResult(local));
+    const unavailable = (status, error) => ({ ...base, status, ...(error ? { error } : {}), coverage: unavailableCoverage(status === 'unreachable' ? 'error' : status, checked_at) });
+    if (!node.online) return unavailable('offline');
+    const port = node.brain_port || Number(process.env.TR_SERVER_PORT || process.env.PORT || 3000);
+    try {
+      if (execPeer) {
+        try {
+          // Mesh owns the authenticated transport. The command is fixed and read-only.
+          // A mesh-sync token is not a PAT for the generic plugin-run HTTP route.
+          const result = await execPeer(node_id, 'total-recall automations list --local --json', { timeoutMs: 15000 });
+          if (result.success && result.exitCode === 0) {
+            const inventory = parseInventoryOutput(result.stdout);
+            if (inventory.schema_version !== 1 || !Array.isArray(inventory.nodes) || inventory.nodes.length !== 1 || inventory.nodes[0].self !== true) throw new Error('Unsupported peer inventory');
+            return nodeResult(base, verifyLocalResult(inventory.nodes[0]));
+          }
+        } catch { /* Retain metadata through its separate mesh-auth contract below. */ }
+      }
+      if (!authorization) return unavailable('unauthorized', 'Full peer inventory is unavailable; mesh metadata authorization is unavailable');
+      // Old or unreachable CLI hosts may still expose plugin declarations.
+      const fallback = await fetchImpl(peerUrl(node.ip, '/api/mesh/plugins/installed', port), { headers: { Authorization: authorization } }, 5000);
+      if (!fallback.ok) return unavailable(fallback.status === 404 ? 'unsupported' : [401, 403].includes(fallback.status) ? 'unauthorized' : 'error', `HTTP ${fallback.status}`);
+      const data = await fallback.json();
+      if (!Array.isArray(data.plugins)) throw new Error('Invalid legacy peer response');
+      return nodeResult(base, { automations: scheduledTasks(data.plugins, { node_id }), coverage: SOURCES.map(source => ({ source, status: source === 'plugin-tasks' ? 'partial' : 'unsupported', checked_at,
+        error: source === 'plugin-tasks' ? 'Peer metadata reports declarations only; placement and outcome evidence may be missing' : 'Full peer inventory is unavailable' })) });
+    } catch (error) { return unavailable('unreachable', error.name === 'SyntaxError' ? 'Invalid peer JSON' : error.message); }
+  }));
+  return { schema_version: 1, checked_at, complete: records.every(node => node.status === 'ok'), nodes: records };
+}
+
+export function filterInventory(inventory, filters = {}) {
+  let nodes = inventory.nodes;
+  if (filters.node) nodes = nodes.filter(node => [node.node_id, node.hostname, node.ip].includes(filters.node));
+  if (filters.node && !nodes.length) throw new Error('Unknown node');
+  return { ...inventory, nodes: nodes.map(node => ({ ...node, automations: node.automations.filter(record => (!filters.source || record.source === filters.source) && (!filters.trigger || record.trigger?.kind === filters.trigger) && (!filters.state || record.state === filters.state)) })) };
+}