@inetafrica/open-claudia 2.6.37 → 2.6.39

package/core/handlers.js

@@ -19,7 +19,8 @@ const { isChatAuthorized, isChatOwner, recordPendingAuthRequest, authRequestLabe
 const { isOnboarded, startOnboarding } = require("./onboarding");
 const { listProjects, findProject, projectKeyboard, workspacePath } = require("./projects");
 const { vault } = require("./vault-store");
-const { redactSensitive } = require("./redact");
+const keyring = require("./keyring");
+const { redactSensitive, registerSecrets } = require("./redact");
 const { runDoctorChecks, formatDoctorReport } = require("./doctor");
 const { isNewerVersion } = require("./version");
 const jobs = require("./jobs");
@@ -702,18 +703,18 @@ register({
     const active = recall.activeEngineName(settings);
     if (tail) {
       const v = tail.trim().toLowerCase();
-      if (v === "classic" || v === "default") settings.recallEngine = null;
+      if (v === "default" || v === recall.DEFAULT_ENGINE) settings.recallEngine = null;
       else if (recall.listEngines().includes(v)) settings.recallEngine = v;
       else return send(`Unknown engine "${v}". Options: ${recall.listEngines().join(", ")}.`);
       saveState();
-      return send(`Recall engine: ${settings.recallEngine || "classic (default)"}`);
+      return send(`Recall engine: ${recall.activeEngineName(settings)}${settings.recallEngine ? "" : " (default)"}`);
     }
     send(
       `Recall engine: ${active}${settings.recallEngine ? "" : " (default)"}\n\n` +
-      "• classic — keyword FTS + relevance judge (stable default)\n" +
-      "• discoverer — typed-edge graph + spreading activation + why-bullets (new, opt-in)",
+      "• discoverer — typed-edge graph + spreading activation + why-bullets (default)\n" +
+      "• classic — keyword FTS + relevance judge (opt-out fallback)",
       { keyboard: { inline_keyboard: [
-        [{ text: "Classic (default)", callback_data: "eng:classic" }, { text: "Discoverer", callback_data: "eng:discoverer" }],
+        [{ text: "Discoverer (default)", callback_data: "eng:discoverer" }, { text: "Classic", callback_data: "eng:classic" }],
       ] } },
     );
   },
@@ -965,8 +966,16 @@ register({
       setTimeout(() => killProcessTree(pid, "SIGKILL"), 3000);
       state.runningProcess = null;
       if (state.streamInterval) clearTimeout(state.streamInterval);
+      if (state.typingHeartbeat) { clearInterval(state.typingHeartbeat); state.typingHeartbeat = null; }
       state.messageQueue = [];
       await send("Cancelled.");
+    } else if (state.preparingRun) {
+      // Turn is mid-recall/compaction — no process to kill yet. Flag it so
+      // runClaude bails at its pre-spawn checkpoint, and stop typing now.
+      state.cancelRequested = true;
+      state.messageQueue = [];
+      if (state.typingHeartbeat) { clearInterval(state.typingHeartbeat); state.typingHeartbeat = null; }
+      await send("Cancelled.");
     } else await send("Nothing running.");
   },
 });
@@ -988,7 +997,7 @@ register({
     const { settings } = state;
     const backendLabel = settings.backend === "cursor" ? "Cursor Agent" : settings.backend === "codex" ? "Codex" : "Claude Code";
     const cronCount = jobs.listForChannel(env.adapter.id, env.channelId).filter((j) => j.kind === "cron").length;
-    const activeEngine = settings.recallEngine || "classic (default)";
+    const activeEngine = require("./recall").activeEngineName(settings) + (settings.recallEngine ? "" : " (default)");
     send([
       `Project: ${state.currentSession.name}`,
       `Backend: ${backendLabel}`,
@@ -1057,6 +1066,77 @@ register({
   },
 });
 
+register({
+  name: "lessons", description: "View/manage always-loaded learned rules", args: "[add <rule> | remove <id>]",
+  handler: async (env, { tail }) => {
+    if (!authorized(env)) return;
+    const lessonsLib = require("./lessons");
+    const trimmed = (tail || "").trim();
+    const [sub, ...restArr] = trimmed ? trimmed.split(/\s+/) : [];
+    const subCmd = (sub || "").toLowerCase();
+
+    if (subCmd === "add") {
+      const text = restArr.join(" ").trim();
+      if (!text) return send('Usage: /lessons add <rule>');
+      const r = lessonsLib.addLesson({ text, origin: "user" });
+      if (r.added) return send(`📌 Added lesson [${r.id}].${r.overCap ? ` That's ${r.count}, over the cap of ${lessonsLib.MAX_LESSONS} — the nightly dream will tidy.` : ""}`);
+      if (r.reinforced) return send(`Already knew that one — reinforced [${r.id}].`);
+      return send(`Couldn't add it: ${r.reason}.`);
+    }
+
+    if (subCmd === "remove" || subCmd === "rm") {
+      const key = restArr.join(" ").trim();
+      if (!key) return send("Usage: /lessons remove <id>");
+      return send(lessonsLib.removeLesson(key) ? `Removed ${key}.` : `No matching lesson: ${key}`);
+    }
+
+    const all = lessonsLib.listLessons();
+    if (all.length === 0) {
+      return send(`No lessons yet. These are cross-cutting rules I always load — I add them automatically when you correct me on something I should have known. Add one manually: /lessons add <rule>\n\nFile: ${lessonsLib.LESSONS_FILE}`);
+    }
+    const lines = all.map((l) => `📌 [${l.id}] ${l.text}${l.src ? `\n    src: ${l.src}` : ""}${l.reinforced ? ` · reinforced ${l.reinforced}×` : ""}`);
+    let msg = `Lessons I always load (${all.length}/${lessonsLib.MAX_LESSONS}):\n\n${lines.join("\n")}`;
+    msg += `\n\n/lessons add <rule> · /lessons remove <id>\nFile: ${lessonsLib.LESSONS_FILE}`;
+    return send(msg);
+  },
+});
+
+register({
+  name: "ideas", description: "View/manage the self-improvement backlog", args: "[add <idea> | remove <id>]",
+  handler: async (env, { tail }) => {
+    if (!authorized(env)) return;
+    const ideasLib = require("./ideas");
+    const trimmed = (tail || "").trim();
+    const [sub, ...restArr] = trimmed ? trimmed.split(/\s+/) : [];
+    const subCmd = (sub || "").toLowerCase();
+
+    if (subCmd === "add") {
+      const text = restArr.join(" ").trim();
+      if (!text) return send("Usage: /ideas add <idea>");
+      const r = ideasLib.addIdea({ text });
+      if (r.added) return send(`💡 Added idea [${r.id}] (now ${r.count}).`);
+      if (r.duplicate) return send(`Already had that one [${r.id}].`);
+      return send(`Couldn't add it: ${r.reason}.`);
+    }
+
+    if (subCmd === "remove" || subCmd === "rm") {
+      const key = restArr.join(" ").trim();
+      if (!key) return send("Usage: /ideas remove <id>");
+      return send(ideasLib.removeIdea(key) ? `Removed ${key}.` : `No matching idea: ${key}`);
+    }
+
+    const all = ideasLib.listIdeas();
+    if (all.length === 0) {
+      return send(`No ideas yet. The nightly dream jots self-improvement ideas here from the day's work. Add one manually: /ideas add <idea>\n\nFile: ${ideasLib.IDEAS_FILE}`);
+    }
+    const lines = all.slice(0, 30).map((i) => `💡 [${i.id}] ${i.date ? i.date + " " : ""}${i.scope ? "(" + i.scope + ") " : ""}${i.text}`);
+    let msg = `Ideas backlog (${all.length}/${ideasLib.MAX_IDEAS}):\n\n${lines.join("\n")}`;
+    if (all.length > 30) msg += `\n\n… and ${all.length - 30} more — see ${ideasLib.IDEAS_FILE}`;
+    msg += `\n\n/ideas add <idea> · /ideas remove <id>`;
+    return send(msg);
+  },
+});
+
 register({
   name: "dreamsummary", description: "Toggle the post-dream memory summary in chat", args: "[on|off]",
   handler: async (env, { tail }) => {
@@ -1135,7 +1215,8 @@ register({
       `The user typed /learn: capture the most recent substantial piece of work in this conversation as a reusable skill.${hint} ` +
       `Skills live in context packs (~/.open-claudia/packs/<dir>/PACK.md), NOT the legacy ~/.claude/skills dir. ` +
       `First check the already-injected packs and 'open-claudia pack list' for a pack this work belongs to; if one fits, fold the reusable how-to into that pack's Procedure section (exact commands in order, prerequisites, pitfalls) and append a dated Journal line — edit the PACK.md directly. ` +
-      `Only if no pack fits, create a new one: 'open-claudia pack' has no create subcommand, so write ~/.open-claudia/packs/<kebab-name>/PACK.md following the four-section format (Stance, Procedure, State, Journal) with name + a when-to-use description in the frontmatter. ` +
+      `Only if no pack fits, create a new one: 'open-claudia pack' has no create subcommand, so write ~/.open-claudia/packs/<kebab-name>/PACK.md following the four-section format (Stance, Procedure, State, Journal) with name + a when-to-use description in the frontmatter. Give it an ACTIVITY-oriented name and description (what you DO — the verbs, tools, and artifacts) so it is findable from other projects by the work being done, not by a project name; and if this how-to came from a specific project, add a 'learned_on: <project-pack-dir>' frontmatter line so its cross-project reuse can be tracked. ` +
+      `Then mark that pack as a reusable skill so it is always surfaced in future conversations: run 'open-claudia pack skill <dir> on'. This flags it as a reusable ability and adds it to the always-on skill index (name + description); the Procedure still loads on demand. ` +
       `No secrets or tokens. When done, reply with one short line naming the pack you created or updated and what it covers. ` +
       `If the recent work is genuinely not reusable, say so instead of forcing a skill.`;
     await runClaude(prompt, currentState().currentSession.dir, env.messageId);
@@ -1406,6 +1487,54 @@ register({
 
 module.exports.PENDING_VAULT_TTL_MS = PENDING_VAULT_TTL_MS;
 
+// ── Keyring (operational, plaintext) ───────────────────────────────
+// Unlike the vault, the keyring is always available to the agent (no
+// password, no lock) so it can repeat work you've shown it once. Use it for
+// creds the agent is allowed to use unattended; use /vault for personal
+// secrets it must not. Values are injected into the agent's env each turn.
+
+register({
+  name: "keyring", description: "Manage operational credentials (plaintext, agent-usable)", args: "[set|get|remove] ...",
+  handler: async (env, { tail }) => {
+    if (!authorized(env)) return;
+
+    if (!tail) {
+      const entries = keyring.list();
+      const names = Object.keys(entries);
+      if (names.length === 0) {
+        return send("Keyring is empty.\n\nStore a credential the agent can reuse:\n/keyring set <name> <value>\n\n(For personal secrets the agent should NOT use on its own, use /vault instead.)");
+      }
+      return send("Keyring (available to the agent as env vars):\n\n" + names.map((k) => `${k}: ${entries[k]}`).join("\n") + "\n\nGet a value: /keyring get <name>");
+    }
+
+    const setMatch = tail.match(/^set\s+(\S+)\s+([\s\S]+)$/);
+    if (setMatch) {
+      await deleteMessage(env.messageId);
+      if (!ownerEnv(env)) return send("Owner only.");
+      const value = setMatch[2].trim();
+      keyring.set(setMatch[1], value);
+      registerSecrets([value]);
+      return send(`Stored ${setMatch[1]}. I deleted your message. It's available to the agent from the next turn.`);
+    }
+
+    const getMatch = tail.match(/^get\s+(\S+)$/);
+    if (getMatch) {
+      if (!ownerEnv(env)) return send("Owner only.");
+      const value = keyring.get(getMatch[1]);
+      if (value === null) return send(`No such key: ${getMatch[1]}`);
+      return send(`${getMatch[1]}: ${value}\n\n(Plaintext — delete this message when done.)`);
+    }
+
+    const removeMatch = tail.match(/^remove\s+(\S+)$/);
+    if (removeMatch) {
+      if (!ownerEnv(env)) return send("Owner only.");
+      return send(keyring.remove(removeMatch[1]) ? `Removed ${removeMatch[1]}.` : `No such key: ${removeMatch[1]}`);
+    }
+
+    send("Usage: /keyring | /keyring set <name> <value> | /keyring get <name> | /keyring remove <name>");
+  },
+});
+
 // ── Cron ───────────────────────────────────────────────────────────
 
 register({

package/core/ideas.js

@@ -0,0 +1,114 @@
+// ideas.md — a self-improvement backlog. While the nightly dream reviews the
+// day's seeds and introspects on its own current self, it jots ideas here:
+// things that could improve Open Claudia itself, or follow-ups for the work
+// done that day. Unlike LESSONS (binding rules, always injected) ideas are
+// suggestions — a backlog the user and future dreams can act on. So ideas are
+// NOT injected into every turn; they surface via /ideas and the dream summary.
+//
+// Newest first. User-editable (/ideas or the file directly). No secrets.
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const CONFIG_DIR = require("../config-dir");
+const { dayStamp } = require("./day-seeds");
+
+const IDEAS_FILE = process.env.IDEAS_FILE ? path.resolve(process.env.IDEAS_FILE) : path.join(CONFIG_DIR, "ideas.md");
+const MAX_IDEAS = Number(process.env.IDEAS_MAX || 100);
+const MAX_IDEA_CHARS = Number(process.env.IDEA_MAX_CHARS || 400);
+
+const FILE_HEADER = `Ideas — self-improvement backlog.
+Captured by the nightly dream from the day's work, plus anything you add. One idea per bullet.
+Not binding (those are lessons); these are suggestions to act on later. Scope tag: (oc) = Open Claudia itself, (work) = the projects we work on. Edit or prune freely.
+`;
+
+function normalize(t) { return String(t || "").toLowerCase().replace(/\s+/g, " ").trim(); }
+function ideaId(t) { return crypto.createHash("sha1").update(normalize(t)).digest("hex").slice(0, 8); }
+
+// Parse "- [YYYY-MM-DD] (scope) text" bullets; date + scope optional so
+// hand-added bullets still parse. Dedupe by normalized text.
+function parseIdeas(raw) {
+  const out = [];
+  const seen = new Set();
+  for (const line of String(raw || "").split("\n")) {
+    const m = line.match(/^\s*[-*]\s+(.*\S)\s*$/);
+    if (!m) continue;
+    let full = m[1].trim();
+    let date = "", scope = "";
+    const dm = full.match(/^\[(\d{4}-\d{2}-\d{2})\]\s*/);
+    if (dm) { date = dm[1]; full = full.slice(dm[0].length); }
+    const sm = full.match(/^\(([\w-]+)\)\s*/);
+    if (sm) { scope = sm[1].toLowerCase(); full = full.slice(sm[0].length); }
+    const text = full.trim();
+    if (!text) continue;
+    const id = ideaId(text);
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push({ id, date, scope, text });
+  }
+  return out;
+}
+
+function readIdeas() {
+  try { return parseIdeas(fs.readFileSync(IDEAS_FILE, "utf-8")); }
+  catch (e) { return []; }
+}
+
+function ideaLine(i) {
+  const parts = [];
+  if (i.date) parts.push(`[${i.date}]`);
+  if (i.scope) parts.push(`(${i.scope})`);
+  parts.push(i.text);
+  return `- ${parts.join(" ")}`;
+}
+
+function writeIdeas(ideas) {
+  const body = ideas.map(ideaLine).join("\n");
+  const content = FILE_HEADER + "\n" + body + (body ? "\n" : "");
+  fs.mkdirSync(path.dirname(IDEAS_FILE), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(IDEAS_FILE, content, { mode: 0o600 });
+  return IDEAS_FILE;
+}
+
+// File order is the source of truth; we keep newest-first on write.
+function listIdeas() { return readIdeas(); }
+
+function addIdea({ text, scope = "", date = "" } = {}) {
+  const body = String(text || "").trim();
+  if (!body) return { added: false, reason: "empty" };
+  if (body.length > MAX_IDEA_CHARS) return { added: false, reason: `too long (>${MAX_IDEA_CHARS} chars)` };
+  const ideas = readIdeas();
+  const id = ideaId(body);
+  if (ideas.some((i) => i.id === id)) return { added: false, duplicate: true, id };
+  ideas.unshift({ id, date: date || dayStamp(), scope: String(scope || "").toLowerCase(), text: body });
+  const trimmed = ideas.slice(0, MAX_IDEAS); // cap: keep newest
+  writeIdeas(trimmed);
+  return { added: true, id, count: trimmed.length, dropped: ideas.length - trimmed.length };
+}
+
+function removeIdea(idOrText) {
+  const key = String(idOrText || "").trim();
+  if (!key) return false;
+  const ideas = readIdeas();
+  const id = ideas.some((i) => i.id === key) ? key : ideaId(key);
+  const next = ideas.filter((i) => i.id !== id);
+  if (next.length === ideas.length) return false;
+  writeIdeas(next);
+  return true;
+}
+
+function saveIdeasRaw(raw) {
+  const text = String(raw || "");
+  if (text.length > MAX_IDEA_CHARS * MAX_IDEAS * 2) throw new Error(`ideas file too large (${text.length} chars); trim it`);
+  fs.mkdirSync(path.dirname(IDEAS_FILE), { recursive: true, mode: 0o700 });
+  writeIdeas(parseIdeas(text)); // canonicalize through the parser
+  return IDEAS_FILE;
+}
+
+function ideasExist() { return readIdeas().length > 0; }
+
+module.exports = {
+  IDEAS_FILE, MAX_IDEAS, MAX_IDEA_CHARS,
+  normalize, ideaId, parseIdeas,
+  readIdeas, listIdeas, addIdea, removeIdea, saveIdeasRaw, ideasExist,
+};

package/core/keyring.js

@@ -0,0 +1,79 @@
+// Operational keyring: a plaintext, permissioned credential store for the
+// agent's day-to-day work — the API keys, base URLs, account IDs and tokens
+// it needs to *repeat* a task you've already shown it once.
+//
+// Why plaintext (and not the vault)? The vault (vault.js) uses real AES-GCM
+// crypto because it holds personal secrets the bot must NOT use unattended —
+// it stays locked until you type a password, and clears on restart. That is
+// exactly the wrong shape for operational creds: the agent needs them
+// available every turn, with no human in the loop. An encrypted store whose
+// key lives on the same box would only be obfuscation, not security. So the
+// honest model here is "a managed .env": the protection is filesystem perms
+// (chmod 600) + log redaction, not encryption. Keep genuine personal secrets
+// in the vault; keep "creds the agent is allowed to use on its own" here.
+//
+// Values set here flow to every agent subprocess via botSubprocessEnv()
+// (config.js), so a credential stored once is present as an env var on the
+// next turn — no restart needed.
+
+const fs = require("fs");
+const path = require("path");
+const CONFIG_DIR = require("../config-dir");
+
+const KEYRING_FILE = process.env.KEYRING_FILE || path.join(CONFIG_DIR, "keyring.json");
+
+function load() {
+  try {
+    const data = JSON.parse(fs.readFileSync(KEYRING_FILE, "utf-8"));
+    return data && typeof data === "object" ? data : {};
+  } catch (e) {
+    return {}; // missing or corrupt → empty keyring
+  }
+}
+
+function save(data) {
+  fs.writeFileSync(KEYRING_FILE, JSON.stringify(data, null, 2) + "\n");
+  try { fs.chmodSync(KEYRING_FILE, 0o600); } catch (e) { /* best effort on odd filesystems */ }
+}
+
+// Full {key: value} map — used to inject creds into subprocess env.
+function all() {
+  return load();
+}
+
+function keys() {
+  return Object.keys(load());
+}
+
+function get(key) {
+  const v = load()[key];
+  return v === undefined ? null : v;
+}
+
+function set(key, value) {
+  const data = load();
+  data[String(key)] = String(value);
+  save(data);
+  return true;
+}
+
+function remove(key) {
+  const data = load();
+  if (!(key in data)) return false;
+  delete data[key];
+  save(data);
+  return true;
+}
+
+// Masked view for display — last 4 chars only.
+function list() {
+  const data = load();
+  const out = {};
+  for (const [k, v] of Object.entries(data)) {
+    const s = String(v);
+    out[k] = s.length >= 4 ? "****" + s.slice(-4) : "****";
+  }
+  return out;
+}
+
+module.exports = { KEYRING_FILE, load, all, keys, get, set, remove, list };

package/core/lessons.js

@@ -0,0 +1,276 @@
+// Lessons tier. The soul holds identity + hard rules (user-owned); the
+// persona holds voice (Open-Claudia-owned). Lessons are the third
+// always-injected layer: a small, bounded set of cross-cutting rules that
+// Open Claudia got WRONG before and was corrected on.
+//
+// Why this exists: every other piece of learned knowledge (pack Stances,
+// entity Notes) is topic-gated — it only loads when the incoming message
+// FTS-matches its tags. That fails precisely when a fact is relevant on an
+// off-topic turn (e.g. the Kazee mobile-deploy mechanism coming up during
+// an hr-hub deploy conversation), and recall keys on the USER's text, not
+// the assistant's own wrong output. So a fact can be perfectly stored and
+// still never surface at the moment it's needed. Lessons fix that by being
+// ALWAYS loaded, like soul and persona.
+//
+// To keep the always-on budget tiny and high-signal, a rule only graduates
+// here after a MISS: the per-turn reviewer (pack-review.js) sees the user
+// correct the assistant or repeat a known fact — proof topic-matching
+// failed for it — and promotes a one-line lesson. Each lesson keeps a
+// "(src: <pack-dir>)" pointer to the pack that holds the full context. The
+// nightly dream dedupes, demotes lessons safely captured in their source
+// pack when over cap, and enforces the count. Lessons are user-editable
+// (/lessons, or the file directly) and never store secrets.
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const CONFIG_DIR = require("../config-dir");
+const LESSONS_FILE = process.env.LESSONS_FILE ? path.resolve(process.env.LESSONS_FILE) : path.join(CONFIG_DIR, "lessons.md");
+const LESSONS_META_FILE = path.join(path.dirname(LESSONS_FILE), "lessons.meta.json");
+
+// Count cap is the primary bound (dream enforces it with judgment); the
+// char budget is the hard safety net on what actually gets injected.
+const MAX_LESSONS = Number(process.env.LESSONS_MAX || 20);
+const MAX_LESSON_CHARS = Number(process.env.LESSON_MAX_CHARS || 240);  // per lesson
+const MAX_LESSONS_CHARS = Number(process.env.LESSONS_MAX_CHARS || 3500); // total injected block
+
+const FILE_HEADER = `Lessons learned — always loaded into every conversation.
+One rule per bullet: cross-cutting things I got wrong before and was corrected on.
+Edit freely; keep each to a single line. Optional "(src: <pack-dir>)" points to the pack with the full context.
+`;
+
+// ── parsing ─────────────────────────────────────────────────────────
+
+// Strip the "(src: ...)" pointer so the id is stable across src changes.
+function stripSrc(text) {
+  return String(text || "").replace(/\s*\(src:\s*[^)]*\)\s*$/i, "").trim();
+}
+
+function srcOf(text) {
+  const m = String(text || "").match(/\(src:\s*([^)]+)\)\s*$/i);
+  return m ? m[1].trim() : "";
+}
+
+function normalize(text) {
+  return stripSrc(text).toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+function lessonId(text) {
+  return crypto.createHash("sha1").update(normalize(text)).digest("hex").slice(0, 8);
+}
+
+// Parse only top-level "- " bullets; everything else (header lines, blank
+// lines, the user's decorative text) is ignored. Robust to hand-edits.
+function parseLessons(raw) {
+  const out = [];
+  const seen = new Set();
+  for (const line of String(raw || "").split("\n")) {
+    const m = line.match(/^\s*[-*]\s+(.*\S)\s*$/);
+    if (!m) continue;
+    const full = m[1].trim();
+    const body = stripSrc(full);
+    if (!body) continue;
+    const id = lessonId(full);
+    if (seen.has(id)) continue; // dedupe identical lessons
+    seen.add(id);
+    out.push({ id, text: body, src: srcOf(full) });
+  }
+  return out;
+}
+
+function readLessons() {
+  try { return parseLessons(fs.readFileSync(LESSONS_FILE, "utf-8")); }
+  catch (e) { return []; }
+}
+
+// ── meta sidecar (lifecycle: origin / created / reinforced / src) ────
+
+function readMeta() {
+  try { return JSON.parse(fs.readFileSync(LESSONS_META_FILE, "utf-8")) || {}; }
+  catch (e) { return {}; }
+}
+
+function writeMeta(meta) {
+  fs.mkdirSync(path.dirname(LESSONS_META_FILE), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(LESSONS_META_FILE, JSON.stringify(meta, null, 2) + "\n", { mode: 0o600 });
+}
+
+// Self-heal: drop meta for lessons that no longer exist, seed defaults for
+// lessons that have none (e.g. hand-added by the user). Idempotent.
+function reconcileMeta(lessons) {
+  lessons = lessons || readLessons();
+  const meta = readMeta();
+  const now = new Date().toISOString();
+  const next = {};
+  let changed = false;
+  for (const l of lessons) {
+    if (meta[l.id]) {
+      next[l.id] = meta[l.id];
+      if (l.src && next[l.id].src !== l.src) { next[l.id].src = l.src; changed = true; }
+    } else {
+      next[l.id] = { origin: "user", created: now, reinforced: 0, reinforcedAt: null, src: l.src || "" };
+      changed = true;
+    }
+  }
+  if (Object.keys(meta).length !== Object.keys(next).length) changed = true;
+  if (changed) writeMeta(next);
+  return next;
+}
+
+// ── serialization ───────────────────────────────────────────────────
+
+function lessonLine(l) {
+  return l.src ? `- ${l.text} (src: ${l.src})` : `- ${l.text}`;
+}
+
+function writeLessons(lessons) {
+  const body = lessons.map(lessonLine).join("\n");
+  const content = FILE_HEADER + "\n" + body + (body ? "\n" : "");
+  fs.mkdirSync(path.dirname(LESSONS_FILE), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(LESSONS_FILE, content, { mode: 0o600 });
+  return LESSONS_FILE;
+}
+
+// ── public API ──────────────────────────────────────────────────────
+
+// Structured list merged with meta, newest first by created.
+function listLessons() {
+  const lessons = readLessons();
+  const meta = reconcileMeta(lessons);
+  return lessons
+    .map((l) => ({ ...l, ...(meta[l.id] || {}) }))
+    .sort((a, b) => String(b.created || "").localeCompare(String(a.created || "")));
+}
+
+// The always-injected block. Highest-priority lessons (most reinforced,
+// then most recently reinforced) survive the char budget. Returns "" when
+// there are none, so the system prompt stays clean on a fresh install.
+function loadLessonsBlock() {
+  const lessons = readLessons();
+  if (lessons.length === 0) return "";
+  const meta = reconcileMeta(lessons);
+  const ranked = lessons.slice().sort((a, b) => {
+    const ma = meta[a.id] || {}, mb = meta[b.id] || {};
+    return (mb.reinforced || 0) - (ma.reinforced || 0)
+      || String(mb.reinforcedAt || "").localeCompare(String(ma.reinforcedAt || ""))
+      || String(mb.created || "").localeCompare(String(ma.created || ""));
+  });
+  const out = [];
+  let used = 0;
+  for (const l of ranked) {
+    const line = lessonLine(l);
+    if (used + line.length + 1 > MAX_LESSONS_CHARS) break;
+    out.push(line);
+    used += line.length + 1;
+  }
+  if (out.length === 0) return "";
+  return out.join("\n");
+}
+
+// Add or reinforce a lesson. Dedupe is by normalized text (id), so the same
+// fact phrased the same way reinforces instead of duplicating. No eviction
+// here — the char budget bounds injection and dream enforces the count cap
+// with judgment, so a hard-won lesson is never silently dropped on add.
+function addLesson({ text, src = "", origin = "reviewer" } = {}) {
+  const body = stripSrc(text);
+  if (!body) return { added: false, reason: "empty" };
+  if (body.length > MAX_LESSON_CHARS) return { added: false, reason: `too long (>${MAX_LESSON_CHARS} chars)` };
+
+  const lessons = readLessons();
+  const id = lessonId(body);
+  const meta = reconcileMeta(lessons);
+  const now = new Date().toISOString();
+  const existing = lessons.find((l) => l.id === id);
+
+  if (existing) {
+    if (src && !existing.src) { existing.src = src; writeLessons(lessons); }
+    const m = meta[id] || { origin, created: now, reinforced: 0, src };
+    m.reinforced = (m.reinforced || 0) + 1;
+    m.reinforcedAt = now;
+    if (src && !m.src) m.src = src;
+    meta[id] = m;
+    writeMeta(meta);
+    return { added: false, reinforced: true, id, count: lessons.length };
+  }
+
+  lessons.push({ id, text: body, src });
+  writeLessons(lessons);
+  meta[id] = { origin, created: now, reinforced: 0, reinforcedAt: null, src };
+  writeMeta(meta);
+  const count = lessons.length;
+  return { added: true, id, count, overCap: count > MAX_LESSONS };
+}
+
+// Rewrite a lesson's text in place, preserving its meta (reinforced count,
+// created, origin). Used by the dream to tighten/merge wording. If the new
+// text collides with another existing lesson, the old one is dropped (the
+// survivor keeps its own meta).
+function editLesson(idOrText, newText, { src } = {}) {
+  const body = stripSrc(newText);
+  if (!body) return { ok: false, reason: "empty" };
+  if (body.length > MAX_LESSON_CHARS) return { ok: false, reason: `too long (>${MAX_LESSON_CHARS})` };
+  const arr = readLessons();
+  const oldId = arr.some((l) => l.id === idOrText) ? idOrText : lessonId(idOrText);
+  const idx = arr.findIndex((l) => l.id === oldId);
+  if (idx === -1) return { ok: false, reason: "not found" };
+  const old = arr[idx];
+  const newId = lessonId(body);
+  const meta = readMeta();
+  if (newId !== oldId && arr.some((l) => l.id === newId)) {
+    arr.splice(idx, 1);            // merge into the existing twin
+    writeLessons(arr);
+    delete meta[oldId];
+    writeMeta(meta);
+    return { ok: true, merged: true, id: newId };
+  }
+  arr[idx] = { id: newId, text: body, src: src != null ? src : old.src };
+  writeLessons(arr);
+  const m = meta[oldId] || { origin: "user", created: new Date().toISOString(), reinforced: 0, reinforcedAt: null, src: old.src };
+  if (oldId !== newId) delete meta[oldId];
+  if (src != null) m.src = src;
+  meta[newId] = m;
+  writeMeta(meta);
+  return { ok: true, id: newId };
+}
+
+function removeLesson(idOrText) {
+  const key = String(idOrText || "").trim();
+  if (!key) return false;
+  const lessons = readLessons();
+  const id = lessons.some((l) => l.id === key) ? key : lessonId(key);
+  const next = lessons.filter((l) => l.id !== id);
+  if (next.length === lessons.length) return false;
+  writeLessons(next);
+  const meta = readMeta();
+  delete meta[id];
+  writeMeta(meta);
+  return true;
+}
+
+// Overwrite from raw text (the /lessons edit path and manual edits). Bounds
+// the total size, then reconciles meta to the new contents.
+function saveLessonsRaw(raw) {
+  const text = String(raw || "");
+  if (text.length > MAX_LESSONS_CHARS * 3) {
+    throw new Error(`lessons file too large (${text.length} chars); trim it`);
+  }
+  fs.mkdirSync(path.dirname(LESSONS_FILE), { recursive: true, mode: 0o700 });
+  // Re-serialize through the parser so the stored form is canonical.
+  writeLessons(parseLessons(text));
+  reconcileMeta();
+  return LESSONS_FILE;
+}
+
+function lessonsExist() {
+  return readLessons().length > 0;
+}
+
+module.exports = {
+  LESSONS_FILE, LESSONS_META_FILE,
+  MAX_LESSONS, MAX_LESSON_CHARS, MAX_LESSONS_CHARS,
+  normalize, lessonId, parseLessons,
+  readLessons, listLessons, loadLessonsBlock,
+  readMeta, writeMeta, reconcileMeta,
+  addLesson, editLesson, removeLesson, saveLessonsRaw, lessonsExist,
+};