cert-coach-web 0.1.0 → 0.1.2

package/web/public/spa-render.js

@@ -0,0 +1,107 @@
+// DOM markdown renderer, extracted from app.js so it can be unit-tested in
+// jsdom. `doc` is injected (rather than using the global) so the same code runs
+// in the browser (documents) and in tests (jsdom window.document).
+import { safeHttpUrl } from "./spa-logic.js";
+
+const INLINE = /(`[^`]+`|\*\*[^*]+\*\*|\[[^\]]+\]\(https?:\/\/[^)\s]+\))/g;
+
+/** Inline markdown (code, bold, http links) -> DocumentFragment. */
+export function inlineNodes(doc, text) {
+  const frag = doc.createDocumentFragment();
+  let last = 0;
+  for (const m of text.matchAll(INLINE)) {
+    if (m.index > last) frag.append(doc.createTextNode(text.slice(last, m.index)));
+    const tok = m[0];
+    if (tok.startsWith("`")) {
+      const code = doc.createElement("code");
+      code.textContent = tok.slice(1, -1);
+      frag.append(code);
+    } else if (tok.startsWith("**")) {
+      const b = doc.createElement("strong");
+      b.textContent = tok.slice(2, -2);
+      frag.append(b);
+    } else {
+      const mm = tok.match(/^\[([^\]]+)\]\((https?:\/\/[^)\s]+)\)$/);
+      const a = doc.createElement("a");
+      a.textContent = mm?.[1] || tok;
+      a.href = safeHttpUrl(mm?.[2] || "");
+      a.target = "_blank";
+      a.rel = "noreferrer";
+      frag.append(a);
+    }
+    last = m.index + tok.length;
+  }
+  if (last < text.length) frag.append(doc.createTextNode(text.slice(last)));
+  return frag;
+}
+
+/** Block markdown (fenced code, headings, lists, quotes, paragraphs) -> DocumentFragment. */
+export function markdownFragment(doc, text) {
+  const frag = doc.createDocumentFragment();
+  const lines = String(text || "").split(/\r?\n/);
+  let i = 0;
+  let para = [];
+  const flush = () => {
+    if (!para.length) return;
+    const p = doc.createElement("p");
+    p.append(inlineNodes(doc, para.join(" ")));
+    frag.append(p);
+    para = [];
+  };
+  while (i < lines.length) {
+    const line = lines[i];
+    if (/^```/.test(line)) {
+      flush();
+      const lang = line.slice(3).trim();
+      i++;
+      const code = [];
+      while (i < lines.length && !/^```/.test(lines[i])) code.push(lines[i++]);
+      if (i < lines.length) i++;
+      const pre = doc.createElement("pre");
+      if (lang === "mermaid") pre.className = "diagram";
+      const c = doc.createElement("code");
+      c.textContent = code.join("\n");
+      pre.append(c);
+      frag.append(pre);
+      continue;
+    }
+    const h = line.match(/^(#{1,3})\s+(.*)$/);
+    if (h) {
+      flush();
+      const elh = doc.createElement("h" + h[1].length);
+      elh.append(inlineNodes(doc, h[2]));
+      frag.append(elh);
+      i++;
+      continue;
+    }
+    if (/^\s*[-*]\s+/.test(line)) {
+      flush();
+      const ul = doc.createElement("ul");
+      while (i < lines.length && /^\s*[-*]\s+/.test(lines[i])) {
+        const li = doc.createElement("li");
+        li.append(inlineNodes(doc, lines[i].replace(/^\s*[-*]\s+/, "")));
+        ul.append(li);
+        i++;
+      }
+      frag.append(ul);
+      continue;
+    }
+    if (/^>\s?/.test(line)) {
+      flush();
+      const quote = doc.createElement("blockquote");
+      quote.append(inlineNodes(doc, line.replace(/^>\s?/, "")));
+      frag.append(quote);
+      i++;
+      continue;
+    }
+    if (!line.trim()) {
+      flush();
+      i++;
+      continue;
+    }
+    para.push(line);
+    i++;
+  }
+  flush();
+  return frag;
+}

package/web/public/spa-store.js

@@ -0,0 +1,100 @@
+/**
+ * Console session store: the mutable bits that used to be module-level `let`s.
+ *
+ * Everything lives on one exported object so other modules can mutate fields
+ * (`store.state = s`). A module cannot reassign an imported binding, so plain
+ * named exports would not work here.
+ *
+ * The small pure helpers at the bottom are unit-tested in tests/spa-store.test.mjs
+ * because they carry the fiddly rules (multi-select toggling, timer labels,
+ * which card a phase maps to).
+ */
+
+export const store = {
+  /** Latest state snapshot from the server. Null until bootstrap. */
+  state: null,
+  /** Currently selected option values. */
+  selected: new Set(),
+  /** 1 = guess, 2 = unsure, 3 = confident. */
+  confidence: 2,
+  /** Epoch ms the current question was first shown. */
+  startedAt: 0,
+  /** `${qid}:${rev}` of the question the timer belongs to. */
+  questionKey: "",
+  timerHandle: null,
+
+  eventSource: null,
+  theoryNodes: null,
+  activeTheoryNode: "",
+  activeView: "study",
+  activeLayout: "triptych",
+
+  chat: {
+    enabled: false,
+    reason: "",
+    busy: false,
+    /** { div, text } while an assistant answer streams. */
+    stream: null,
+    /** Echo suppression: the message we already rendered optimistically. */
+    pendingUser: "",
+  },
+  toolCards: new Map(),
+};
+
+/** New selection set for a single- or multi-select question. */
+export function toggleSelection(selected, value, multi) {
+  const next = new Set(selected || []);
+  if (!multi) return new Set([value]);
+  if (next.has(value)) next.delete(value);
+  else next.add(value);
+  return next;
+}
+
+/** `m:ss` for a non-negative number of seconds. */
+export function formatTimer(totalSeconds) {
+  const s = Math.max(0, Math.floor(Number(totalSeconds) || 0));
+  return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, "0")}`;
+}
+
+/**
+ * Timer text for a question. A timed mock counts down to its deadline;
+ * otherwise the timer counts up from when the question appeared.
+ */
+export function timerLabel({ deadline = 0, startedAt = 0 }, now = Date.now()) {
+  if (deadline) return `${formatTimer((deadline - now) / 1000)} left`;
+  return formatTimer((now - startedAt) / 1000);
+}
+
+/** Stem length drives a CSS class so long question text gets a smaller font. */
+export function stemClass(text) {
+  const len = String(text || "").length;
+  if (len > 420) return "stem-xlong";
+  if (len > 220) return "stem-long";
+  return "";
+}
+
+/** Human-readable mock summary, built from the loop's mock payload. */
+export function mockSummary(m = {}) {
+  const completed = m.completed ?? m.total ?? 0;
+  const requested = m.requested ?? m.total ?? 0;
+  const score = m.correct || 0;
+  return {
+    meta: `${score}/${completed} correct · ${completed}/${requested} completed`,
+    title: m.score != null ? `Mock score: ${Math.round(m.score * 100)}%` : "Mock complete",
+    note: `${m.timedOut ? "Time expired. " : ""}Requested ${m.requested ?? "?"} questions; completed ${completed}. Feedback is shown now that the run is over. progress.json was not modified.`,
+  };
+}
+
+/** Which card a server phase maps to (`loading` means nothing to show yet). */
+export function phaseCard(phase) {
+  if (phase === "question" || phase === "submitted") return "question";
+  if (phase === "feedback") return "feedback";
+  if (phase === "teach") return "teach";
+  if (phase === "mock_summary") return "mock";
+  return "idle";
+}
+
+/** True when the server says the current question takes multiple answers. */
+export function isMultiSelect(state) {
+  return state?.q?.multi === true;
+}

package/web/public/spa-ui.js

@@ -0,0 +1,62 @@
+/**
+ * Leaf UI helpers: connection dot, notice bar, card switching, phase pill,
+ * layout toggle, and the coach status log.
+ *
+ * No feature logic lives here, so every module can depend on these freely.
+ */
+import { el } from "./spa-dom.js";
+import { store } from "./spa-store.js";
+
+export function setConnection(kind) {
+  el.connection.classList.remove("live", "down");
+  if (kind === "live") el.connection.classList.add("live");
+  if (kind === "down") el.connection.classList.add("down");
+  el.connection.title = kind === "live" ? "live" : kind === "down" ? "reconnecting" : "connecting";
+}
+
+export function showNotice(text) {
+  if (!text) {
+    el.notice.hidden = true;
+    el.notice.textContent = "";
+    return;
+  }
+  el.notice.hidden = false;
+  el.notice.textContent = text;
+}
+
+/** Show exactly one of the study cards. `null` shows none. */
+export function only(card) {
+  for (const c of [el.loading, el.idle, el.question, el.feedback, el.teach, el.mock]) {
+    if (c) c.hidden = c !== card;
+  }
+}
+
+export function setPhase(phase) {
+  el.phasePill.textContent = phase || "idle";
+}
+
+export function setLayout(name) {
+  store.activeLayout = ["triptych", "command"].includes(name) ? name : "triptych";
+  el.app.dataset.layout = store.activeLayout;
+  for (const b of el.layoutButtons) b.classList.toggle("active", b.dataset.appLayout === store.activeLayout);
+  localStorage.setItem("certCoachLayout", store.activeLayout);
+  return store.activeLayout;
+}
+
+/** Prepend coach log lines (newest first) and cap the list at 80. */
+export function appendStatus(lines) {
+  for (const item of lines || []) {
+    const div = document.createElement("div");
+    div.className = "status-line";
+    const t = item?.at ? new Date(item.at).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit", second: "2-digit" }) : "";
+    const strong = document.createElement("strong");
+    strong.textContent = t ? `${t} ` : "";
+    const span = document.createElement("span");
+    span.textContent = item?.line || "";
+    div.append(strong, span);
+    el.statusLog.prepend(div);
+  }
+  while (el.statusLog.children.length > 80) el.statusLog.lastChild.remove();
+  // Newest just under the "Coach log" title; older entries stay below.
+  el.statusLog.parentElement.scrollTop = 0;
+}

package/web/public/spa-views.js

@@ -0,0 +1,279 @@
+/**
+ * The non-study views: Path (blueprint route), Dashboard (readiness), Theory
+ * (per-node reference) and Logs (study_log.md), plus the command-center strip.
+ *
+ * Every loader reads the same /api/status or /api/theory endpoints and never
+ * mutates progress.
+ */
+import { el } from "./spa-dom.js";
+import { store } from "./spa-store.js";
+import { api } from "./spa-api.js";
+import { renderMarkdownInto } from "./spa-mermaid.js";
+import { safeHttpUrl } from "./spa-logic.js";
+
+function stat(k, v) {
+  const d = document.createElement("div");
+  d.className = "stat";
+  const kk = document.createElement("div");
+  kk.className = "k";
+  kk.textContent = k;
+  const vv = document.createElement("div");
+  vv.className = "v";
+  vv.textContent = String(v);
+  d.append(kk, vv);
+  return d;
+}
+
+/** Compact readiness/domains strip shown in the command-center layout. */
+export async function updateCommandStrip() {
+  try {
+    const data = await api("/api/status");
+    const d = data.dashboard || {};
+    const p = data.plan || {};
+    const r = d.readiness || {};
+    const readiness = Math.round((r.value || 0) * 100);
+    const coverage = Math.round((r.coverage || 0) * 100);
+    el.cmdReadiness.textContent = `${readiness}%`;
+    el.cmdCoverage.textContent = `${coverage}%`;
+    el.cmdDue.textContent = String(d.due || 0);
+    const weak = (p.weakNodes || [])[0];
+    el.cmdWeak.textContent = weak?.domain || "—";
+    el.cmdWeakNote.textContent = weak ? `${weak.title} · ${Math.round((weak.accuracy || 0) * 100)}%` : "No attempts yet";
+    el.cmdReadinessBar.style.setProperty("--value", `${readiness}%`);
+    el.cmdCoverageBar.style.setProperty("--value", `${coverage}%`);
+    el.cmdDomains.replaceChildren();
+    for (const dom of p.domains || []) {
+      const row = document.createElement("div");
+      row.className = "domain-row";
+      const name = document.createElement("span");
+      name.textContent = dom.name;
+      const meter = document.createElement("div");
+      meter.className = "domain-meter";
+      const fill = document.createElement("i");
+      fill.style.setProperty("--value", `${Math.round((dom.accuracy || 0) * 100)}%`);
+      meter.append(fill);
+      const val = document.createElement("b");
+      val.textContent = `${Math.round((dom.accuracy || 0) * 100)}%`;
+      row.append(name, meter, val);
+      el.cmdDomains.append(row);
+    }
+  } catch {
+    /* command strip is optional */
+  }
+}
+
+export function setView(name) {
+  store.activeView = name;
+  for (const b of document.querySelectorAll(".nav button, .side-nav button")) b.classList.toggle("active", b.dataset.tab === name);
+  el.studyView.hidden = name !== "study";
+  el.pathView.hidden = name !== "path";
+  el.dashboardView.hidden = name !== "dashboard";
+  el.theoryView.hidden = name !== "theory";
+  el.logsView.hidden = name !== "logs";
+  if (name === "path") void loadPath();
+  if (name === "dashboard") void loadDashboard();
+  if (name === "theory") void loadTheory();
+  if (name === "logs") void loadLogs();
+}
+
+export async function loadPath() {
+  el.pathRoute.textContent = "Loading...";
+  el.pathDetail.textContent = "";
+  try {
+    const data = await api("/api/status");
+    const p = data.plan || {};
+    el.pathMeta.textContent = p.ready
+      ? "target met"
+      : `probe ${Math.min(p.seenQuestions || 0, p.probeSize || 20)}/${p.probeSize || 20} · target ${Math.round((p.target?.readiness || 0.85) * 100)}% readiness / ${Math.round((p.target?.coverage || 0.8) * 100)}% coverage`;
+    el.pathRoute.replaceChildren();
+    const steps = document.createElement("div");
+    steps.className = "route-steps";
+    for (const step of p.steps || []) {
+      const d = document.createElement("div");
+      d.className = "route-step " + (step.state || "");
+      d.textContent = `${step.name} · ${step.state || ""}`;
+      steps.append(d);
+    }
+    el.pathRoute.append(steps);
+    const callout = document.createElement("div");
+    callout.className = "route-callout";
+    const phase = document.createElement("h3");
+    phase.textContent = p.ready ? "READY" : String(p.phase || "progress").toUpperCase();
+    const why = document.createElement("p");
+    why.textContent = p.why || "";
+    const next = document.createElement("p");
+    next.textContent = "Next: " + (p.next || "");
+    const criteria = document.createElement("p");
+    criteria.className = "muted";
+    criteria.textContent = p.criteria || "";
+    callout.append(phase, why, next, criteria);
+    el.pathRoute.append(callout);
+
+    el.pathDetail.replaceChildren();
+    for (const d of p.domains || []) {
+      const section = document.createElement("section");
+      section.className = "path-domain";
+      const h = document.createElement("h3");
+      h.textContent = `${d.name} · ${Math.round((d.weight_min || 0) * 100)}–${Math.round((d.weight_max || 0) * 100)}% of exam`;
+      const summary = document.createElement("p");
+      summary.className = "muted";
+      summary.textContent = `${d.seen}/${d.total} questions seen · ${d.accuracy == null ? "no accuracy yet" : `${Math.round(d.accuracy * 100)}% accuracy`} · coverage ${Math.round((d.coverage || 0) * 100)}%`;
+      section.append(h, summary);
+      if (d.skills?.length) {
+        const skills = document.createElement("ul");
+        skills.className = "path-skills";
+        for (const s of d.skills) { const li = document.createElement("li"); li.textContent = s; skills.append(li); }
+        section.append(skills);
+      }
+      const table = document.createElement("table");
+      table.className = "node-table";
+      const head = document.createElement("tr");
+      for (const label of ["Node / subdomain", "Status", "Questions", "Accuracy", "Box"]) {
+        const th = document.createElement("th"); th.textContent = label; head.append(th);
+      }
+      table.append(head);
+      for (const n of d.nodes || []) {
+        const tr = document.createElement("tr");
+        const title = document.createElement("td");
+        title.className = "path-node-title";
+        title.textContent = n.title;
+        const small = document.createElement("small");
+        small.textContent = n.summary || n.id;
+        title.append(small);
+        const status = document.createElement("td");
+        const tag = document.createElement("span");
+        tag.className = "status-tag " + (n.status || "unseen");
+        tag.textContent = n.status || "unseen";
+        status.append(tag);
+        const qs = document.createElement("td");
+        qs.className = "num";
+        qs.textContent = `${n.seen}/${n.total}`;
+        const acc = document.createElement("td");
+        acc.className = "num";
+        acc.textContent = n.accuracy == null ? "—" : `${Math.round(n.accuracy * 100)}%`;
+        const box = document.createElement("td");
+        box.className = "num";
+        box.textContent = String(n.box ?? 0);
+        tr.append(title, status, qs, acc, box);
+        table.append(tr);
+      }
+      section.append(table);
+      el.pathDetail.append(section);
+    }
+  } catch (e) {
+    el.pathRoute.textContent = e.message;
+  }
+}
+
+export async function loadDashboard() {
+  el.dashboardBody.textContent = "Loading...";
+  try {
+    const data = await api("/api/status");
+    const d = data.dashboard || {};
+    const r = d.readiness || {};
+    el.dashboardMeta.textContent = `${d.title || ""} · ${d.verified || 0}/${d.total || 0} verified`;
+    el.dashboardBody.replaceChildren();
+    const grid = document.createElement("div");
+    grid.className = "dash-grid";
+    grid.append(
+      stat("Readiness", `${((r.value || 0) * 100).toFixed(1)}%`),
+      stat("Coverage", `${((r.coverage || 0) * 100).toFixed(0)}%`),
+      stat("Due now", d.due || 0),
+      stat("Gaps / review", `${d.boxes?.[1] || 0} / ${d.boxes?.[2] || 0}`),
+      stat("Mastered", d.boxes?.[3] || 0),
+      stat("Sessions", d.sessions || 0)
+    );
+    el.dashboardBody.append(grid);
+
+    const domains = document.createElement("div");
+    for (const [id, v] of Object.entries(r.by_domain || {})) {
+      const row = document.createElement("div");
+      row.className = "domain-row";
+      const name = document.createElement("span");
+      name.textContent = id;
+      const bar = document.createElement("div");
+      bar.className = "bar";
+      const fill = document.createElement("span");
+      fill.style.width = `${Math.round((v.accuracy || 0) * 100)}%`;
+      bar.append(fill);
+      const num = document.createElement("span");
+      num.className = "muted";
+      num.textContent = `${v.seen}/${v.total}${v.accuracy == null ? "" : ` · ${Math.round(v.accuracy * 100)}%`}`;
+      row.append(name, bar, num);
+      domains.append(row);
+    }
+    el.dashboardBody.append(domains);
+    if (d.weak?.length) {
+      const weak = document.createElement("div");
+      weak.className = "weak-list";
+      weak.textContent = "Weakest domains: " + d.weak.map((x) => `${x.domain} ${Math.round((x.accuracy || 0) * 100)}%`).join(" · ");
+      el.dashboardBody.append(weak);
+    }
+  } catch (e) {
+    el.dashboardBody.textContent = e.message;
+  }
+}
+
+export async function loadTheory() {
+  try {
+    if (!store.theoryNodes) {
+      const data = await api("/api/theory");
+      store.theoryNodes = data.nodes || [];
+      el.theoryNodes.replaceChildren();
+      for (const n of store.theoryNodes) {
+        const b = document.createElement("button");
+        b.type = "button";
+        b.textContent = n.title || n.id;
+        b.dataset.node = n.id;
+        b.addEventListener("click", () => selectTheory(n.id));
+        el.theoryNodes.append(b);
+      }
+    }
+    const preferred = store.state?.q?.node || store.state?.teach?.node || store.theoryNodes[0]?.id;
+    if (preferred) await selectTheory(preferred);
+  } catch (e) {
+    el.theoryBody.textContent = e.message;
+  }
+}
+
+export async function selectTheory(node) {
+  store.activeTheoryNode = node;
+  for (const b of el.theoryNodes.querySelectorAll("button")) b.classList.toggle("active", b.dataset.node === node);
+  el.theoryBody.textContent = "Loading...";
+  try {
+    const t = await api("/api/theory?node=" + encodeURIComponent(node));
+    el.theoryBody.replaceChildren();
+    const h = document.createElement("h2");
+    h.textContent = t.title || node;
+    const meta = document.createElement("p");
+    meta.className = "muted";
+    meta.textContent = [t.domain, t.summary].filter(Boolean).join(" · ");
+    el.theoryBody.append(h, meta);
+    const body = document.createElement("div");
+    renderMarkdownInto(body, t.section || "No theory section yet.");
+    el.theoryBody.append(body);
+    const doc = safeHttpUrl(t.docUrl || "");
+    if (doc) {
+      const p = document.createElement("p");
+      const a = document.createElement("a");
+      a.href = doc;
+      a.target = "_blank";
+      a.rel = "noreferrer";
+      a.textContent = doc;
+      p.append(a);
+      el.theoryBody.append(p);
+    }
+  } catch (e) {
+    el.theoryBody.textContent = e.message;
+  }
+}
+
+export async function loadLogs() {
+  el.logsBody.textContent = "Loading...";
+  try {
+    const data = await api("/api/log");
+    el.logsBody.textContent = data.text || "No study log yet.";
+  } catch (e) {
+    el.logsBody.textContent = e.message;
+  }
+}

package/web/public/styles.css

@@ -324,6 +324,7 @@ a:hover { color: #183677; }
 .chat-msg { max-width: 92%; padding: 9px 11px; border-radius: 11px; font-size: 12px; line-height: 1.5; overflow-wrap: anywhere; }
 .chat-msg.user { align-self: flex-end; background: var(--cobalt-soft); border: 1px solid #cbd7f7; color: #183677; }
 .chat-msg.assistant { align-self: flex-start; background: var(--surface-2); border: 1px solid var(--rule); }
+.chat-msg.system { align-self: center; max-width: 100%; background: transparent; border: 1px dashed var(--rule); color: var(--ink-3, #6b6257); font-size: 11px; font-style: italic; padding: 4px 10px; }
 .chat-msg.assistant p { margin: 0 0 7px; }
 .chat-msg.assistant p:last-child { margin-bottom: 0; }
 .chat-msg.assistant h1, .chat-msg.assistant h2, .chat-msg.assistant h3 { font-family: var(--font-display); font-size: 16px; margin: 10px 0 5px; }

package/web/server/chat.mjs

@@ -21,6 +21,15 @@ function textOf(message) {
     .join("");
 }
 
+// A long study session eventually overflows a small-context model. When the child
+// dies for that reason we compact instead of surfacing a dead chat.
+const CONTEXT_OVERFLOW = /context (?:window|length|size)|context (?:is )?too (?:big|large|long)|maximum context|token limit|too many tokens|prompt is too long/i;
+const DEFAULT_MAX_TURNS = 12;
+
+function isContextOverflow(message) {
+  return CONTEXT_OVERFLOW.test(String(message || ""));
+}
+
 function contextBlock(state) {
   const lines = [];
   lines.push(`[cert] ${state?.cert || "?"} · ${state?.mode || "practice"} · phase=${state?.phase || "idle"}`);
@@ -46,7 +55,7 @@ function contextBlock(state) {
 }
 
 export class ChatBridge extends EventEmitter {
-  constructor({ root, cert, cliPath, sessionDir = "", session = false }) {
+  constructor({ root, cert, cliPath, sessionDir = "", session = false, maxTurns }) {
     super();
     this.root = root;
     this.cert = cert;
@@ -56,6 +65,14 @@ export class ChatBridge extends EventEmitter {
     this.rpc = null;
     this.busy = false;
     this.history = [];
+    // Context hygiene: rotate the pi child before it outgrows a small-context model,
+    // carrying a short recap of earlier turns into the fresh session.
+    const configured = Number(maxTurns ?? process.env.CERT_COACH_CHAT_MAX_TURNS ?? DEFAULT_MAX_TURNS);
+    this.maxTurns = Number.isFinite(configured) && configured > 0 ? Math.floor(configured) : DEFAULT_MAX_TURNS;
+    this.turns = 0;
+    this.rotations = 0;
+    this.recap = "";
+    this.lastRotateReason = "";
     this.error = cliPath ? null : "Teaching chat is unavailable: no pi CLI found. Pass --pi <pi|path> or set PI_BIN.";
     this._assistant = "";
     this._tools = new Map();
@@ -67,6 +84,10 @@ export class ChatBridge extends EventEmitter {
       running: Boolean(this.rpc?.running),
       busy: this.busy,
       error: this.error,
+      turns: this.turns,
+      maxTurns: this.maxTurns,
+      rotations: this.rotations,
+      lastRotateReason: this.lastRotateReason,
       stderr: (this.rpc?.stderr || "").slice(-1200),
     };
   }
@@ -95,8 +116,19 @@ export class ChatBridge extends EventEmitter {
     rpc.on("event", (ev) => this._onRpc(ev));
     rpc.on("exit", (e) => {
       this.busy = false;
-      this.error = e.message;
       this.rpc = null;
+      if (isContextOverflow(e.message)) {
+        // Compact rather than dead-end: keep the learner's thread alive.
+        this.recap = this._buildRecap();
+        this.turns = 0;
+        this.rotations += 1;
+        this.lastRotateReason = "context-overflow";
+        this.error = null;
+        this._emitEvent({ type: "chat.rotated", reason: "context-overflow", rotations: this.rotations, hasRecap: Boolean(this.recap) });
+        this._emitEvent({ type: "chat.error", error: "Context limit reached. Earlier turns were summarised - your next message continues the conversation.", recoverable: true });
+        return;
+      }
+      this.error = e.message;
       this._emitEvent({ type: "chat.error", error: e.message });
     });
     await rpc.start();
@@ -161,17 +193,55 @@ export class ChatBridge extends EventEmitter {
     }
   }
 
+  /** Short recap of earlier turns, injected once into a fresh session. */
+  _buildRecap(limit = 6) {
+    const users = this.history.filter((m) => m.role === "user").slice(-limit);
+    const lastAssistant = [...this.history].reverse().find((m) => m.role === "assistant");
+    const lines = [];
+    if (users.length) {
+      lines.push("Earlier in this session the learner asked:");
+      for (const m of users) lines.push(`- ${String(m.text).replace(/\s+/g, " ").slice(0, 160)}`);
+    }
+    if (lastAssistant?.text) {
+      lines.push(`Where we left off: ${String(lastAssistant.text).replace(/\s+/g, " ").slice(0, 400)}`);
+    }
+    return lines.join("\n");
+  }
+
+  /** Stop the child so the next prompt starts a fresh pi session. */
+  async rotate(reason = "turn-limit") {
+    if (this.rpc) {
+      try { await this.rpc.stop(); } catch { /* ignore */ }
+      this.rpc = null;
+    }
+    this.recap = this._buildRecap();
+    this.turns = 0;
+    this.rotations += 1;
+    this.lastRotateReason = reason;
+    this.busy = false;
+    this._emitEvent({ type: "chat.rotated", reason, rotations: this.rotations, hasRecap: Boolean(this.recap) });
+    return this.recap;
+  }
+
   async prompt(text, state) {
     const clean = String(text || "").trim();
     if (!clean) throw new CoreError("EMPTY_PROMPT", "Message is empty.");
+    if (this.turns >= this.maxTurns) await this.rotate("turn-limit");
     await this.ensure();
     this.history.push({ role: "user", text: clean, at: new Date().toISOString() });
     if (this.history.length > 200) this.history = this.history.slice(-200);
     this._emitEvent({ type: "chat.user", text: clean });
     this.busy = true;
     this.error = null;
-    const message = `${contextBlock(state)}\n\n[learner]\n${clean}`;
-    const disposition = await this.rpc.prompt(message);
+    const parts = [];
+    if (this.recap) {
+      parts.push(`[session recap - earlier turns were summarised to keep this conversation responsive]\n${this.recap}`);
+      this.recap = "";
+    }
+    parts.push(contextBlock(state));
+    parts.push(`[learner]\n${clean}`);
+    this.turns += 1;
+    const disposition = await this.rpc.prompt(parts.join("\n\n"));
     return { disposition };
   }