@inetafrica/open-claudia 3.1.27 → 3.2.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # 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.
+- **How it was found.** Reasoning from prod logs had already produced one wrong fix, so this time the local install was instrumented directly (unthrottled lifecycle events to a side file) and a real burst was captured. Two facts invisible to the console log settled it: every polling error after the first carried `_polling._abort === true` — meaning *we* aborted it, not Telegram — and `_lastUpdate` read 0 for 200+ seconds straight across 9 successful restarts. It also retired a number the previous investigation had reported as fact: the "~62s failure cadence" was an artifact of the 1/min log throttle. The real rate was one every ~15s.
+- **Root cause — three stacked deadlocks, each independently fatal to recovery.** (1) `_heal` → `_stopPollingClean` → `_agent.destroy()` kills the in-flight `getUpdates`, which surfaces in `_onPollingHiccup` ~1ms later as `EFATAL: socket hang up`. `_healTimer` had just been nulled at the top of `_heal`, so the "a heal is already scheduled" guard didn't hold and the teardown scheduled *another* heal — which tore the socket down again. Self-sustaining. (2) The backoff capped at 15s while `polling.params.timeout` is 30s, so every restarted poll was aborted at the halfway mark: `_lastUpdate`, the only evidence of recovery, could never advance. (3) `_armHealthyCheck` cleared its own pending timer on every re-arm, so a heal every 15s starved a check that needs 35s of quiet — **zero healthy checks fired in the entire captured burst** — and that callback owns the only reset of `_wedgedSince` and `_healBackoff`. With nothing able to clear the wedge clock, it ran monotonically to the 10-minute backstop. One ordinary `ECONNRESET` was enough to cost ten minutes and a reboot.
+- **Fix.** (1) A time-boxed self-abort window opened in `_stopPollingClean` makes `_onPollingHiccup` ignore the error our own teardown raises; it is never explicitly cleared, so a path that forgets to close it cannot permanently deafen the handler — the worst case is a dropped error that `_armHealthyCheck` re-arms 35s later anyway. (2) The heal ladder (now `_scheduleHeal`) escalates to 45s, clearing the 40s request timeout that bounds one `getUpdates`, so the late rungs give a poll genuine room to land; early rungs stay short because they run while polling is down. (3) Re-arming the healthy check no longer pushes its deadline back — the first arm always fires — while the baseline tracks the newest restart, so a poll that completed *before* the latest restart can't be mistaken for proof the latest restart worked. A failed `startPolling` now schedules its own retry rather than waiting for a hiccup that the suppression window means will never come.
+- **Proof, not assertion.** `testOneNetworkBlipDoesNotSpiralIntoTheWedgeExitLoop` models the poller instead of stubbing it: `destroy()` raises the teardown error for real, a healthy poll takes the full 30s hold to complete, the library re-dials ~300ms after a fault (which is why a heal always had something to destroy), and a virtual clock runs a single `ECONNRESET` well past the 10-minute budget. Against unmodified code it reproduces the production failure exactly — a storm of `socket hang up`, then "Polling wedged >10min and Telegram is reachable — exiting for a clean restart" — and against the fix the bot recovers with the wedge cleared and the ladder reset. Three narrower tests pin each deadlock individually. The previous release's test passed against a bug it did not fix because it drove `_enterOutagePause()` directly, a path production never takes; the lesson — model the interaction, don't stub past it — is why this harness raises the error from `destroy()`.
+- **Correction to v3.1.27's closing note.** That entry wondered whether the wedge-exit backstop earned its keep, observing that "210 restarts never helped". They did: a fresh process is the only thing that escapes the loop, which is exactly why each reboot bought 2.7–4.2h of health. The backstop stays until this fix is proven in the fleet.
+
 ## v3.1.27 — The outage pause stops feeding the wedge-exit clock (the fleet-wide Telegram reboot loop)
 
 - **Symptom.** Every Telegram-channel bot was rebooting itself in a loop while no other bot was: rashmi 214 restarts in 7d15h, euvy 210 in 7d17h, ruk-ai 62 in 44h, rahil-coders 11 — 4 of 4 pods running the `telegram` channel. All 12 pods running only `kazee, spaces, web` sat at 0. All 16 share one node and one egress IP, so node, address and NetworkPolicy preset were all controlled for; the *unrestricted* bot (euvy, allow-all egress) restarted most, which retired the egress theory rather than confirming it. The channel was the only discriminator.

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/channels/telegram/adapter.js

@@ -44,6 +44,9 @@ class TelegramAdapter {
     this._deferredExitLogAt = 0; // throttle the "deferring restart, turn in progress" log (1/min)
     this._lastHiccupLog = 0;     // throttle the transient-error log (1/min)
     this._healBackoff = 0;       // grows per consecutive heal, capped
+    this._selfAbortUntil = 0;    // teardown grace: errors WE caused aren't faults
+    this._healthyBaseline = 0;   // newest restart the pending healthy-check judges
+    this._healthyReArmMsg = "";  // reason text if that check finds no completed poll
     this._pausedForOutage = false; // host-network outage: poll loop stopped, slow re-probe owns recovery
     this._outageProbeTimer = null; // the ~30s re-probe loop that runs while paused
     this._pollWatchdogTimer = null; // detects a silent first/active getUpdates stall
@@ -112,6 +115,15 @@ class TelegramAdapter {
   // old exit-for-relaunch *was* the restart the bot kept doing on every idle
   // timeout (a sleep/wake burst could exhaust all 6 attempts in seconds).
   _onPollingHiccup(msg) {
+    // OUR OWN teardown, not a fault. _stopPollingClean destroys the agent, which
+    // kills the in-flight getUpdates and surfaces here as "socket hang up" 1-5ms
+    // later. Counting it re-armed the heal that had just torn the socket down —
+    // a self-sustaining loop that ran until the 10-min backstop exited the
+    // process (root-caused 2026-08-03 from a live capture: after the ONE genuine
+    // ECONNRESET, every subsequent error carried _polling._abort === true, i.e.
+    // we aborted it). The heal re-arms its own follow-up via _armHealthyCheck,
+    // so dropping these loses no recovery.
+    if (Date.now() < (this._selfAbortUntil || 0)) return;
     if (this._pausedForOutage) return; // paused for a host outage; the slow re-probe owns recovery
     // During a 409 streak the conflict handler owns the poll lifecycle; a heal
     // here would startPolling straight back into the conflict and its errors
@@ -125,8 +137,21 @@ class TelegramAdapter {
       console.log(`${this._stamp()} Polling hiccup (${msg}) — retrying on a fresh connection.`);
     }
     if (this._healTimer) return; // a heal is already scheduled; let it run
-    this._healBackoff = Math.min(this._healBackoff + 1, 5);
-    const delay = Math.min(15000, 500 * 2 ** this._healBackoff); // 1s … 15s
+    this._scheduleHeal();
+  }
+
+  // The heal ladder MUST out-wait one getUpdates or it can never observe
+  // success: a heal tears the socket down, so an interval shorter than the poll
+  // hold aborts every attempt before it can complete and _lastUpdate (the only
+  // evidence of recovery) stays pinned at 0 forever. The old 15s cap sat at HALF
+  // the 30s long-poll hold, which made recovery structurally impossible — a
+  // burst could only ever end at the 10-min wedge-exit. The cap now clears the
+  // 40s request timeout, which bounds even a hung poll, so the last rungs give a
+  // poll genuine room to land. Early rungs stay short: they run while polling is
+  // still down, where retrying fast is free and often enough.
+  _scheduleHeal() {
+    this._healBackoff = Math.min(this._healBackoff + 1, 7);
+    const delay = Math.min(45000, 500 * 2 ** this._healBackoff); // 1s, 2s, 4s, 8s, 16s, 32s, 45s
     this._healTimer = setTimeout(() => this._heal(), delay);
   }
 
@@ -141,6 +166,13 @@ class TelegramAdapter {
   // destroying the agent forces a hung half-open getUpdates to settle NOW
   // instead of never. The 5s race caps the wait if teardown gets swallowed.
   async _stopPollingClean(reason) {
+    // Open the self-abort window BEFORE destroying the agent: the "socket hang
+    // up" it raises lands in _onPollingHiccup within milliseconds. Time-boxed
+    // (never an explicit clear) so a path that forgets to close it can't deafen
+    // the hiccup handler permanently — the worst case is that a genuine error
+    // inside the window is dropped, and _armHealthyCheck still re-arms recovery
+    // 35s later. Covers the 5s stop race + 500ms settle + startPolling.
+    this._selfAbortUntil = Date.now() + 10000;
     const stopped = Promise.resolve(this.bot.stopPolling({ reason })).catch(() => {});
     try { this._agent.destroy(); } catch (e) {}
     await Promise.race([stopped, new Promise((r) => setTimeout(r, 5000))]);
@@ -244,7 +276,12 @@ class TelegramAdapter {
       this._pollStartedAt = Date.now();
       await this.bot.startPolling({ restart: false });
     } catch (e) {
-      return; // restart didn't take — the next hiccup reschedules a heal
+      // Restart didn't take. This used to fall through to "the next hiccup
+      // reschedules a heal", but the self-abort window means the teardown we
+      // just did raises no hiccup — so nothing would be scheduled and the
+      // adapter would sit dead until the wedge-exit. Schedule it ourselves.
+      if (!this._healTimer) this._scheduleHeal();
+      return;
     }
     this._armHealthyCheck(this._pollStartedAt, "restart completed but no getUpdates within 35s");
   }
@@ -254,18 +291,29 @@ class TelegramAdapter {
   // nothing, so a blind timer would declare it healthy and reset _wedgedSince,
   // hiding the wedge until the 10-min backstop rebooted. Gate the reset on a
   // completed poll; otherwise re-arm a heal.
+  //
+  // Re-arming used to clearTimeout the pending check, which starved it: heals
+  // ran every 15s, the check needed 35s of quiet, so it NEVER fired — and it
+  // owns the only reset of _wedgedSince/_healBackoff, so the wedge clock ran
+  // unbroken to the 10-min exit (zero healthcheck events in a 200s+ live
+  // capture, 2026-08-03). Now the DEADLINE is never pushed back — the first arm
+  // wins and always fires — while the baseline tracks the newest restart, so a
+  // poll that completed before the latest restart can't be mistaken for proof
+  // that the latest restart worked.
   _armHealthyCheck(restartedAt, reArmMsg) {
-    if (this._healthyTimer) clearTimeout(this._healthyTimer);
+    this._healthyBaseline = restartedAt;
+    this._healthyReArmMsg = reArmMsg;
+    if (this._healthyTimer) return;
     this._healthyTimer = setTimeout(() => {
       this._healthyTimer = null;
       const lastCompletedPoll = this.bot?._polling?._lastUpdate || 0;
-      if (lastCompletedPoll >= restartedAt) {
+      if (lastCompletedPoll >= this._healthyBaseline) {
         if (this._wedgedSince) console.log(`${this._stamp()} Polling healthy again.`);
         this._wedgedSince = 0;
         this._healBackoff = 0;
         this._deferredExitLogAt = 0;
       } else {
-        this._onPollingHiccup(reArmMsg);
+        this._onPollingHiccup(this._healthyReArmMsg);
       }
     }, 35000);
   }

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,
 };