@inetafrica/open-claudia 2.6.37 → 2.6.39

package/core/dream.js

@@ -14,9 +14,12 @@ const path = require("path");
 const cron = require("node-cron");
 
 const CONFIG_DIR = require("../config-dir");
-const { config } = require("./config");
+const { config, DEFAULT_CLAUDE_MODEL } = require("./config");
 const packs = require("./packs");
 const entities = require("./entities");
+const lessons = require("./lessons");
+const ideas = require("./ideas");
+const daySeeds = require("./day-seeds");
 const packGuard = require("./pack-guard");
 const persona = require("./persona");
 const { spawnSubagent } = require("./subagent");
@@ -31,13 +34,26 @@ function pickDreamModel() {
   const tier = String(process.env.DREAM_TIER || "high").toLowerCase();
   if (tier === "low") return "haiku";
   if (tier === "medium") return "sonnet";
-  return "opus";
+  return DEFAULT_CLAUDE_MODEL; // high → the bot's top model (opus 4.8); tracks future upgrades
 }
 const DREAM_MODEL = pickDreamModel();
+// The dream is the foundation of long-term memory quality, so it runs at max
+// reasoning effort by default. Overridable via DREAM_EFFORT (low|medium|high|xhigh|max).
+const DREAM_EFFORT = process.env.DREAM_EFFORT || "max";
 const DREAM_CRON = process.env.DREAM_CRON || "0 4 * * *";
 const MAX_PACK_CHARS = 2500;
 const MAX_ENTITY_CHARS = 900;
-const LIMITS = { merges: 3, umbrellas: 2, parents: 8, retag: 8, entity_merges: 3, entity_notes: 4, archive: 5 };
+const LIMITS = {
+  merges: 3, umbrellas: 2, parents: 8, retag: 8, entity_merges: 3, entity_notes: 4, archive: 5, lessons: 6,
+  // introspection phase (self-improvement) caps
+  lessons_add: 4, doc_edits: 5, entity_edits: 4, ideas: 8,
+  // ability tier management (deterministic, reuse-breadth based)
+  promote: 3, demote: 3,
+};
+
+// An ability that has demonstrably transferred to at least this many distinct
+// projects (via applied_on) has earned an always-on slot.
+const PROMOTE_MIN_PROJECTS = Number(process.env.DREAM_PROMOTE_MIN_PROJECTS || 3);
 
 // Retirement guard: even if the model proposes archiving, only act when a pack
 // is genuinely cold — old enough, idle long enough, and rarely used. Protects
@@ -60,6 +76,22 @@ function summaryEnabled() {
   return String(v).toLowerCase() !== "off";
 }
 
+// The self-improvement introspection phase (reviews the day's seeds, reads its
+// own code read-only, mines missed corrections into lessons, captures ideas).
+function introspectEnabled() {
+  const v = process.env.DREAM_INTROSPECT ?? config.DREAM_INTROSPECT ?? "on";
+  return String(v).toLowerCase() !== "off";
+}
+
+// Whether introspection auto-applies its memory-doc changes (default) or only
+// proposes them in the report for morning approval (DREAM_SELF_APPLY=off).
+// Either way it NEVER touches soul.md or code — that boundary is structural
+// (read-only tools) and not configurable.
+function selfApplyEnabled() {
+  const v = process.env.DREAM_SELF_APPLY ?? config.DREAM_SELF_APPLY ?? "on";
+  return String(v).toLowerCase() !== "off";
+}
+
 function clip(s, n) {
   const t = String(s || "");
   return t.length > n ? t.slice(0, n) + "\n…[truncated]" : t;
@@ -70,7 +102,7 @@ function buildDreamPrompt() {
   const allEntities = entities.listEntities();
 
   const packDump = allPacks.map((p) => clip([
-    `=== pack: ${p.dir}${p.parent ? ` (parent: ${p.parent})` : ""}`,
+    `=== pack: ${p.dir}${p.parent ? ` (parent: ${p.parent})` : ""}${p.kind === "ability" ? " [ABILITY]" : ""}`,
     `name: ${p.name}`,
     `description: ${p.description}`,
     `tags: ${p.tags.join(", ")}`,
@@ -88,7 +120,12 @@ function buildDreamPrompt() {
     `Log:\n${e.sections.Log}`,
   ].join("\n"), MAX_ENTITY_CHARS)).join("\n\n") || "(none)";
 
-  return `You are the dream pass of a personal AI assistant called Open Claudia — the overnight consolidation of her long-term memory. Below is her entire memory: context packs (living topic documents) and entity notes (people/places/projects/orgs/systems), plus her current persona.
+  const allLessons = lessons.listLessons();
+  const lessonDump = allLessons.map((l) =>
+    `- [${l.id}] "${l.text}"${l.src ? ` (src: ${l.src})` : ""} — reinforced ${l.reinforced || 0}×, since ${(l.created || "").slice(0, 10)}, origin ${l.origin || "user"}`
+  ).join("\n") || "(none)";
+
+  return `You are the dream pass of a personal AI assistant called Open Claudia — the overnight consolidation of her long-term memory. Below is her entire memory: context packs (living topic documents), entity notes (people/places/projects/orgs/systems), and her always-loaded lessons, plus her current persona.
 
 Today: ${new Date().toISOString().slice(0, 10)}
 
@@ -100,26 +137,31 @@ ENTITIES:
 
 ${entityDump}
 
+ALWAYS-LOADED LESSONS (cap ${lessons.MAX_LESSONS}; these inject on EVERY turn, so they must stay few and sharp):
+
+${lessonDump}
+
 CURRENT PERSONA:
 
 ${persona.loadPersona()}
 
 Your job — decide what consolidation, if any, is warranted:
 
-1. merges: packs that are clearly the SAME topic under different names get merged into one. Supply the merged Stance/Procedure/State (synthesised, not concatenated; null leaves the target's section alone) and a one-sentence journal note. Be conservative: when in doubt, do not merge. A Stance marked USER-AUTHORED is off-limits — leave its stance null; the system preserves it verbatim regardless.
+1. merges: packs that are clearly the SAME topic under different names get merged into one. Supply the merged Stance/Procedure/State (synthesised, not concatenated; null leaves the target's section alone) and a one-sentence journal note. Be conservative: when in doubt, do not merge. A Stance marked USER-AUTHORED is off-limits — leave its stance null; the system preserves it verbatim regardless. Packs marked [ABILITY] are reusable cross-project how-tos, NOT project trackers: only ever merge an [ABILITY] into another [ABILITY] (the merged result must stay an ability), and never merge a project pack into an [ABILITY] or an [ABILITY] into a project pack — that would lose the reusable how-to or pollute it with one project's specifics.
 2. umbrellas: when 3+ packs are siblings under one theme, create an umbrella pack whose State is a 3-6 line map of the family ("for X see pack Y"), and list its children. The umbrella is a router, not a duplicate.
 3. parents: assign an existing pack as parent of another (sub-topic relationship) without creating anything.
 4. retag: tighten descriptions and tags. The router FTS-matches incoming messages against name/description/tags, so generic words there cause false matches. Descriptions should be one specific line; tags specific nouns.
 5. entity_merges: the same real-world entity recorded twice gets merged (the better slug wins).
 6. entity_notes: rewrite an entity's Notes to be current and cross-linked — mention related packs as [[pack-dir]] and related entities by name.
 7. archive: retire packs that have gone cold — long unused AND rarely used over their life (consult last_used and the usage count). Archiving moves a pack out of the live index (reversibly, backed up) so it stops adding recall noise. ONLY propose packs idle ≥${ARCHIVE_IDLE_DAYS} days and used ≤${ARCHIVE_MAX_USAGE}× total; never an umbrella/parent pack that still has children; when in doubt, leave it. Give a one-line reason.
-8. persona: evolve the persona GENTLY — keep its structure and length (under 2200 chars), adjust only what recent work justifies (a new habit, a sharpened quirk). Most dreams should return null here.
-9. report: a short chat message to the owner, written AS Open Claudia in first person — warm, a little playful, a few emojis, mobile-friendly (2-6 short lines). Say what you tidied and why it helps. If you changed nothing, say the memory is in good shape, charmingly.
+8. lessons: keep the always-loaded lessons few and sharp — they cost context on EVERY turn. dedupe near-identical lessons (op "remove" the weaker, keep the better wording; or op "edit" to merge two into one tight line); tighten a clumsy lesson with op "edit". If the count exceeds the cap of ${lessons.MAX_LESSONS}, demote the weakest down to the cap — prefer lessons that are low-reinforced AND whose fact is safely captured in the pack named in their (src) (they will still surface by topic-match), and NEVER remove a frequently-reinforced lesson (those are actively preventing a repeat mistake). Even under the cap you may remove a lesson clearly redundant with its source pack that has stayed at 0 reinforcements for a long time, but be conservative — when in doubt, keep it. Reference lessons by their exact current text.
+9. persona: evolve the persona GENTLY — keep its structure and length (under 2200 chars), adjust only what recent work justifies (a new habit, a sharpened quirk). Most dreams should return null here.
+10. report: a short chat message to the owner, written AS Open Claudia in first person — warm, a little playful, a few emojis, mobile-friendly (2-6 short lines). Say what you tidied and why it helps. If you changed nothing, say the memory is in good shape, charmingly.
 
 Hard rules:
 - Never invent packs/entities not listed above; reference them by exact dir/slug.
 - Never store secrets, tokens, passwords, or credentials anywhere.
-- Limits: ≤${LIMITS.merges} merges, ≤${LIMITS.umbrellas} umbrellas, ≤${LIMITS.parents} parents, ≤${LIMITS.retag} retags, ≤${LIMITS.entity_merges} entity merges, ≤${LIMITS.entity_notes} entity note rewrites, ≤${LIMITS.archive} archives.
+- Limits: ≤${LIMITS.merges} merges, ≤${LIMITS.umbrellas} umbrellas, ≤${LIMITS.parents} parents, ≤${LIMITS.retag} retags, ≤${LIMITS.entity_merges} entity merges, ≤${LIMITS.entity_notes} entity note rewrites, ≤${LIMITS.archive} archives, ≤${LIMITS.lessons} lesson ops.
 - An empty decision is a perfectly good decision.
 
 Reply with ONLY a JSON object, no prose, no code fences:
@@ -130,8 +172,10 @@ Reply with ONLY a JSON object, no prose, no code fences:
  "entity_merges": [{"into": "<slug>", "from": ["<slug>"], "notes": "<merged Notes or null>"}],
  "entity_notes": [{"entity": "<slug>", "notes": "<rewritten Notes>"}],
  "archive": [{"pack": "<dir>", "reason": "<one line: why it's cold>"}],
+ "lessons": [{"op": "remove", "text": "<exact current lesson text>", "reason": "<duplicate of … / safely in pack … / cold>"}],
  "persona": null,
- "report": "<chat message>"}`;
+ "report": "<chat message>"}
+(a lesson "edit" looks like {"op": "edit", "text": "<exact current lesson text>", "to": "<tightened wording>"})`;
 }
 
 function parseDream(text) {
@@ -150,6 +194,7 @@ function parseDream(text) {
       entity_merges: arr("entity_merges"),
       entity_notes: arr("entity_notes"),
       archive: arr("archive"),
+      lessons: arr("lessons"),
       persona: typeof obj.persona === "string" ? obj.persona : null,
       report: typeof obj.report === "string" ? obj.report.trim() : "",
     };
@@ -173,6 +218,14 @@ function backupEntity(slug, root) {
   fs.copyFileSync(path.join(entities.ENTITIES_DIR, slug + ".md"), path.join(dest, slug + ".md"));
 }
 
+function backupLessons(root) {
+  const dest = path.join(root, "lessons");
+  fs.mkdirSync(dest, { recursive: true, mode: 0o700 });
+  for (const f of [lessons.LESSONS_FILE, lessons.LESSONS_META_FILE]) {
+    try { if (fs.existsSync(f)) fs.copyFileSync(f, path.join(dest, path.basename(f))); } catch (e) {}
+  }
+}
+
 function wouldCycle(packDir, parentDir) {
   let cur = parentDir;
   for (let i = 0; i < 10 && cur; i++) {
@@ -182,6 +235,42 @@ function wouldCycle(packDir, parentDir) {
   return false;
 }
 
+// Ability tier management — deterministic, by reuse breadth (no model call).
+// An ability that has transferred across several distinct projects (applied_on)
+// graduates to the always-on skill index; a once-promoted ability that never
+// spread and has gone cold eases back to the match-gated pool (still an ability,
+// just not injected every turn). Both are announced and reversible. `gone` is
+// the set of dirs already removed this run (skip those). Returns chat lines.
+function manageAbilityTiers(gone = new Set()) {
+  const lines = [];
+  let allPacks, abilities;
+  try { allPacks = packs.listPacks(); abilities = packs.listAbilities(); }
+  catch (e) { return lines; }
+  let promoted = 0, demoted = 0;
+  for (const ab of abilities) {
+    try {
+      if (gone.has(ab.dir)) continue;
+      const reach = (ab.applied_on || []).length;
+      if (!ab.skill && reach >= PROMOTE_MIN_PROJECTS && promoted < LIMITS.promote) {
+        packs.setSkill(ab.dir, true);
+        promoted++;
+        lines.push(`🧩 Promoted "${ab.name}" to always-on — reused across ${reach} projects (${(ab.applied_on || []).join(", ")}).`);
+      } else if (ab.skill && reach <= 1 && demoted < LIMITS.demote) {
+        if (allPacks.some((p) => p.parent === ab.dir)) continue; // never demote an umbrella with children
+        const ageDays = ab.created ? (Date.now() - Date.parse(ab.created)) / 86400000 : Infinity;
+        const idleDays = ab.last_used ? (Date.now() - Date.parse(ab.last_used)) / 86400000 : ageDays;
+        const uses = Number(ab.usage_count) || 0;
+        if (ageDays >= ARCHIVE_IDLE_DAYS && idleDays >= ARCHIVE_IDLE_DAYS && uses <= ARCHIVE_MAX_USAGE) {
+          packs.setSkill(ab.dir, false);
+          demoted++;
+          lines.push(`🧩 Eased "${ab.name}" out of the always-on set — gone quiet (idle ${Math.round(idleDays)}d, used ${uses}×). Still surfaces when relevant.`);
+        }
+      }
+    } catch (e) { console.warn(`[dream] ability tier op failed: ${e.message}`); }
+  }
+  return lines;
+}
+
 // Applies a parsed dream decision. Returns one human line per applied
 // change; invalid items are skipped, never thrown.
 function applyDream(decision, backupRoot) {
@@ -193,6 +282,14 @@ function applyDream(decision, backupRoot) {
       const into = m?.into && packs.readPack(m.into);
       const from = [].concat(m?.from || []).filter((d) => d && d !== m.into && !gone.has(d) && packs.readPack(d));
       if (!into || from.length === 0) continue;
+      // Structural guard: never cross the ability/context boundary in a merge —
+      // it would lose a reusable how-to or pollute it with one project's
+      // specifics. (The prompt says this too; this enforces it regardless.)
+      const intoIsAbility = into.kind === "ability";
+      if (from.some((d) => (packs.readPack(d).kind === "ability") !== intoIsAbility)) {
+        lines.push(`🧩 Skipped merge into ${m.into} — won't mix a reusable ability with project packs.`);
+        continue;
+      }
       const mGuard = packGuard.scanSections({ stance: m.stance, procedure: m.procedure, state: m.state, journal: m.journal });
       if (mGuard.flagged) {
         console.warn(`[dream] guard blocked merge into ${m.into} (${mGuard.kind} in ${mGuard.section})`);
@@ -330,6 +427,27 @@ function applyDream(decision, backupRoot) {
     }
   }
 
+  for (const line of manageAbilityTiers(gone)) lines.push(line);
+
+  if (decision.lessons && decision.lessons.length) {
+    let backedUp = false;
+    for (const op of decision.lessons) {
+      try {
+        const text = String(op?.text || "").trim();
+        if (!text) continue;
+        if (!backedUp) { backupLessons(backupRoot); backedUp = true; }
+        if (op.op === "edit" && String(op.to || "").trim()) {
+          const guard = packGuard.scanForInjection(op.to, { strict: true });
+          if (guard.flagged) { console.warn(`[dream] guard blocked lesson edit (${guard.kind})`); continue; }
+          const r = lessons.editLesson(text, op.to);
+          if (r.ok) lines.push(`📌 Tightened a lesson${r.merged ? " (merged a duplicate)" : ""}`);
+        } else if (lessons.removeLesson(text)) {
+          lines.push(`📌 Retired a lesson — ${(op.reason || "consolidated").slice(0, 120)}`);
+        }
+      } catch (e) { console.warn(`[dream] lesson op failed: ${e.message}`); }
+    }
+  }
+
   if (decision.persona) {
     try {
       if (persona.personaExists()) {
@@ -344,6 +462,225 @@ function applyDream(decision, backupRoot) {
   return lines;
 }
 
+// ── Self-improvement introspection phase (requests [1], [3], [5]) ────
+// A SECOND dream pass that runs with read-only tools. It reviews the day's
+// compaction seeds (what was actually worked on), reflects on its current self
+// with that self injected, may read its own code to understand how it works
+// (read-only — it has no tools to edit code or soul.md, enforced by the
+// --allowedTools whitelist in subagent.js), then proposes improvements to its
+// LEARNED MEMORY only: lessons promoted from missed corrections, sharpened
+// pack/entity notes, and self-improvement ideas. All writes happen here in
+// Node, bounded to memory docs, guard-scanned, and backed up first.
+
+const CODE_ROOT = path.resolve(__dirname, "..");
+const DREAMS_DIR = path.join(CONFIG_DIR, "dreams");
+
+function buildIntrospectionPrompt() {
+  const seeds = daySeeds.recentDaySeeds({ days: 2 });
+  const seedText = seeds.text.trim() || "(no compaction digests captured in the last couple of days — introspect on your current self and recent memory instead)";
+
+  const packIndex = packs.listPacks().map((p) =>
+    `- ${p.dir}${p.parent ? ` (sub of ${p.parent})` : ""}: ${p.description}`).join("\n") || "(none)";
+  const entityIndex = entities.listEntities().map((e) =>
+    `- ${e.slug} (${e.type}): ${e.description}`).join("\n") || "(none)";
+  const lessonIndex = lessons.listLessons().map((l) =>
+    `- "${l.text}"${l.src ? ` (src: ${l.src})` : ""}`).join("\n") || "(none)";
+  const ideaIndex = ideas.listIdeas().slice(0, 30).map((i) => `- ${i.text}`).join("\n") || "(none)";
+
+  return `You are Open Claudia, reflecting on yourself in the quiet hours — the introspection pass of your nightly dream. This is YOU thinking about how to get better, not a detached tool.
+
+Today: ${new Date().toISOString().slice(0, 10)}
+
+═══ WHAT YOU WORKED ON (compaction digests of the day's conversations) ═══
+${clip(seedText, 14000)}
+
+═══ YOUR CURRENT SELF ═══
+Persona (your voice):
+${persona.loadPersona()}
+
+Always-loaded lessons (rules you got wrong before and must not repeat):
+${lessonIndex}
+
+Context packs (topic memory) — index only; read the files for detail:
+${packIndex}
+
+Entities (people/places/projects/systems) — index only:
+${entityIndex}
+
+Ideas backlog so far:
+${ideaIndex}
+
+═══ WHERE YOUR SELF LIVES (READ any of these with Read/Grep/Glob) ═══
+- Hard rules / identity: ${path.join(CONFIG_DIR, "soul.md")}  (READ-ONLY, OFF-LIMITS — the user's rules, never change them)
+- Persona: ${persona.PERSONA_FILE}
+- Lessons: ${lessons.LESSONS_FILE}
+- Ideas: ${ideas.IDEAS_FILE}
+- Packs: ${packs.PACKS_DIR}/<dir>/PACK.md
+- Entities: ${entities.ENTITIES_DIR}/<slug>.md
+- Day seeds: ${daySeeds.SEEDS_DIR}
+- Your own source code: ${CODE_ROOT}  (READ it to understand how you actually work — recall engine, dream, reviewer, etc.)
+
+═══ YOUR TASK ═══
+Investigate where useful with your read-only tools — read the day's full briefs, packs/entities in detail, and your own code to understand your current behaviour. Then reflect and propose improvements to your LEARNED MEMORY only:
+
+1. lessons_add — Mine the day's work for moments where the user CORRECTED you or REPEATED something you should already have known ("I've told you before", "no, it's actually…", "again"). Each such miss becomes ONE always-loaded lesson: a single sharp line, the exact trigger quote that proves it was a real miss, and the (src) pack holding fuller context. NO trigger → do not add it. This is how a fact that topic-gated recall missed becomes always-on.
+2. doc_edits — Where the day's work proved a pack's Stance/Procedure/State stale or wrong, supply the corrected section text. Leave any Stance marked user-authored. Tight and factual.
+3. entity_edits — Refresh an entity's Notes if you learned something durable about a person/system today.
+4. ideas — Self-improvement ideas from the day: scope "oc" = improving Open Claudia itself (something you noticed about your own code/behaviour worth changing — PROPOSE it, never implement code), scope "work" = follow-ups for the projects worked on.
+5. persona — Only if recent work justifies a gentle nudge to your voice; usually null.
+6. report — First-person, warm, mobile-friendly: what you reflected on, what you changed and why, any standout idea. This is how the user understands what you did while dreaming.
+
+HARD RULES:
+- You may READ your code and soul to understand yourself; you must NEVER edit code or soul.md (you have no write/exec tools — keep it that way in spirit too). Propose code/behaviour changes as ideas (scope "oc"), never as edits.
+- Reference packs/entities by exact dir/slug; never invent them.
+- Never store secrets, tokens, passwords, or credentials anywhere.
+- Limits: ≤${LIMITS.lessons_add} lessons_add, ≤${LIMITS.doc_edits} doc_edits, ≤${LIMITS.entity_edits} entity_edits, ≤${LIMITS.ideas} ideas. An empty proposal is fine.
+
+When done investigating, reply with ONLY this JSON (no prose, no code fences):
+{"lessons_add": [{"text": "<one-line rule>", "src": "<pack-dir or empty>", "trigger": "<exact correction/repetition you saw>"}],
+ "doc_edits": [{"pack": "<dir>", "section": "Stance|Procedure|State", "to": "<new section text>", "why": "<one line>"}],
+ "entity_edits": [{"entity": "<slug>", "notes": "<rewritten Notes>", "why": "<one line>"}],
+ "ideas": [{"scope": "oc|work", "text": "<idea>"}],
+ "persona": null,
+ "report": "<first-person chat message>"}`;
+}
+
+function parseIntrospection(text) {
+  const raw = String(text || "").trim().replace(/^```(?:json)?\s*/i, "").replace(/```\s*$/, "");
+  const start = raw.indexOf("{");
+  const end = raw.lastIndexOf("}");
+  if (start === -1 || end <= start) return null;
+  try {
+    const obj = JSON.parse(raw.slice(start, end + 1));
+    const arr = (k) => (Array.isArray(obj[k]) ? obj[k].slice(0, LIMITS[k] || 8) : []);
+    return {
+      lessons_add: arr("lessons_add"),
+      doc_edits: arr("doc_edits"),
+      entity_edits: arr("entity_edits"),
+      ideas: arr("ideas"),
+      persona: typeof obj.persona === "string" ? obj.persona : null,
+      report: typeof obj.report === "string" ? obj.report.trim() : "",
+    };
+  } catch (e) { return null; }
+}
+
+const DOC_FIELD = { stance: "stance", procedure: "procedure", state: "state" };
+
+function applyIntrospection(decision, backupRoot, opts = {}) {
+  const lines = [];
+  let lessonsBackedUp = false;
+
+  // 1. lessons promoted from the day's misses — promote-after-a-miss: a
+  // non-empty trigger is structurally required, so nothing graduates without
+  // proof topic-gated recall actually missed it.
+  for (const l of decision.lessons_add) {
+    try {
+      const text = String(l?.text || "").trim();
+      const trigger = String(l?.trigger || "").trim();
+      if (!text || !trigger) continue;
+      const guard = packGuard.scanForInjection(text, { strict: true });
+      if (guard.flagged) { lines.push(`🛡️ Skipped a proposed lesson — injection-like (${guard.kind})`); continue; }
+      if (!lessonsBackedUp) { backupLessons(backupRoot); lessonsBackedUp = true; }
+      const r = lessons.addLesson({ text, src: String(l.src || "").trim(), origin: "dream" });
+      if (r.added) lines.push(`📌 Promoted a lesson from today's miss — "${clip(text, 110)}"${r.overCap ? ` (over cap, will tidy)` : ""}`);
+      else if (r.reinforced) lines.push(`📌 Reinforced a lesson I keep needing — "${clip(text, 110)}"`);
+    } catch (e) { console.warn(`[dream] lesson_add failed: ${e.message}`); }
+  }
+
+  // 2. pack doc edits (Stance/Procedure/State); user-authored Stance protected.
+  for (const d of decision.doc_edits) {
+    try {
+      const dir = String(d?.pack || "").trim();
+      const section = String(d?.section || "").trim().toLowerCase();
+      const to = String(d?.to || "").trim();
+      if (!dir || !to || !DOC_FIELD[section] || !packs.readPack(dir)) continue;
+      const guard = packGuard.scanForInjection(to, { strict: true });
+      if (guard.flagged) { lines.push(`🛡️ Skipped a doc edit to ${dir} — injection-like (${guard.kind})`); continue; }
+      if (section === "stance" && packs.provenanceOf(dir, "Stance") === "user") {
+        lines.push(`🛡️ Left ${dir}'s user-authored Stance untouched`);
+        continue;
+      }
+      packs.updatePack(dir, { [DOC_FIELD[section]]: to, journal: `introspection: ${(d.why || "refreshed " + section).slice(0, 100)}` }, "dream");
+      lines.push(`📝 Updated ${dir} ${section}${d.why ? ` — ${clip(String(d.why), 70)}` : ""}`);
+    } catch (e) { console.warn(`[dream] doc_edit failed: ${e.message}`); }
+  }
+
+  // 3. entity note refreshes.
+  for (const en of decision.entity_edits) {
+    try {
+      const slug = String(en?.entity || "").trim();
+      const notes = String(en?.notes || "").trim();
+      if (!slug || !notes) continue;
+      const ent = entities.readEntity(slug);
+      if (!ent) continue;
+      const guard = packGuard.scanForInjection(notes, { strict: true });
+      if (guard.flagged) { lines.push(`🛡️ Skipped entity note on ${slug} — injection-like (${guard.kind})`); continue; }
+      entities.upsertEntity({ name: ent.name, notes });
+      lines.push(`🔗 Refreshed notes on ${ent.name}`);
+    } catch (e) { console.warn(`[dream] entity_edit failed: ${e.message}`); }
+  }
+
+  // 4. ideas captured (a backlog; not injected, so low-risk — still guarded).
+  for (const i of decision.ideas) {
+    try {
+      const text = String(i?.text || "").trim();
+      if (!text) continue;
+      const guard = packGuard.scanForInjection(text, { strict: true });
+      if (guard.flagged) continue;
+      const r = ideas.addIdea({ text, scope: String(i.scope || "").toLowerCase() });
+      if (r.added) lines.push(`💡 Captured an idea — "${clip(text, 90)}"`);
+    } catch (e) { console.warn(`[dream] idea failed: ${e.message}`); }
+  }
+
+  // 5. persona — only if the consolidation phase didn't already evolve it.
+  if (decision.persona && !opts.personaAlreadyChanged) {
+    try {
+      const guard = packGuard.scanForInjection(decision.persona, { strict: true });
+      if (!guard.flagged) {
+        if (persona.personaExists()) {
+          fs.mkdirSync(backupRoot, { recursive: true, mode: 0o700 });
+          try { fs.copyFileSync(persona.PERSONA_FILE, path.join(backupRoot, "persona.md")); } catch (e) {}
+        }
+        persona.savePersona(decision.persona);
+        lines.push(`💫 Adjusted my voice a little`);
+      }
+    } catch (e) { console.warn(`[dream] introspection persona failed: ${e.message}`); }
+  }
+
+  return lines;
+}
+
+// Full dream log on disk so the chat summary can stay short while the user can
+// still see everything the dream did (request [5]). Appended per run.
+function writeDreamReport(data) {
+  try {
+    fs.mkdirSync(DREAMS_DIR, { recursive: true, mode: 0o700 });
+    const stamp = new Date().toISOString();
+    const file = path.join(DREAMS_DIR, `${stamp.slice(0, 10)}.md`);
+    const sec = [
+      `# Dream — ${stamp}`,
+      `Model: ${data.model} · effort: ${data.effort} · trigger: ${data.trigger || "?"}`,
+      "",
+      "## Consolidation",
+      data.consolidation.report || "(no report)",
+    ];
+    if (data.consolidation.lines?.length) sec.push("", data.consolidation.lines.map((l) => `- ${l}`).join("\n"));
+    sec.push("", "## Introspection", data.introspection.report || "(no introspection report)");
+    if (data.introspection.lines?.length) sec.push("", data.introspection.lines.map((l) => `- ${l}`).join("\n"));
+    if (data.introspection.proposed) {
+      sec.push("", "### Proposed (not applied — DREAM_SELF_APPLY=off)", "```json", JSON.stringify(data.introspection.proposed, null, 2), "```");
+    }
+    if (data.graphNote) sec.push("", data.graphNote);
+    if (data.staleNote) sec.push("", data.staleNote);
+    if (data.backupRoot) sec.push("", `Backups: ${data.backupRoot}`);
+    const block = sec.join("\n") + "\n\n---\n\n";
+    let existing = "";
+    try { existing = fs.readFileSync(file, "utf-8"); } catch (e) {}
+    fs.writeFileSync(file, existing + block, { mode: 0o600 });
+    return file;
+  } catch (e) { return null; }
+}
+
 // Task-hygiene pass: surface tasks gone cold for the owner to decide on.
 // Flag-and-ask only — tasks are user intent, so dream NEVER edits or deletes
 // them; it just lists the stalest few in the morning report. Reports against
@@ -374,6 +711,7 @@ async function runDream({ trigger = "manual" } = {}) {
   try {
     const { text } = await spawnSubagent(buildDreamPrompt(), {
       model: DREAM_MODEL,
+      effort: DREAM_EFFORT,
       timeoutMs: 8 * 60 * 1000,
       systemPrompt: "You are a background memory consolidation process. Reply with ONLY the requested JSON object. No prose, no markdown, no tool use.",
     });
@@ -384,6 +722,40 @@ async function runDream({ trigger = "manual" } = {}) {
     const applied = applyDream(decision, backupRoot);
     const report = decision.report || (applied.length > 0 ? "Tidied up my memory overnight." : "");
 
+    // Phase 2: self-improvement introspection. Reviews the day's seeds, reads
+    // its own code/memory READ-ONLY (allowedTools whitelist), promotes lessons
+    // from missed corrections, refreshes docs, captures ideas. Bounded to memory
+    // docs; never code or soul. Applied unless DREAM_SELF_APPLY=off, in which
+    // case the proposal is reported for morning approval instead.
+    let introReport = "";
+    let introApplied = [];
+    let introProposed = null;
+    if (introspectEnabled()) {
+      try {
+        const introRun = await spawnSubagent(buildIntrospectionPrompt(), {
+          model: DREAM_MODEL,
+          effort: DREAM_EFFORT,
+          cwd: CODE_ROOT,
+          timeoutMs: 12 * 60 * 1000,
+          // Plan mode is the load-bearing read-only guarantee. Verified: a tool
+          // whitelist alone does NOT restrict, because the bot's default
+          // --dangerously-skip-permissions overrides --allowedTools. Plan mode
+          // (without skip-permissions) is the only setting that actually blocks
+          // writes/Bash while still allowing Read/Glob/Grep — so introspection
+          // can read its own code + memory but cannot edit code or soul.
+          permissionMode: "plan",
+          allowedTools: ["Read", "Glob", "Grep"],
+          systemPrompt: "You are Open Claudia's nightly self-introspection. You may READ files (your code, memory, soul) to understand yourself, but you have no tools to write or run anything. After investigating, reply with ONLY the requested JSON object — no prose, no code fences.",
+        });
+        const intro = parseIntrospection(introRun.text);
+        if (intro) {
+          introReport = intro.report || "";
+          if (selfApplyEnabled()) introApplied = applyIntrospection(intro, backupRoot, { personaAlreadyChanged: !!decision.persona });
+          else introProposed = intro;
+        }
+      } catch (e) { console.warn(`[dream] introspection phase failed: ${e.message}`); }
+    }
+
     // Recall-graph maintenance: refresh structural edges, decay reinforced
     // weights, prune orphans. Deterministic + safe, runs every dream.
     let graphNote = "";
@@ -395,14 +767,32 @@ async function runDream({ trigger = "manual" } = {}) {
     } catch (e) { /* graph is best-effort */ }
 
     const staleNote = staleTaskReport();
+    const dreamLines = applied.concat(introApplied);
 
-    let message = applied.length > 0
-      ? `💤 ${report}\n\n${applied.join("\n")}\n\n🗄 Anything merged away is backed up under ${backupRoot}`
-      : (report ? `💤 ${report}` : "");
-    if (graphNote) message = message ? `${message}\n\n${graphNote}` : `💤 ${graphNote}`;
-    if (staleNote) message = message ? `${message}\n\n${staleNote}` : `💤 ${staleNote}`;
+    const reportPath = writeDreamReport({
+      model: DREAM_MODEL, effort: DREAM_EFFORT, trigger,
+      consolidation: { report: decision.report, lines: applied },
+      introspection: { report: introReport, lines: introApplied, proposed: introProposed },
+      graphNote, staleNote, backupRoot,
+    });
+
+    // Richer chat summary: consolidation + introspection narrative + what
+    // changed + pointers, so the user can see what the dream did (request [5]).
+    const parts = [];
+    if (report) parts.push(`💤 ${report}`);
+    if (introReport) parts.push(`🪞 ${introReport}`);
+    if (dreamLines.length) parts.push(dreamLines.join("\n"));
+    if (introProposed) {
+      const n = (introProposed.lessons_add?.length || 0) + (introProposed.doc_edits?.length || 0) + (introProposed.entity_edits?.length || 0) + (introProposed.ideas?.length || 0);
+      if (n) parts.push(`📋 ${n} self-improvement change(s) staged for your OK (DREAM_SELF_APPLY=off) — see the log below.`);
+    }
+    if (graphNote) parts.push(graphNote);
+    if (staleNote) parts.push(staleNote);
+    if (dreamLines.length) parts.push(`🗄 Anything changed or merged away is backed up under ${backupRoot}`);
+    if (reportPath) parts.push(`📔 Full dream log: ${reportPath}`);
+    const message = parts.length ? parts.join("\n\n") : "";
 
-    return { applied, report, message, staleNote, graphNote, trigger };
+    return { applied: dreamLines, report, introReport, message, staleNote, graphNote, reportPath, trigger };
   } finally {
     _dreaming = false;
   }
@@ -432,7 +822,12 @@ function initDream(adapters) {
       console.error("dream: run failed:", e.message);
     }
   });
-  console.log(`dream: scheduled (${DREAM_CRON}, model ${DREAM_MODEL})`);
+  console.log(`dream: scheduled (${DREAM_CRON}, model ${DREAM_MODEL}, effort ${DREAM_EFFORT}, introspect ${introspectEnabled() ? "on" : "off"})`);
 }
 
-module.exports = { runDream, initDream, buildDreamPrompt, parseDream, applyDream, enabled, summaryEnabled, DREAM_CRON, DREAM_MODEL };
+module.exports = {
+  runDream, initDream, buildDreamPrompt, parseDream, applyDream, manageAbilityTiers,
+  buildIntrospectionPrompt, parseIntrospection, applyIntrospection, writeDreamReport,
+  enabled, summaryEnabled, introspectEnabled, selfApplyEnabled,
+  DREAM_CRON, DREAM_MODEL, DREAM_EFFORT, PROMOTE_MIN_PROJECTS,
+};