@inetafrica/open-claudia 3.1.28 → 3.2.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## v3.2.0 — The employee batch: memory hygiene at write time, prospective memory, earned trust, and learning from the owner's judgment calls
+
+Three approved plans land together — memory adoption A1-A4 (from the TencentDB-Agent-Memory review), codegraph Phase 1, and employee capabilities C1-C6 — plus the Kazee group speaker-identity fix. Two rules hold throughout: **report-only where trust is involved** (nothing here grants, acts, or loosens an approval rule by itself), and **no new standing context cost** (everything injects only when already-matched content fires, or lands in the nightly dream summary).
+
+- **A1 — write-time dedup adjudicator, gated (the only hot-path item).** The post-turn reviewer's journal facts used to append unconditionally; duplicates accumulated all day for the one nightly pass that can lose things (merge) to clean up. Now cheap extractive recall checks each proposed fact against existing journal lines first. The gate keeps the hot path free: no candidates → zero LLM cost, store as proposed; exact-normalized duplicates auto-skip mechanically; only the fuzzy remainder goes to ONE batched low-tier call returning per-fact `store | update | merge | skip`. Fail-open everywhere — any error, timeout, or malformed judgement stores facts as proposed, because dedup failure must never make memory worse than append-only.
+- **A2 — merges keep the absorbed packs' history.** Dream merges used to delete the absorbed pack's entire Journal (surviving only in the backup dir); a merged pack read younger and thinner than the history it represents. Absorbed Journal lines now carry into the survivor — normalized-exact dedup only (never fuzzy: similar-but-distinct events must both survive), date-ascending, the cap keeps newest and drops undated lines first.
+- **A3 — substitutability stamps.** The reviewer self-rates each journal line 0-10 for how fully its wording substitutes for the turn's original words — a checkable claim about the text, not a guess about future importance. The score rides the stored line as a trailing `⟨s:N⟩` marker (announcements stay clean, near-dup similarity ignores it) and protects low-scored, verbatim-precious lines from the dream's journal collapse.
+- **A4 — section budgets are enforced, not requested.** "Keep State under ~150 words" was prose; States drifted. LLM-edited sections now have mechanical ceilings: pack State trims at the cap with a visible cut marker + flag, entity Notes and persona sections trim at theirs, and the review prompt measures State against the target so over-budget turns the reviewer's job into an edit, not an append. Mandate (owner-set policy) and user-origin writes are never trimmed.
+- **codegraph — code-structure queries as a reusable read-only tool (Phase 1).** Machine-side `codegraph` tool wrapping `@colbymchenry/codegraph`, pinned exactly 1.5.0 (native binaries from a solo author — upgrades are deliberate, reviewed events, never `^` drift), `CODEGRAPH_TELEMETRY=0` baked into every invocation, 12 read-only verbs with query verbs auto-syncing the index first. TOOL.md carries the graded trust model: `explore`/`node`/`search`/`files` are high-trust retrieval; `callers`/`impact`/`affected` are **advisory, positive-signal only** (verified misses: CJS namespace calls, some TS class-method sites) — grep remains the completeness check for destructive refactors. Two-week usage evaluation follows; MCP exposure was dropped against the token-efficiency goal.
+- **C1 — prospective memory.** "Next time X comes up, mention Y" — reminders bound to a TOPIC (pack or entity), not a time; crons and watches already own time and condition. They fire as a `📌 Pending:` line when the target surfaces in recall injection or is opened with `pack show`/`entity show`, and are consumed ONLY at commit points — a dropped render can never eat a reminder. One-shot by default with a fired ledger; `--sticky` survives; the dream GCs expired and orphaned entries. New `open-claudia remind` CLI.
+- **C2 — recall misses become permanent tests.** `open-claudia recall-case add "<query>" --expect <slug>` saves a case whenever a miss is corrected; the dream re-grades the suite nightly against the deterministic recall floor (matchPacks + matchEntities — the candidate stage every engine builds on) so the suite runs, and means the same thing, on nights the providers are down. Capped with oldest-first rotation; orphaned cases drop; pass-rate + delta land in the dream's memory-health section. "It feels degraded" is now a number.
+- **C3 — skill certification: trust is earned per verb, and granting stays human.** Tools already log per-verb runs in state.json; a certification tier is now derived from that telemetry — `certified` at ≥5 clean runs with no recent failure, `probation` for 7 days after a failure (only clean runs SINCE the failure re-certify, read from history), `learning` otherwise. `tool show` renders the tier per verb, labeled informational — nothing in the run gate consults it. The dream proposes at most 2 certified gated-tier verbs per night as Always-allow candidates; read-only verbs need no grant, and no auto-grant exists, ever.
+- **C4 — apprenticeship radar: it asks to be taught.** A deterministic 7-day transcript scan spots repeated manual work — the same ad-hoc command re-derived by the agent (inline code + `$`-lines; its own CLI excluded) or the owner asking for the same thing again — at ≥3 occurrences across ≥2 distinct days. The dream's introspection report offers at most 2 as `/learn` candidates with the counts as evidence. Report-only: `/learn` stays owner-triggered, and no evidence means no section, no standing cost.
+- **C5 — denied-approval mining: trained by the owner's judgment calls.** Every Deny tap was training data we dropped. Recently DENIED approval records (never approvals — an approve confirms, it corrects nothing) now feed the post-turn reviewer as fenced DATA with explicit never-instructions framing, on owner-turn reviews only — deny content can never surface via an external speaker's turn. Each deny is fed exactly once (stamped after a parseable decision; parse failure re-feeds). Forge-proof by structure: a deny-sourced lesson's trigger must cite a real record with status denied — the model cannot invent a refusal, and an approved id confers nothing.
+- **C6 — weekly cost self-report.** The dream summary gains a cost section: rolling 7-day totals over the existing per-turn usage log, top burns by project, week-over-week delta, and ONE concrete suggested cut picked by deterministic heuristics. Pure arithmetic — no model call, no new logging surface.
+- **Kazee groups: the Speaker block now knows the env-configured owner.** The prompt's Speaker block resolved identity ONLY through `people.findByHandle`, so an env-configured owner (`KAZEE_OWNER_USER_ID` — no people record, because auto-contact skips owners by design) and any not-yet-recorded group member spoke anonymously, and in group chats the model refused to attribute their messages (the "Ok go" incident, 2026-08-03). The block now falls back to the canonical owner check and the transport-reported display name — without a name ever conferring owner standing (R1 intact).
+- **Eleven new release-chain tests** (chain now 67): journal union, substitutability stamps, section budgets, dedup adjudicator, prospective memory, recall regressions, cost report, speaker context, approval mining, tool certification, apprenticeship radar. The 360° dangling-pathway pass found and closed one real gap pre-release: the C5 deny-feed originally fired on ALL reviewed turns, including external speakers' — now owner-gated with tests proving external turns see nothing and records stay un-mined.
+
 ## v3.1.28 — The Telegram reboot loop was self-inflicted: the heal kept tearing down its own recovery
 
 - **Symptom.** v3.1.27 shipped to all four Telegram pods and the loop continued (euvy: 6 restarts in 3h). Its fix was real but addressed a different failure — the dominant one never enters `_enterOutagePause` at all (zero "Telegram unreachable" lines in the crash logs). The decisive observation was that the bot reproduced it identically on a laptop — 155 self-exits in a local `bot.log` — which retired the cluster-network and conntrack theories outright. The shape is bursts: healthy for 2.7–4.2h, then ~10 minutes of failed heals, then `process.exit(1)`, repeat.

package/bin/cli.js

@@ -375,6 +375,16 @@ switch (command) {
     break;
   }
 
+  case "remind": {
+    require("./remind").run(args.slice(1));
+    break;
+  }
+
+  case "recall-case": {
+    require("./recall-case").run(args.slice(1));
+    break;
+  }
+
   case "lessons": {
     require("./lessons").run(args.slice(1));
     break;
@@ -473,6 +483,8 @@ Memory tools:
   open-claudia pack list|show|match|archive|restore|archived  Context packs: living topic docs (skills + memory)
   open-claudia tool list|search|show|scaffold|add|set|note|edit|run|migrate|remove  Reusable tools: git-tracked dirs (exec + TOOL.md + telemetry), risk-gated runs
   open-claudia entity list|show|match|note   Entity notes: people/places/projects memory
+  open-claudia remind "<note>" --pack <dir>|--entity <slug>  Prospective memory: fires when that topic next comes up (remind list|remove <id>)
+  open-claudia recall-case add "<query>" --expect <slug>     Memory regression suite: corrected recall misses become nightly-graded tests (list|run|remove)
   open-claudia lessons list|add|remove|show  Always-loaded learned rules (cross-cutting, promoted after a miss)
   open-claudia ideas list|add|remove|show    Self-improvement backlog (captured by the nightly dream)
   open-claudia keyring list|get|set|remove   Operational creds the agent can reuse (plaintext; vault for secrets)

package/bin/entity.js

@@ -31,6 +31,15 @@ function run(args) {
       const e = entities.findEntity(rest.join(" "));
       if (!e) { console.error(`No entity: ${rest.join(" ")}`); process.exitCode = 1; return; }
       console.log(fs.readFileSync(path.join(entities.ENTITIES_DIR, e.slug + ".md"), "utf-8"));
+      // C1: topic-bound reminders fire when the target is explicitly opened.
+      try {
+        const prospective = require("../core/prospective");
+        const pending = prospective.pendingFor("entity", e.slug);
+        if (pending.length) {
+          console.log("\n" + prospective.renderPendingLines(pending));
+          prospective.fire(pending, "entity show");
+        }
+      } catch (err) { /* reminders optional */ }
       break;
     }
 

package/bin/pack.js

@@ -113,6 +113,16 @@ function run(args) {
           for (const t of linked) console.log(`#   ${t.name} — ${t.description || "(no description)"}`);
         }
       } catch (e) { /* tools optional */ }
+      // C1: topic-bound reminders also fire when their target is explicitly
+      // opened — the show output IS the surface, so consuming here is safe.
+      try {
+        const prospective = require("../core/prospective");
+        const pending = prospective.pendingFor("pack", p.dir);
+        if (pending.length) {
+          console.log("\n" + prospective.renderPendingLines(pending));
+          prospective.fire(pending, "pack show");
+        }
+      } catch (e) { /* reminders optional */ }
       break;
     }
 

package/bin/recall-case.js

@@ -0,0 +1,90 @@
+// CLI: memory regression suite — corrected recall misses become permanent
+// test cases, re-graded nightly by the dream (deterministic, no LLM).
+//   open-claudia recall-case add "<query>" --expect <slug> [--expect <slug2>] [--source live-miss|manual] [--note "..."]
+//   open-claudia recall-case list
+//   open-claudia recall-case run [--cap N]     — grade now and print per-case results
+//   open-claudia recall-case remove <id>
+// Add a case the moment a recall miss gets corrected in chat — same moment a
+// lesson forms. The query should be the user's original phrasing; the expected
+// slug is the pack dir / entity slug that SHOULD have surfaced.
+
+const regressions = require("../core/recall-regressions");
+
+function usage() {
+  console.error('Usage: open-claudia recall-case add "<query>" --expect <slug> [--expect <slug2>] [--source live-miss|manual] [--note "..."]');
+  console.error("       open-claudia recall-case list | run [--cap N] | remove <id>");
+  process.exitCode = 1;
+}
+
+function run(args) {
+  const cmd = (args[0] || "").toLowerCase();
+
+  if (cmd === "" || cmd === "help" || cmd === "--help") return usage();
+
+  if (cmd === "list") {
+    const all = regressions.listCases();
+    if (all.length === 0) return console.log("No regression cases yet. Add one with: open-claudia recall-case add \"<query>\" --expect <slug>");
+    for (const c of all) {
+      const state = c.lastResult ? `${c.lastResult}${c.lastRunAt ? ` @ ${String(c.lastRunAt).slice(0, 10)}` : ""}` : "never run";
+      console.log(`${c.id}  [${state}] (${c.source})\n    query:  ${c.query}\n    expect: ${c.expectSlugs.join(", ")}${c.note ? `\n    note:   ${c.note}` : ""}`);
+    }
+    return;
+  }
+
+  if (cmd === "remove") {
+    const id = args[1];
+    if (!id) return usage();
+    if (!regressions.removeCase(id)) { console.error(`No case: ${id} (open-claudia recall-case list)`); process.exitCode = 1; return; }
+    console.log(`Removed case ${id}.`);
+    return;
+  }
+
+  if (cmd === "run") {
+    let cap;
+    const capIdx = args.indexOf("--cap");
+    if (capIdx !== -1) cap = Math.max(1, parseInt(args[capIdx + 1], 10) || regressions.NIGHTLY_CAP);
+    const before = regressions.listCases();
+    if (before.length === 0) return console.log("No regression cases to run.");
+    const res = regressions.runSuite(cap ? { cap } : {});
+    for (const c of regressions.listCases()) {
+      if (!c.lastResult) continue;
+      console.log(`${c.lastResult === "pass" ? "✅" : "❌"} ${c.id}  ${c.query.slice(0, 60)}${c.lastResult === "fail" ? "  (expected: " + c.expectSlugs.join(", ") + ")" : ""}`);
+    }
+    const rate = res.ran > 0 ? Math.round((res.passed / res.ran) * 100) : 0;
+    console.log(`\n${res.passed}/${res.ran} passing (${rate}%)${res.orphaned ? `, ${res.orphaned} orphaned case(s) dropped` : ""}${res.total > res.ran ? `, ${res.total - res.ran} deferred to next rotation` : ""}.`);
+    return;
+  }
+
+  if (cmd === "add") {
+    const rest = args.slice(1);
+    const expect = [];
+    let source = "manual", note = "";
+    for (let i = 0; i < rest.length; i++) {
+      if (rest[i] === "--expect") { expect.push(rest[++i]); continue; }
+      if (rest[i] === "--source") { source = rest[++i]; continue; }
+      if (rest[i] === "--note") { note = rest[++i] || ""; continue; }
+    }
+    const query = rest.filter((a, i) => {
+      if (a === "--expect" || a === "--source" || a === "--note") return false;
+      if (i > 0 && ["--expect", "--source", "--note"].includes(rest[i - 1])) return false;
+      return true;
+    }).join(" ").trim();
+    if (!query || expect.length === 0) return usage();
+    // Warn (don't refuse) on an unknown slug — the pack may be created next.
+    const packs = require("../core/packs");
+    const entities = require("../core/entities");
+    for (const s of expect) {
+      let known = false;
+      try { known = !!packs.readPack(s); } catch (e) {}
+      if (!known) { try { known = !!entities.readEntity(s); } catch (e) {} }
+      if (!known) console.log(`⚠️  ${s} is not a known pack dir or entity slug right now — the case will grade as orphaned until it exists.`);
+    }
+    const entry = regressions.addCase({ query, expectSlugs: expect, source, note });
+    console.log(`🧪 Case ${entry.id} added — nightly recall must surface ${expect.join(", ")} for: "${query}"`);
+    return;
+  }
+
+  usage();
+}
+
+module.exports = { run };

package/bin/remind.js

@@ -0,0 +1,82 @@
+// CLI: prospective memory — "next time X comes up, mention Y".
+//   open-claudia remind "<note>" --pack <dir> | --entity <slug> [--sticky] [--expires <YYYY-MM-DD>]
+//   open-claudia remind list
+//   open-claudia remind remove <id>
+// Reminders are topic-bound, not time-bound: they fire when the target pack/
+// entity next surfaces in recall injection or is opened with pack show /
+// entity show. Time-based reminding belongs to schedule-wakeup / cron-add;
+// condition-based reminding belongs to watch-add.
+
+const prospective = require("../core/prospective");
+
+function usage() {
+  console.error('Usage: open-claudia remind "<note>" --pack <dir> | --entity <slug> [--sticky] [--expires <YYYY-MM-DD>]');
+  console.error("       open-claudia remind list | remove <id>");
+  process.exitCode = 1;
+}
+
+function run(args) {
+  const cmd = (args[0] || "").toLowerCase();
+
+  if (cmd === "" || cmd === "help" || cmd === "--help") return usage();
+
+  if (cmd === "list") {
+    const all = prospective.listReminders();
+    if (all.length === 0) return console.log("No pending reminders.");
+    for (const r of all) {
+      const extras = [r.sticky ? "sticky" : "one-shot", r.expiresAt ? `expires ${String(r.expiresAt).slice(0, 10)}` : ""].filter(Boolean).join(", ");
+      console.log(`${r.id}  [${r.targetType}:${r.targetSlug}] (${extras}, asked ${String(r.createdAt).slice(0, 10)})\n    ${r.note}`);
+    }
+    return;
+  }
+
+  if (cmd === "remove") {
+    const id = args[1];
+    if (!id) return usage();
+    if (!prospective.removeReminder(id)) { console.error(`No reminder: ${id} (open-claudia remind list)`); process.exitCode = 1; return; }
+    console.log(`Removed reminder ${id}.`);
+    return;
+  }
+
+  // Default verb: add. The note is everything that isn't a flag.
+  const rest = args.slice();
+  const takeFlag = (flag, hasValue = true) => {
+    const i = rest.indexOf(flag);
+    if (i === -1) return null;
+    const v = hasValue ? rest[i + 1] : true;
+    rest.splice(i, hasValue ? 2 : 1);
+    return v == null ? "" : v;
+  };
+  const packArg = takeFlag("--pack");
+  const entityArg = takeFlag("--entity");
+  const sticky = takeFlag("--sticky", false) === true;
+  const expires = takeFlag("--expires");
+  const note = rest.join(" ").trim();
+
+  if (!note || (!packArg && !entityArg) || (packArg && entityArg)) return usage();
+
+  // Resolve the target now so a typo surfaces immediately, not as a reminder
+  // that silently never fires (dream GC would drop it as an orphan).
+  let targetType, targetSlug, targetName;
+  if (packArg) {
+    const p = require("../core/packs").findPack(packArg);
+    if (!p) { console.error(`No pack: ${packArg} (open-claudia pack list)`); process.exitCode = 1; return; }
+    targetType = "pack"; targetSlug = p.dir; targetName = p.name || p.dir;
+  } else {
+    const e = require("../core/entities").findEntity(entityArg);
+    if (!e) { console.error(`No entity: ${entityArg} (open-claudia entity list)`); process.exitCode = 1; return; }
+    targetType = "entity"; targetSlug = e.slug; targetName = e.name || e.slug;
+  }
+
+  let expiresAt = null;
+  if (expires) {
+    const t = Date.parse(expires);
+    if (!Number.isFinite(t)) { console.error(`Bad --expires date: ${expires} (use ISO, e.g. 2026-09-01)`); process.exitCode = 1; return; }
+    expiresAt = new Date(t).toISOString();
+  }
+
+  const entry = prospective.addReminder({ note, targetType, targetSlug, sticky, expiresAt });
+  console.log(`📌 Reminder ${entry.id} armed — fires when ${targetType} "${targetName}" next comes up${sticky ? " (sticky: repeats until removed)" : " (one-shot)"}${expiresAt ? `, expires ${expiresAt.slice(0, 10)}` : ""}.`);
+}
+
+module.exports = { run };

package/bin/tool.js

@@ -214,9 +214,14 @@ async function run(args) {
         console.log(`Runs: ${t.runCount}${t.lastUsed ? ` · last used ${t.lastUsed.slice(0, 16).replace("T", " ")}` : ""}${exit}`);
       }
       if (t.verbs && Object.keys(t.verbs).length) {
-        const rows = Object.entries(t.verbs).map(([v, s]) =>
-          `  • ${v}: ${s.runs} run(s), last exit ${s.lastExit}${s.lastSuccess ? `, last success ${s.lastSuccess.slice(0, 10)}` : ""}`);
-        console.log("Verbs:\n" + rows.join("\n"));
+        let certs = {};
+        try { certs = tools.certificationForState({ verbs: t.verbs, history: t.history }); } catch (e) {}
+        const rows = Object.entries(t.verbs).map(([v, s]) => {
+          const c = certs[v];
+          const cert = c ? ` · ${c.tier}${c.tier === "certified" ? "" : ` (${c.cleanRuns}/${tools.CERTIFY_CLEAN_RUNS} clean)`}` : "";
+          return `  • ${v}: ${s.runs} run(s), last exit ${s.lastExit}${s.lastSuccess ? `, last success ${s.lastSuccess.slice(0, 10)}` : ""}${cert}`;
+        });
+        console.log("Verbs (certification is earned trust, informational only):\n" + rows.join("\n"));
       }
       try {
         const log = repo.toolLog(t.name, 5);

package/core/apprenticeship.js

@@ -0,0 +1,104 @@
+"use strict";
+
+// C4: apprenticeship radar. A deterministic 7-day scan of the project
+// transcripts for repeated manual work — the same ad-hoc command re-derived by
+// the agent, or the owner asking for the same thing again and again. The scan
+// only gathers EVIDENCE; the dream's introspection pass turns it into at most
+// two /learn CANDIDATES in its report. Report-only end to end: /learn remains
+// the owner-triggered capture, and nothing here creates a pack or tool.
+
+const fs = require("fs");
+const path = require("path");
+const { TRANSCRIPTS_DIR } = require("./config");
+
+const WINDOW_DAYS = 7;
+const MIN_REPEATS = 3;
+const MIN_DAYS = 2;
+const MAX_CANDIDATES = 2;
+const MIN_COMMAND_CHARS = 12;
+const MIN_REQUEST_CHARS = 16;
+const MAX_REQUEST_CHARS = 200;
+
+function normalize(s) {
+  return String(s || "").replace(/\s+/g, " ").trim();
+}
+
+// Commands the assistant quoted in a turn: inline code spans plus "$ "-prefixed
+// lines. The bot's own bookkeeping CLI is excluded — /learn-ing `open-claudia
+// task list` would be circular.
+function commandsIn(text) {
+  const out = [];
+  const t = String(text || "");
+  for (const m of t.matchAll(/`([^`\n]{4,160})`/g)) out.push(m[1]);
+  for (const m of t.matchAll(/^\s*\$\s+(.{4,160})$/gm)) out.push(m[1]);
+  return out
+    .map(normalize)
+    .filter((c) => c.length >= MIN_COMMAND_CHARS)
+    .filter((c) => !c.startsWith("open-claudia "))
+    .filter((c) => /^[a-zA-Z_./~]/.test(c) && /\s/.test(c)); // looks like an invocation, not a bare word or path
+}
+
+function scanForApprenticeship({
+  now = Date.now(), days = WINDOW_DAYS, dir = TRANSCRIPTS_DIR,
+  minRepeats = MIN_REPEATS, minDays = MIN_DAYS, max = MAX_CANDIDATES,
+} = {}) {
+  let files;
+  try { files = fs.readdirSync(dir).filter((f) => f.endsWith(".jsonl")); }
+  catch (e) { return []; }
+  const from = now - days * 86400000;
+  const tally = new Map(); // key → {kind, sample, count, days:Set, files:Set, lastAt}
+  const bump = (kind, sample, day, file, at) => {
+    const key = `${kind}:${sample.toLowerCase()}`;
+    const e = tally.get(key) || { kind, sample, count: 0, days: new Set(), files: new Set(), lastAt: "" };
+    e.count += 1;
+    e.days.add(day);
+    e.files.add(file);
+    if (at > e.lastAt) { e.lastAt = at; e.sample = sample; }
+    tally.set(key, e);
+  };
+  for (const f of files) {
+    let raw;
+    try { raw = fs.readFileSync(path.join(dir, f), "utf-8"); } catch (e) { continue; }
+    for (const line of raw.split("\n")) {
+      if (!line.trim()) continue;
+      let rec;
+      try { rec = JSON.parse(line); } catch (e) { continue; }
+      const t = Date.parse(rec.timestamp || "");
+      if (!Number.isFinite(t) || t < from || t > now) continue;
+      const day = new Date(t).toISOString().slice(0, 10);
+      if (rec.role === "assistant") {
+        for (const cmd of new Set(commandsIn(rec.text))) bump("command", cmd, day, f, rec.timestamp);
+      } else if (rec.role === "user") {
+        const req = normalize(rec.text);
+        if (req.length >= MIN_REQUEST_CHARS && req.length <= MAX_REQUEST_CHARS && !req.startsWith("/")) {
+          bump("request", req, day, f, rec.timestamp);
+        }
+      }
+    }
+  }
+  return [...tally.values()]
+    .filter((e) => e.count >= minRepeats && e.days.size >= minDays)
+    .sort((a, b) => b.count - a.count || b.days.size - a.days.size)
+    .slice(0, max)
+    .map((e) => ({ kind: e.kind, sample: e.sample, count: e.count, days: e.days.size, sessions: e.files.size }));
+}
+
+// Prompt block for the dream's introspection pass. Empty string when nothing
+// repeated — the section only exists when there is evidence (no standing cost).
+function radarSection(opts = {}) {
+  const found = scanForApprenticeship(opts);
+  if (!found.length) return "";
+  const lines = found.map((c) =>
+    `- [${c.kind}] ${c.kind === "command" ? `\`${c.sample}\`` : `"${c.sample}"`} — ${c.count}× across ${c.days} day${c.days === 1 ? "" : "s"} (${c.sessions} session${c.sessions === 1 ? "" : "s"})`);
+  return [
+    "═══ APPRENTICESHIP RADAR (deterministic scan of the last 7 days of transcripts) ═══",
+    "Repeated manual work — the same thing re-derived by hand instead of taught once:",
+    ...lines,
+    `In your report, offer at most ${MAX_CANDIDATES} of these as /learn candidates ("want to teach me this properly? say /learn after we next do it"), citing the counts above as evidence. Report-only: /learn stays owner-triggered — NEVER capture a pack, tool, or lesson from this radar yourself.`,
+  ].join("\n");
+}
+
+module.exports = {
+  WINDOW_DAYS, MIN_REPEATS, MIN_DAYS, MAX_CANDIDATES,
+  commandsIn, scanForApprenticeship, radarSection,
+};

package/core/approvals.js

@@ -231,6 +231,43 @@ function consume(id, commandLine) {
   } finally { releaseRecordLock(held); }
 }
 
+// Read-side for the reviewer's denied-approval mining (C5): recent decided
+// records, newest first. The ledger itself is already persisted per-record —
+// this only lists it.
+function listDecided({ withinMs = MAX_AGE_MS, statuses = ["denied", "approved"] } = {}) {
+  let entries;
+  try { entries = fs.readdirSync(APPROVALS_DIR); } catch (e) { return []; }
+  const wanted = new Set(statuses);
+  const cutoff = Date.now() - withinMs;
+  const out = [];
+  for (const f of entries) {
+    if (!f.endsWith(".json")) continue;
+    let rec;
+    try { rec = JSON.parse(fs.readFileSync(path.join(APPROVALS_DIR, f), "utf-8")); } catch (e) { continue; }
+    if (!rec || !wanted.has(rec.status)) continue;
+    const decidedAt = Date.parse(rec.decidedAt || "");
+    if (!Number.isFinite(decidedAt) || decidedAt < cutoff) continue;
+    out.push(rec);
+  }
+  return out.sort((a, b) => Date.parse(b.decidedAt) - Date.parse(a.decidedAt));
+}
+
+// Stamp records the reviewer has already been shown, so each deny is fed to
+// the correction-detector exactly once.
+function markMined(ids) {
+  for (const id of ids || []) {
+    const held = acquireRecordLock(id);
+    if (!held) continue;
+    try {
+      const rec = read(id);
+      if (rec && !rec.minedAt) {
+        rec.minedAt = new Date().toISOString();
+        writeRecord(rec);
+      }
+    } finally { releaseRecordLock(held); }
+  }
+}
+
 module.exports = {
   APPROVALS_DIR,
   MAX_COMMAND_BYTES,
@@ -240,6 +277,8 @@ module.exports = {
   decide,
   detach,
   formatApprovedCommand,
+  listDecided,
+  markMined,
   read,
   waitForDecision,
 };

package/core/cost-report.js

@@ -0,0 +1,140 @@
+"use strict";
+
+// C6: cost self-report. Aggregates the existing per-turn usage-history.jsonl
+// (ts, project, provider/model, token parts, costUsd) into a rolling 7-day
+// section for the dream summary: total spend + tokens, top burns by project,
+// week-over-week delta, and ONE concrete suggested cut picked by
+// deterministic heuristics. Pure arithmetic — no model call, no new logging
+// surface, nothing recorded at turn time beyond what already exists.
+
+const usageLog = require("./usage-log");
+
+const WINDOW_DAYS = 7;
+// Heuristic thresholds (exported for tests): concentration of spend in one
+// project, poor cache-hit ratio on a meaningful token volume, oversized
+// average context.
+const CONCENTRATION_SHARE = 0.6;
+const CONCENTRATION_MIN_USD = 1;
+const CACHE_RATIO_FLOOR = 0.5;
+const CACHE_MIN_INPUT_TOKENS = 1_000_000;
+const CONTEXT_AVG_CEILING = 120_000;
+
+function fmtTokens(n) {
+  if (!Number.isFinite(n) || n <= 0) return "0";
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${Math.round(n / 1_000)}k`;
+  return String(n);
+}
+
+function inWindow(ts, from, to) {
+  const t = Date.parse(ts);
+  return Number.isFinite(t) && t >= from && t < to;
+}
+
+function aggregate(records) {
+  const agg = {
+    turns: 0, costUsd: 0, inputTokens: 0, outputTokens: 0,
+    cacheReadTokens: 0, contextTokenSum: 0, contextTurns: 0,
+    byProject: new Map(),
+  };
+  for (const r of records) {
+    agg.turns += 1;
+    const cost = Number(r.costUsd) || 0;
+    agg.costUsd += cost;
+    // session_total records carry cumulative token snapshots — counting them
+    // as a turn's tokens would double-bill. Their per-turn cost still counts.
+    if (r.usageScope !== "session_total") {
+      agg.inputTokens += Number(r.inputTokens) || 0;
+      agg.outputTokens += Number(r.outputTokens) || 0;
+      agg.cacheReadTokens += Number(r.cacheReadTokens) || 0;
+      const ctx = Number(r.billedContextTokens ?? r.contextTokens) || 0;
+      if (ctx > 0) { agg.contextTokenSum += ctx; agg.contextTurns += 1; }
+    }
+    const key = String(r.project || "(no project)");
+    const p = agg.byProject.get(key) || { costUsd: 0, turns: 0 };
+    p.costUsd += cost;
+    p.turns += 1;
+    agg.byProject.set(key, p);
+  }
+  return agg;
+}
+
+function topBurns(agg, n = 3) {
+  return [...agg.byProject.entries()]
+    .map(([project, v]) => ({ project, costUsd: v.costUsd, turns: v.turns }))
+    .sort((a, b) => b.costUsd - a.costUsd)
+    .slice(0, n);
+}
+
+// ONE concrete cut, first matching heuristic. Deterministic on purpose — a
+// suggestion the owner can check against the numbers shown next to it.
+function suggestCut(agg, burns) {
+  const top = burns[0];
+  if (top && agg.costUsd > 0 && top.costUsd / agg.costUsd > CONCENTRATION_SHARE && top.costUsd >= CONCENTRATION_MIN_USD) {
+    return `${Math.round((top.costUsd / agg.costUsd) * 100)}% of spend is "${top.project}" — review that channel's model tier and recall engine first.`;
+  }
+  const cacheDenom = agg.cacheReadTokens + agg.inputTokens;
+  if (cacheDenom >= CACHE_MIN_INPUT_TOKENS && agg.cacheReadTokens / cacheDenom < CACHE_RATIO_FLOOR) {
+    return `cache hit ratio is only ${Math.round((agg.cacheReadTokens / cacheDenom) * 100)}% — an unstable prompt head or long gaps between turns are re-billing the prefix; keeping the always-on head stable would cut input cost.`;
+  }
+  const avgCtx = agg.contextTurns ? Math.round(agg.contextTokenSum / agg.contextTurns) : 0;
+  if (avgCtx > CONTEXT_AVG_CEILING) {
+    return `average billed context is ${fmtTokens(avgCtx)} tokens/turn — earlier compaction or fewer injected packs would trim every turn.`;
+  }
+  return null;
+}
+
+function weeklyReport({ now = Date.now(), days = WINDOW_DAYS, history } = {}) {
+  const records = history || usageLog.loadUsageHistory();
+  const from = now - days * 86400000;
+  const prevFrom = from - days * 86400000;
+  const current = aggregate(records.filter((r) => inWindow(r.ts, from, now)));
+  const previous = aggregate(records.filter((r) => inWindow(r.ts, prevFrom, from)));
+  const burns = topBurns(current);
+  return {
+    days,
+    turns: current.turns,
+    costUsd: Math.round(current.costUsd * 100) / 100,
+    inputTokens: current.inputTokens,
+    outputTokens: current.outputTokens,
+    cacheReadTokens: current.cacheReadTokens,
+    cacheHitRatio: (current.cacheReadTokens + current.inputTokens) > 0
+      ? current.cacheReadTokens / (current.cacheReadTokens + current.inputTokens)
+      : null,
+    prevCostUsd: Math.round(previous.costUsd * 100) / 100,
+    deltaPct: previous.costUsd > 0 ? Math.round(((current.costUsd - previous.costUsd) / previous.costUsd) * 100) : null,
+    topBurns: burns,
+    suggestedCut: suggestCut(current, burns),
+  };
+}
+
+// Dream entry point: returns announce lines (empty when there is no usage in
+// the window — silence over noise).
+function reportLines(opts = {}) {
+  const r = weeklyReport(opts);
+  if (r.turns === 0) return { report: r, lines: [] };
+  const deltaTxt = r.deltaPct === null ? "" : ` · ${r.deltaPct >= 0 ? "+" : ""}${r.deltaPct}% vs prior week`;
+  const cacheTxt = r.cacheHitRatio === null ? "" : ` (cache ${Math.round(r.cacheHitRatio * 100)}%)`;
+  const burnsTxt = r.topBurns.length
+    ? ` Top: ${r.topBurns.map((b) => `${b.project} $${b.costUsd.toFixed(2)}`).join(" · ")}.`
+    : "";
+  const lines = [
+    `💸 Cost, last ${r.days}d: $${r.costUsd.toFixed(2)} · ${r.turns} turn${r.turns === 1 ? "" : "s"} · ${fmtTokens(r.inputTokens)} in / ${fmtTokens(r.outputTokens)} out${cacheTxt}${deltaTxt}.${burnsTxt}`,
+  ];
+  if (r.suggestedCut) lines.push(`💡 Cut: ${r.suggestedCut}`);
+  return { report: r, lines };
+}
+
+module.exports = {
+  WINDOW_DAYS,
+  CONCENTRATION_SHARE,
+  CONCENTRATION_MIN_USD,
+  CACHE_RATIO_FLOOR,
+  CACHE_MIN_INPUT_TOKENS,
+  CONTEXT_AVG_CEILING,
+  aggregate,
+  topBurns,
+  suggestCut,
+  weeklyReport,
+  reportLines,
+};