total-recall-brain 3.44.0 → 3.45.0

package/scaffold/.agent/skills/total-recall/plugins/git-sentinel/README.md

@@ -1,53 +0,0 @@
-# Git Hygiene
-
-Reports the state of the git repository you run it in: current branch, staged / unstaged / untracked / conflicted files, commits not yet pushed to upstream, and stashes.
-
-**Reporting accuracy, verified 2026-10-23.** Two defects reported in the September 30 review are fixed and covered by testing:
-
-- **Porcelain columns are preserved.** `git status --porcelain` output is never trimmed, so a file whose name begins with a space parses correctly. Verified against a file literally named `" leading-space.txt"`, which reports as `A   leading-space.txt`.
-- **An unknown upstream is never reported as zero unpushed commits.** `upstreamStatus` distinguishes `tracking`, `none`, `gone`, `detached`, `unborn`, `unknown` and `error`; where no comparison exists, `unpushedCommits` is `null` rather than `0`. Verified in a repository with no remote configured.
-
-**Use cases:** software-development
-
-## Install
-
-```bash
-npx total-recall plugin install git-sentinel
-```
-
-## Use
-
-```bash
-npx total-recall git-sentinel audit          # human summary
-npx total-recall git-sentinel audit --json   # machine output for agents
-npx total-recall git-sentinel diff           # diffstat of unstaged changes
-npx total-recall git-sentinel identity --json # current commit identity and local history audit
-```
-
-## Share with your other nodes
-
-```bash
-npx total-recall plugin share git-sentinel
-# on another node on the mesh:
-npx total-recall plugin install peer:<this-node>/git-sentinel
-```
-
-## Capability scope
-
-The plugin runs against the Git worktree selected by the installed Total Recall CLI. Use `diff --patch`, `--cached` and `--base <ref>` for actual Git comparisons. Worktree listing is read-only, creation makes a detached worktree, and removal requires a registered linked worktree. Dirty removal requires `--force`. See the [Git Sentinel project tracker](docs/projects/in-progress/GIT_SENTINEL_CARD/GIT_SENTINEL_CARD_PROJECT_TRACKER.md).
-
-## Using this from an agent
-
-Use the read operations for worktree state, changes, upstream comparison, stashes and commit identity. Worktree creation and removal have separate operation effects.
-
-```bash
-total-recall git-sentinel audit --json
-total-recall git-sentinel diff --json
-total-recall git-sentinel diff --patch --cached --json
-total-recall git-sentinel identity --json
-total-recall git-sentinel worktree-list --json
-total-recall git-sentinel worktree-create <path> --base <ref> --json
-total-recall git-sentinel worktree-remove <path> --json
-```
-
-Raw commands this plugin owns: `git status`, `git stash list`, `git diff --stat`, `git config user.*` and author lookups through `git log`.

package/scaffold/.agent/skills/total-recall/plugins/git-sentinel/plugin.json

@@ -1,129 +0,0 @@
-{
-  "$schema": "https://github.com/gregiteen/total-recall/blob/main/metadata.plugin.schema.json",
-  "id": "git-sentinel",
-  "name": "Git Sentinel",
-  "version": "1.1.5",
-  "description": "Worktree hygiene, branch inspection, unpushed commits, and stash tracker.",
-  "author": "Total Recall",
-  "license": "MIT",
-  "use_cases": [
-    "software-development"
-  ],
-  "gate": {
-    "tasks": ["Check a repository's state before committing or pushing", "Review what changed in a working tree", "Read the commit identity"],
-    "owned_commands": [
-      { "pattern": "git(\\s+-C\\s+\\S+)?\\s+status\\b", "use": "total-recall git-sentinel audit" },
-      { "pattern": "git(\\s+-C\\s+\\S+)?\\s+stash\\s+list\\b", "use": "total-recall git-sentinel audit" },
-      { "pattern": "git(\\s+-C\\s+\\S+)?\\s+diff\\s+--stat\\b", "use": "total-recall git-sentinel diff" },
-      { "pattern": "git(\\s+-C\\s+\\S+)?\\s+config\\s+(--get\\s+)?user\\.(name|email)\\s*($|[;&|])", "use": "total-recall git-sentinel identity" },
-      { "pattern": "git(\\s+-C\\s+\\S+)?\\s+log\\b[^;&|]*%a[en]", "use": "total-recall git-sentinel identity" }
-    ]
-  },
-  "cli": {
-    "answers_help": true,
-    "command": "git-sentinel",
-    "handler": "./cli.mjs",
-    "subcommands": [
-      {
-        "name": "audit",
-        "description": "Summarise branch, worktree, upstream and stash state (--json for machine output)",
-        "effect": "read"
-      },
-      {
-        "name": "diff",
-        "description": "Read a stat or patch for unstaged, staged or base-relative changes",
-        "effect": "read",
-        "args": [
-          { "name": "patch", "flag": "--patch", "type": "boolean", "label": "Show patch" },
-          { "name": "cached", "flag": "--cached", "type": "boolean", "label": "Use staged changes" },
-          { "name": "base", "flag": "--base", "type": "string", "label": "Base ref" }
-        ]
-      },
-      { "name": "worktree-list", "description": "Read registered worktrees for the current repository", "effect": "read" },
-      { "name": "worktree-create", "description": "Create a detached worktree at a specified path and base ref", "effect": "write", "args": [
-        { "name": "path", "type": "string", "label": "Worktree path", "required": true, "positional": true },
-        { "name": "base", "flag": "--base", "type": "string", "label": "Base ref" }
-      ] },
-      { "name": "worktree-remove", "description": "Remove an owned linked worktree, with explicit force for dirty content", "effect": "destructive", "args": [
-        { "name": "path", "type": "string", "label": "Worktree path", "required": true, "positional": true },
-        { "name": "force", "flag": "--force", "type": "boolean", "label": "Allow removal of dirty content" }
-      ] },
-      { "name": "worktree", "description": "Compatibility form: worktree list, create or remove", "effect": "destructive" },
-      {
-        "name": "identity",
-        "description": "Show who commits here and which identities the history publishes; exits 1 on a missing or machine-derived identity (--json for machine output)",
-        "effect": "read"
-      }
-    ]
-  },
-  "card_face": {
-    "skin": "copper-obsidian",
-    "theme": "copper",
-    "headline": "Worktree Hygiene & Repository Watch",
-    "primary_color": "#b45309",
-    "secondary_color": "#0c0a09",
-    "accent_color": "#f59e0b",
-    "touch_layout": "comfortable",
-    "interactive": true,
-    "quick_actions": [
-      {
-        "subcommand": "audit",
-        "label": "AUDIT"
-      },
-      {
-        "subcommand": "diff",
-        "label": "DIFFSTAT"
-      }
-    ]
-  },
-  "ui": {
-    "design_tokens": "ui/DESIGN.md",
-    "elements": [
-      {
-        "id": "card",
-        "kind": "card",
-        "tag": "tr-git-sentinel-card",
-        "module": "ui/card.js",
-        "description": "Git Hygiene Repository Hygiene Card Face"
-      }
-    ]
-  },
-  "auth": {
-    "plugin": "auth",
-    "methods": [
-      "passkey",
-      "google-oauth2"
-    ],
-    "session_verification": true
-  },
-  "deploy": {
-    "targets": [
-      "ssss-app",
-      "nextjs",
-      "react",
-      "flask"
-    ],
-    "required_ssss_version": ">=0.9.3",
-    "access_grants": [
-      "auth:session:verify",
-      "ssss:vault:read",
-      "ssss:vault:write",
-      "ssss:events:append"
-    ]
-  },
-  "branding": {
-    "name": "Git Hygiene",
-    "color": "#b45309",
-    "accent": "#f59e0b",
-    "badge": "Repository Hygiene",
-    "font": "space-grotesk"
-  },
-  "status": {
-    "command": "audit",
-    "refresh_seconds": 60
-  },
-  "distribution": {
-    "tier": "official",
-    "license": "open"
-  }
-}

package/src/core/append-log.mjs

@@ -1,131 +0,0 @@
-/**
- * Append-only JSONL log with last-write-wins semantics and compaction.
- *
- * Write: O(1) — fs.appendFileSync one line
- * Read: O(n) on cold load, cached after first read
- * Compact: Rewrites only latest version of each key
- *
- * File format: One JSON object per line, each with a mandatory `_key` field.
- * Later entries for the same `_key` shadow earlier ones.
- * Tombstones: { "_key": "slug", "_deleted": true }
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { atomicWrite } from './vault.mjs';
-import { logger } from './logger.mjs';
-
-/** @type {Map<string, AppendLog>} Registry of all active AppendLog instances */
-const activeAppendLogs = new Map();
-
-export class AppendLog {
-  #filePath;
-  #cache; // Map<string, object> — latest value per key
-  #dirty; // number of appended lines since last compact
-  #compactThreshold;
-
-  constructor(filePath, { compactThreshold = 500 } = {}) {
-    this.#filePath = filePath;
-    this.#cache = null;
-    this.#dirty = 0;
-    this.#compactThreshold = compactThreshold;
-    activeAppendLogs.set(filePath, this);
-  }
-
-  /** Read the full index. Returns Map<key, value>. Cached after first call. */
-  entries() {
-    if (this.#cache) return this.#cache;
-    this.#cache = new Map();
-    if (!fs.existsSync(this.#filePath)) return this.#cache;
-    const raw = fs.readFileSync(this.#filePath, 'utf8');
-    for (const line of raw.split('\n')) {
-      if (!line.trim()) continue;
-      try {
-        const entry = JSON.parse(line);
-        if (entry._deleted) this.#cache.delete(entry._key);
-        else this.#cache.set(entry._key, entry);
-      } catch { /* skip corrupt lines */ }
-    }
-    return this.#cache;
-  }
-
-  /** Get a single entry by key. */
-  get(key) {
-    return this.entries().get(key) ?? null;
-  }
-
-  /** Append a single entry. O(1) I/O. */
-  append(key, value) {
-    const dir = path.dirname(this.#filePath);
-    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-    const entry = { _key: key, ...value };
-    fs.appendFileSync(this.#filePath, JSON.stringify(entry) + '\n');
-    // Update in-memory cache
-    this.entries().set(key, entry);
-    this.#dirty++;
-    if (this.#dirty >= this.#compactThreshold) {
-      this.compact();
-    }
-  }
-
-  /** Write a tombstone for a key. O(1) I/O. */
-  remove(key) {
-    const dir = path.dirname(this.#filePath);
-    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-    fs.appendFileSync(this.#filePath, JSON.stringify({ _key: key, _deleted: true }) + '\n');
-    this.entries().delete(key);
-    this.#dirty++;
-  }
-
-  /** Number of live entries. */
-  get size() {
-    return this.entries().size;
-  }
-
-  /** Convert to plain object (for JSON.stringify compatibility). */
-  toObject() {
-    const obj = {};
-    for (const [key, value] of this.entries()) {
-      const { _key, ...rest } = value;
-      obj[key] = rest;
-    }
-    return obj;
-  }
-
-  /** Compact: rewrite file with only latest versions. */
-  compact() {
-    const entries = this.entries();
-    const lines = [];
-    for (const [, value] of entries) {
-      lines.push(JSON.stringify(value));
-    }
-    atomicWrite(this.#filePath, lines.join('\n') + '\n');
-    this.#dirty = 0;
-    logger.info('append-log', `Compacted ${this.#filePath}: ${lines.length} entries`);
-  }
-
-  /** Invalidate the in-memory cache (force reload on next read). */
-  invalidate() {
-    this.#cache = null;
-    this.#dirty = 0;
-  }
-}
-
-/**
- * Compact all active AppendLog instances.
- * Returns summary with number of logs compacted and total entries.
- */
-export function compactAppendLogs() {
-  let logsCompacted = 0;
-  let totalEntries = 0;
-  for (const [filePath, log] of activeAppendLogs) {
-    try {
-      log.compact();
-      logsCompacted++;
-      totalEntries += log.size;
-    } catch (err) {
-      logger.warn('append-log', `Failed to compact ${filePath}: ${err.message}`);
-    }
-  }
-  return { logs_compacted: logsCompacted, total_entries: totalEntries };
-}

package/src/core/plugin-tasks.mjs

@@ -1,173 +0,0 @@
-/**
- * Scheduled plugin tasks.
- *
- * A manifest task `{ intent, schedule: "<5-field cron>", command }` runs the
- * plugin's own CLI subcommand on that schedule, out of process. Tasks are per
- * node by default, regardless of leadership. Tasks with selected-node placement
- * require an explicit matching node in plugin_record.task_nodes[command].
- *
- * The last minute-slot each command ran in is kept in the plugin_record, so a
- * restart neither repeats a slot nor loses one: when the daemon was busy or
- * down, the most recent matching slot since the last run (within a day) runs
- * once. A task never runs just because it was installed — the first run is the
- * first matching slot after the scheduler first sees it.
- */
-import { discoverPlugins } from './plugin-loader.mjs';
-import { readPluginRecord, patchPluginRecord, ensurePluginRecord } from './plugin-store.mjs';
-import { pluginExecutionEnabled } from './plugin-state.mjs';
-import { runPluginCommand } from './plugin-runner.mjs';
-import { appendVfsEvent } from './ssss-operation-service.mjs';
-import { vaultForPluginsDir } from './plugin-loader.mjs';
-import { logger } from './logger.mjs';
-import { getMeshSelf, meshNodeKey } from './mesh.mjs';
-
-const TASK_TIMEOUT_MS = 60_000;
-const MAX_CATCHUP_MINUTES = 24 * 60;
-import { parseCron, cronMatches } from './plugin-cron.mjs';
-export { parseCron, cronMatches } from './plugin-cron.mjs';
-const pad = (n) => String(n).padStart(2, '0');
-
-/** A selected-node task stays idle until this node's plugin record selects it. */
-export function taskRunsOnNode(task, record, self) {
-  if (task.placement !== 'selected-node') return true;
-  const selected = String(record?.task_nodes?.[task.command] || '').trim();
-  if (!selected || !self?.hostname) return false;
-  return selected === self.ip || meshNodeKey(selected) === meshNodeKey(self.hostname);
-}
-
-/** Local minute-slot key, e.g. 2026-09-22T14:05. */
-export function minuteSlot(date) {
-  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}`;
-}
-
-function slotToDate(slot) {
-  const m = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/.exec(String(slot || ''));
-  return m ? new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]), Number(m[4]), Number(m[5])) : null;
-}
-
-/**
- * The most recent slot matching `cron` in (lastSlot, now], or null.
- * @returns {string|null}
- */
-export function latestDueSlot(cron, lastSlot, now = new Date()) {
-  const floorNow = new Date(now.getFullYear(), now.getMonth(), now.getDate(), now.getHours(), now.getMinutes());
-  const last = slotToDate(lastSlot);
-  for (let i = 0; i < MAX_CATCHUP_MINUTES; i++) {
-    const candidate = new Date(floorNow.getTime() - i * 60_000);
-    if (last && candidate <= last) return null;
-    if (cronMatches(cron, candidate)) return minuteSlot(candidate);
-  }
-  return null;
-}
-
-/**
- * Run every task that is due. Tasks run sequentially so a slow plugin cannot
- * multiply into concurrent processes on a constrained host.
- * @param {{ projectRoot?: string, now?: Date, runner?: Function, selfNode?: object }} [options]
- * @returns {Promise<Array<{ plugin: string, command: string, slot: string, ok: boolean, exitCode: number|null }>>}
- */
-export async function runDuePluginTasks(options = {}) {
-  const { projectRoot = process.cwd(), now = new Date(), runner = runPluginCommand } = options;
-  const selfNode = options.selfNode === undefined ? getMeshSelf() : options.selfNode;
-  const results = [];
-
-  for (const plugin of discoverPlugins(projectRoot)) {
-    if (!plugin.valid || !Array.isArray(plugin.manifest.tasks) || plugin.manifest.tasks.length === 0) continue;
-
-    let record = readPluginRecord(plugin);
-    if (!record) record = await ensurePluginRecord(plugin);
-    // Scheduled work follows the repository's own setting for a shared plugin.
-    if (!pluginExecutionEnabled(plugin, { projectRoot })) continue;
-    const runs = { ...(record?.task_runs || {}) };
-    let changed = false;
-
-    for (const task of plugin.manifest.tasks) {
-      if (!taskRunsOnNode(task, record, selfNode)) continue;
-      let cron;
-      try {
-        cron = parseCron(task.schedule);
-      } catch (err) {
-        logger.warn('plugin-tasks', `Skipping ${plugin.id}:${task.command} — ${err.message}`);
-        continue;
-      }
-
-      if (!runs[task.command]) {
-        // First sighting: mark the present so the first run is the next real slot.
-        runs[task.command] = minuteSlot(now);
-        changed = true;
-        continue;
-      }
-
-      const slot = latestDueSlot(cron, runs[task.command], now);
-      if (!slot) continue;
-
-      const result = await runner(plugin, { subcommand: task.command, cwd: projectRoot, timeoutMs: task.timeout_ms || TASK_TIMEOUT_MS })
-        .catch((err) => ({ ok: false, exitCode: null, output: err.message, durationMs: 0, timedOut: false }));
-      runs[task.command] = slot;
-      changed = true;
-      results.push({ plugin: plugin.id, command: task.command, slot, ok: result.ok, exitCode: result.exitCode });
-
-      try {
-        await appendVfsEvent(
-          `plugins/${plugin.id}/task-${Date.now()}`,
-          {
-            kind: 'plugin.task_run',
-            plugin_id: plugin.id,
-            command: task.command,
-            intent: task.intent,
-            slot,
-            ok: result.ok,
-            exit_code: result.exitCode,
-            timed_out: !!result.timedOut,
-            duration_ms: result.durationMs,
-            output_tail: String(result.output || '').slice(-2000)
-          },
-          { actorRole: 'system', intent: 'Record plugin task run', vaultRoot: vaultForPluginsDir(plugin.pluginsDir) }
-        );
-      } catch (err) {
-        logger.warn('plugin-tasks', `Could not record task run for ${plugin.id}: ${err.message}`);
-      }
-    }
-
-    if (changed) {
-      try {
-        await patchPluginRecord(plugin, { task_runs: runs });
-      } catch (err) {
-        logger.warn('plugin-tasks', `Could not update task runs for ${plugin.id}: ${err.message}`);
-      }
-    }
-  }
-
-  return results;
-}
-
-let timer = null;
-let running = false;
-
-/** Check for due plugin tasks once a minute. Returns a stop function. */
-export function startPluginTaskScheduler(options = {}) {
-  if (timer) return () => stopPluginTaskScheduler();
-  const tick = async () => {
-    if (running) return;
-    running = true;
-    try {
-      const results = await runDuePluginTasks(options);
-      for (const r of results) {
-        logger.info('plugin-tasks', `${r.plugin}:${r.command} slot ${r.slot} ${r.ok ? 'ok' : `failed (exit ${r.exitCode})`}`);
-      }
-    } catch (err) {
-      logger.warn('plugin-tasks', `Scheduler tick failed: ${err.message}`);
-    } finally {
-      running = false;
-    }
-  };
-  timer = setInterval(tick, 60_000);
-  timer.unref?.();
-  tick();
-  return () => stopPluginTaskScheduler();
-}
-
-export function stopPluginTaskScheduler() {
-  if (timer) clearInterval(timer);
-  timer = null;
-}

package/templates/onboarding-interview.md

@@ -1,82 +0,0 @@
----
-type: task
-slug: onboarding-interview
-category: onboarding
-title: "Conduct portable-memory onboarding interview"
-status: pending
-priority: 1
-created: {{CREATED_AT}}
-updated: {{CREATED_AT}}
----
-
-## Objective
-
-Conduct a warm, practical onboarding interview so Total Recall can store durable preferences and facts as Markdown memory nodes. This is personal portable memory — not an operating system takeover. Keep the tone helpful and concrete.
-
-## Instructions for the Agent
-
-When the user starts their next chat session (and they have no `user-profile` yet), conduct this interview BEFORE unrelated work. Do NOT dump all questions at once. Ask one at a time. Acknowledge each answer before the next.
-
-Once the user has answered (or skipped any), write their answers into the vault using tools / CLI (`remember` or direct vault writes). Prefer CLI when available:
-
-```bash
-npx total-recall remember preference "..." --tags "user,profile,onboarding" --importance 5
-```
-
-## Interview Questions (ask one at a time)
-
-1. **Who are you?** — "Quick intro: what do you do, and what are you most focused on right now?"
-
-2. **What should I remember?** — "What kinds of things matter most for me to keep: decisions, preferences, project facts, people, or something else?"
-
-3. **Which tools do you use?** — "Which IDEs or agents should share this memory? (Claude Code, Cursor, Codex, Gemini, Aider, Obsidian, HTTP, etc.) I can guide you with `npx total-recall connect …`."
-
-4. **How should I talk?** — "Prefer short answers or detailed ones? Should I push back or mostly support?"
-
-5. **Hard rules** — "Any absolute do's or don'ts I must always follow (style, tools, safety)?"
-
-6. **Background work** — "Want dream consolidation and optional daemon tasks running in the background, or on-demand only?"
-
-7. **Secrets** — "API keys never go in the vault. Use `npx total-recall auth secret set`. Any keys you want to set up next?"
-
-8. **Notifications (optional)** — "Want Telegram pings when background tasks finish? If yes, BotFather token + chat ID."
-
-## Product context to reinforce (lightly, not as a lecture)
-
-- **Write** → `remember` / session ingest  
-- **Sleep** → `dream` (consolidate, conflict-check, recompile)  
-- **Read** → `recall` + compiled surfaces in any connected IDE  
-- **Async** → open task queue / daemon under policy  
-- Hosts are equal — track any repo; no product-specific hardcoding
-
-## After the Interview
-
-Write (or update) these files:
-
-**`.agent/config/notifications.yml`** — only if they provided Telegram details:
-```yaml
-telegram_bot_token: "their-token-here"
-telegram_chat_id: "their-chat-id-here"
-```
-
-**`.agent/memory-vault/preferences/user-profile.md`** — identity + communication style  
-**`.agent/memory-vault/preferences/user-priorities.md`** — goals and what they want from memory  
-**`.agent/memory-vault/preferences/user-interests.md`** — topics worth tracking
-
-Frontmatter template:
-```yaml
----
-type: memory
-slug: user-profile
-category: preferences
-title: "User Profile"
-status: active
-confidence: 1.0
-importance: 5
-created: <ISO timestamp>
-updated: <ISO timestamp>
-tags: [user, profile, onboarding]
----
-```
-
-Then mark this task `status: done` and confirm the profile was saved. Point them at the dashboard **Onboarding** page or `init → connect → remember → dream` if they prefer CLI-only.