@vue-skuilder/db 0.2.3 → 0.2.5

package/dist/index.mjs

@@ -1917,12 +1917,13 @@ __export(elo_exports, {
   default: () => ELONavigator
 });
 import { toCourseElo as toCourseElo2 } from "@vue-skuilder/common";
-var ELONavigator;
+var ELO_RELEVANCE_SIGMA, ELONavigator;
 var init_elo = __esm({
   "src/core/navigators/generators/elo.ts"() {
     "use strict";
     init_navigators();
     init_logger();
+    ELO_RELEVANCE_SIGMA = 300;
     ELONavigator = class extends ContentNavigator {
       /** Human-readable name for CardGenerator interface */
       name;
@@ -1962,8 +1963,8 @@ var init_elo = __esm({
         const scored = newCards.map((c) => {
           const cardElo = c.elo ?? 1e3;
           const distance = Math.abs(cardElo - userGlobalElo);
-          const rawScore = Math.max(0, 1 - distance / 500);
-          const samplingKey = rawScore > 0 ? Math.random() ** (1 / rawScore) : 0;
+          const relevance = Math.exp(-((distance / ELO_RELEVANCE_SIGMA) ** 2));
+          const samplingKey = relevance * (0.5 + 0.5 * Math.random());
           return {
             cardId: c.cardID,
             courseId: c.courseID,
@@ -1975,7 +1976,7 @@ var init_elo = __esm({
                 strategyId: this.strategyId || "NAVIGATION_STRATEGY-ELO-default",
                 action: "generated",
                 score: samplingKey,
-                reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), raw ${rawScore.toFixed(3)}, key ${samplingKey.toFixed(3)}`
+                reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), relevance ${relevance.toFixed(3)}, key ${samplingKey.toFixed(3)}`
               }
             ]
           };
@@ -13054,6 +13055,294 @@ mountMixerDebugger();
 // src/study/SessionDebugger.ts
 init_logger();
 init_PipelineDebugger();
+
+// src/study/SessionOverlay.ts
+init_logger();
+var activeController = null;
+function registerActiveController(controller) {
+  activeController = controller;
+}
+function getActiveController() {
+  return activeController;
+}
+var OVERLAY_ID = "skuilder-session-overlay";
+var POLL_MS = 300;
+var INLINE_THRESHOLD = 5;
+var SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+var spinnerFrame = 0;
+var overlayEl = null;
+var pollHandle = null;
+var lastSnapshot = null;
+var copyFlashUntil = 0;
+var minified = false;
+var expanded = {
+  reviewQ: false,
+  newQ: false,
+  failedQ: false,
+  drawn: false
+};
+function toggleSessionOverlay() {
+  if (typeof document === "undefined") {
+    logger.info("[Session Overlay] No DOM available (non-browser host); overlay unavailable.");
+    return;
+  }
+  if (overlayEl) {
+    teardown();
+    logger.info("[Session Overlay] Hidden.");
+  } else {
+    mount();
+    logger.info("[Session Overlay] Shown. Toggle off with window.skuilder.session.dbgOverlay().");
+  }
+}
+function mount() {
+  minified = false;
+  overlayEl = document.createElement("div");
+  overlayEl.id = OVERLAY_ID;
+  Object.assign(overlayEl.style, {
+    position: "fixed",
+    top: "8px",
+    left: "8px",
+    zIndex: "2147483647",
+    maxWidth: "320px",
+    maxHeight: "90vh",
+    overflowY: "auto",
+    padding: "8px 10px",
+    background: "rgba(17, 24, 39, 0.92)",
+    color: "#e5e7eb",
+    font: "11px/1.4 ui-monospace, SFMono-Regular, Menlo, monospace",
+    borderRadius: "6px",
+    boxShadow: "0 4px 16px rgba(0,0,0,0.4)",
+    pointerEvents: "auto",
+    userSelect: "none"
+  });
+  document.body.appendChild(overlayEl);
+  render();
+  pollHandle = setInterval(render, POLL_MS);
+}
+function teardown() {
+  if (pollHandle !== null) {
+    clearInterval(pollHandle);
+    pollHandle = null;
+  }
+  if (overlayEl?.parentNode) {
+    overlayEl.parentNode.removeChild(overlayEl);
+  }
+  overlayEl = null;
+}
+function render() {
+  if (!overlayEl) return;
+  spinnerFrame++;
+  const ctrl = getActiveController();
+  if (!ctrl) {
+    lastSnapshot = null;
+    overlayEl.innerHTML = headerHtml() + (minified ? "" : `<div style="opacity:.65">No active session.</div>`);
+    attachHandlers();
+    return;
+  }
+  const s = ctrl.getDebugSnapshot();
+  lastSnapshot = s;
+  if (minified) {
+    overlayEl.innerHTML = headerHtml();
+    attachHandlers();
+    return;
+  }
+  overlayEl.innerHTML = headerHtml() + replanHtml(s) + metaHtml(s) + hintsHtml(s.sessionHints) + queueHtml("reviewQ", "reviewQ", s.reviewQ) + queueHtml("newQ", "newQ", s.newQ) + queueHtml("failedQ", "failedQ", s.failedQ) + drawnHtml("drawn", s.drawnCards);
+  attachHandlers();
+}
+function attachHandlers() {
+  if (!overlayEl) return;
+  overlayEl.querySelectorAll("[data-q]").forEach((el) => {
+    el.onclick = () => {
+      const key = el.dataset.q;
+      if (!key) return;
+      expanded[key] = !expanded[key];
+      render();
+    };
+  });
+  const copyBtn = overlayEl.querySelector("[data-copy]");
+  if (copyBtn) {
+    copyBtn.onclick = (ev) => {
+      ev.stopPropagation();
+      copySnapshot();
+    };
+  }
+  const minBtn = overlayEl.querySelector("[data-min]");
+  if (minBtn) {
+    minBtn.onclick = (ev) => {
+      ev.stopPropagation();
+      minified = !minified;
+      render();
+    };
+  }
+}
+function copySnapshot() {
+  const text = snapshotToText(lastSnapshot);
+  const flash = () => {
+    copyFlashUntil = Date.now() + 1200;
+    render();
+  };
+  const clip = typeof navigator !== "undefined" ? navigator.clipboard : void 0;
+  if (clip?.writeText) {
+    clip.writeText(text).then(flash, (err) => {
+      logger.warn(`[Session Overlay] Clipboard write failed: ${String(err)}`);
+    });
+  } else {
+    logger.info(`[Session Overlay] Clipboard unavailable; snapshot follows:
+${text}`);
+  }
+}
+function headerHtml() {
+  const flashing = Date.now() < copyFlashUntil;
+  const btnLabel = flashing ? "\u2713 copied" : "\u2398 copy";
+  const btnColor = flashing ? "#86efac" : "#93c5fd";
+  const copyBtn = `<span data-copy style="cursor:pointer;float:right;font-weight:400;color:${btnColor};border:1px solid currentColor;border-radius:4px;padding:0 4px;line-height:1.3">${btnLabel}</span>`;
+  const minBtn = `<span data-min title="${minified ? "Restore" : "Minify"}" style="cursor:pointer;float:right;font-weight:400;color:#93c5fd;border:1px solid currentColor;border-radius:4px;padding:0 5px;margin-right:4px;line-height:1.3">${minified ? "\u25A2" : "\u2014"}</span>`;
+  return `<div style="font-weight:600;color:#93c5fd;margin-bottom:${minified ? 0 : 4}px">${copyBtn}${minBtn}\u2699 SessionController</div>`;
+}
+function replanHtml(s) {
+  if (!s.replanActive) {
+    return `<div style="margin-bottom:6px;opacity:.45">\u25CB idle</div>`;
+  }
+  const frame = SPINNER_FRAMES[spinnerFrame % SPINNER_FRAMES.length];
+  const reason = esc(s.replanLabel ?? "(auto)");
+  return `<div style="margin-bottom:6px;color:#fde047">${frame} replanning <span style="opacity:.85">[${reason}]</span></div>`;
+}
+function metaHtml(s) {
+  const mmss = formatTime(s.secondsRemaining);
+  const guarantee = s.hasCardGuarantee ? ` \xB7 <span style="color:#fbbf24">guarantee ${s.minCardsGuarantee}</span>` : "";
+  const rows = [
+    `time ${mmss}${guarantee}`,
+    `well-indicated left: ${s.wellIndicatedRemaining}`,
+    `current: ${s.currentCard ? esc(s.currentCard) : '<span style="opacity:.6">\u2014</span>'}`
+  ];
+  return `<div style="margin-bottom:6px">${rows.map((r) => `<div>${r}</div>`).join("")}</div>`;
+}
+function hintsHtml(h) {
+  const parts = [];
+  if (h) {
+    if (h.boostTags && Object.keys(h.boostTags).length) {
+      parts.push(
+        `boost: ` + Object.entries(h.boostTags).map(([k, v]) => `${esc(k)}<span style="opacity:.6">\xD7${v}</span>`).join(", ")
+      );
+    }
+    if (h.boostCards && Object.keys(h.boostCards).length) {
+      parts.push(
+        `boostCards: ` + Object.entries(h.boostCards).map(([k, v]) => `${esc(k)}<span style="opacity:.6">\xD7${v}</span>`).join(", ")
+      );
+    }
+    if (h.requireCards?.length) parts.push(`require: ${h.requireCards.map(esc).join(", ")}`);
+    if (h.requireTags?.length) parts.push(`requireTags: ${h.requireTags.map(esc).join(", ")}`);
+    if (h.excludeTags?.length) parts.push(`exclude: ${h.excludeTags.map(esc).join(", ")}`);
+    if (h.excludeCards?.length) parts.push(`excludeCards: ${h.excludeCards.map(esc).join(", ")}`);
+  }
+  const body = parts.length ? parts.map((p) => `<div style="margin-left:6px">${p}</div>`).join("") : `<div style="margin-left:6px;opacity:.6">none</div>`;
+  return `<div style="margin-bottom:6px"><div style="color:#86efac">sessionHints</div>${body}</div>`;
+}
+function queueHtml(key, label, q) {
+  const collapsible = q.length > INLINE_THRESHOLD;
+  const isOpen = collapsible && expanded[key];
+  const caret = collapsible ? expanded[key] ? "\u25BE " : "\u25B8 " : "";
+  const drawn = q.dequeueCount ? ` <span style="opacity:.5">drawn ${q.dequeueCount}</span>` : "";
+  const titleStyle = collapsible ? "cursor:pointer;color:#f9a8d4" : "color:#f9a8d4";
+  const titleAttr = collapsible ? ` data-q="${key}"` : "";
+  const title = `<div${titleAttr} style="${titleStyle}">${caret}${label}: ${q.length}${drawn}</div>`;
+  if (!q.cards.length) {
+    return title + `<div style="margin:1px 0 6px 6px;opacity:.5">empty</div>`;
+  }
+  const shown = isOpen ? q.cards : q.cards.slice(0, INLINE_THRESHOLD);
+  const hiddenCount = q.length - shown.length;
+  const listMarginBottom = collapsible ? 2 : 6;
+  let body = `<ol style="margin:2px 0 ${listMarginBottom}px 0;padding-left:20px">` + shown.map((c) => `<li style="white-space:nowrap">${esc(c)}</li>`).join("") + `</ol>`;
+  if (collapsible) {
+    const footer = isOpen ? "\u25BE show less" : `\u2026 +${hiddenCount} more`;
+    body += `<div data-q="${key}" style="cursor:pointer;margin:0 0 6px 20px;opacity:.6">${footer}</div>`;
+  }
+  return title + body;
+}
+function outcomeGlyph(correct) {
+  if (correct === true) return `<span style="color:#86efac">\u2713</span>`;
+  if (correct === false) return `<span style="color:#fca5a5">\u2717</span>`;
+  return `<span style="opacity:.5">\xB7</span>`;
+}
+function drawnHtml(key, drawn) {
+  const collapsible = drawn.length > INLINE_THRESHOLD;
+  const isOpen = collapsible && expanded[key];
+  const caret = collapsible ? expanded[key] ? "\u25BE " : "\u25B8 " : "";
+  const titleStyle = collapsible ? "cursor:pointer;color:#c4b5fd" : "color:#c4b5fd";
+  const titleAttr = collapsible ? ` data-q="${key}"` : "";
+  const title = `<div${titleAttr} style="${titleStyle}">${caret}drawn: ${drawn.length}</div>`;
+  if (!drawn.length) {
+    return title + `<div style="margin:1px 0 6px 6px;opacity:.5">none yet</div>`;
+  }
+  const shown = isOpen ? drawn : drawn.slice(0, INLINE_THRESHOLD);
+  const hiddenCount = drawn.length - shown.length;
+  const listMarginBottom = collapsible ? 2 : 6;
+  const rows = shown.map((d) => {
+    const retries = d.attempts > 1 ? `<span style="opacity:.5"> \xD7${d.attempts}</span>` : "";
+    const time = `<span style="opacity:.45"> ${Math.round(d.timeSpentMs / 100) / 10}s</span>`;
+    return `<li style="white-space:nowrap">${outcomeGlyph(d.correct)} ${esc(d.cardID)}<span style="opacity:.5"> [${esc(d.status)}]</span>${retries}${time}</li>`;
+  }).join("");
+  let body = `<ol style="margin:2px 0 ${listMarginBottom}px 0;padding-left:20px">${rows}</ol>`;
+  if (collapsible) {
+    const footer = isOpen ? "\u25BE show less" : `\u2026 +${hiddenCount} more`;
+    body += `<div data-q="${key}" style="cursor:pointer;margin:0 0 6px 20px;opacity:.6">${footer}</div>`;
+  }
+  return title + body;
+}
+function snapshotToText(s) {
+  if (!s) return "SessionController \u2014 no active session.";
+  const lines = [];
+  lines.push("=== SessionController ===");
+  lines.push(`time ${formatTime(s.secondsRemaining)}`);
+  if (s.hasCardGuarantee) lines.push(`guarantee: ${s.minCardsGuarantee}`);
+  lines.push(`well-indicated left: ${s.wellIndicatedRemaining}`);
+  lines.push(`current: ${s.currentCard ?? "\u2014"}`);
+  lines.push(
+    s.replanActive ? `replan: ACTIVE [${s.replanLabel ?? "(auto)"}]` : "replan: idle"
+  );
+  lines.push("");
+  lines.push("sessionHints:");
+  const h = s.sessionHints;
+  const hintParts = [];
+  if (h) {
+    if (h.boostTags && Object.keys(h.boostTags).length)
+      hintParts.push(`  boost: ${Object.entries(h.boostTags).map(([k, v]) => `${k}\xD7${v}`).join(", ")}`);
+    if (h.boostCards && Object.keys(h.boostCards).length)
+      hintParts.push(`  boostCards: ${Object.entries(h.boostCards).map(([k, v]) => `${k}\xD7${v}`).join(", ")}`);
+    if (h.requireCards?.length) hintParts.push(`  require: ${h.requireCards.join(", ")}`);
+    if (h.requireTags?.length) hintParts.push(`  requireTags: ${h.requireTags.join(", ")}`);
+    if (h.excludeTags?.length) hintParts.push(`  exclude: ${h.excludeTags.join(", ")}`);
+    if (h.excludeCards?.length) hintParts.push(`  excludeCards: ${h.excludeCards.join(", ")}`);
+  }
+  lines.push(hintParts.length ? hintParts.join("\n") : "  none");
+  const queueText = (label, q) => {
+    lines.push("");
+    lines.push(`${label}: ${q.length} (drawn ${q.dequeueCount})`);
+    q.cards.forEach((c, i) => lines.push(`  ${i + 1}. ${c}`));
+  };
+  queueText("reviewQ", s.reviewQ);
+  queueText("newQ", s.newQ);
+  queueText("failedQ", s.failedQ);
+  lines.push("");
+  lines.push(`drawn: ${s.drawnCards.length}`);
+  s.drawnCards.forEach((d, i) => {
+    const mark = d.correct === true ? "\u2713" : d.correct === false ? "\u2717" : "\xB7";
+    const time = `${Math.round(d.timeSpentMs / 100) / 10}s`;
+    lines.push(`  ${i + 1}. ${mark} ${d.cardID} [${d.status}] \xD7${d.attempts} ${time}`);
+  });
+  return lines.join("\n");
+}
+function formatTime(totalSeconds) {
+  const s = Math.max(0, Math.round(totalSeconds));
+  const m = Math.floor(s / 60);
+  const r = s % 60;
+  return `${m}:${r.toString().padStart(2, "0")}`;
+}
+function esc(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+// src/study/SessionDebugger.ts
 var activeSession = null;
 var sessionHistory = [];
 var MAX_HISTORY = 5;
@@ -13234,6 +13523,13 @@ var sessionDebugAPI = {
   showQueue() {
     showCurrentQueue();
   },
+  /**
+   * Toggle the pinned, live-updating DOM overlay for the active controller
+   * (queues, session hints, timer). No-ops in non-browser hosts.
+   */
+  dbgOverlay() {
+    toggleSessionOverlay();
+  },
   /**
    * Show presentation history for current or past session.
    */
@@ -13295,6 +13591,7 @@ var sessionDebugAPI = {
 \u{1F3AF} Session Debug API
 
 Commands:
+  .dbgOverlay()             Toggle the pinned live overlay (queues, hints, timer)
   .showQueue()              Show current queue state (active session only)
   .showHistory(index?)      Show presentation history (0=current/last, 1=previous, etc)
   .showInterleaving(index?) Analyze course interleaving pattern
@@ -13363,6 +13660,13 @@ var SessionController = class _SessionController extends Loggable {
    * Used by nextCard() to await completion before drawing from queues.
    */
   _replanPromise = null;
+  /**
+   * Reason for the replan currently executing in `_runReplan`, surfaced by the
+   * debug overlay's spinner. The caller's `opts.label` when present, else
+   * `'(auto)'`. Only meaningful while `_replanPromise` is non-null; cleared
+   * when the in-flight chain settles.
+   */
+  _activeReplanLabel = null;
   /**
    * Number of well-indicated new cards remaining before the queue
    * degrades to poorly-indicated content. Decremented on each newQ
@@ -13397,6 +13701,21 @@ var SessionController = class _SessionController extends Loggable {
    * recomputed per-run in `_runReplan` and would otherwise go stale.
    */
   _sessionHints = null;
+  /**
+   * Card IDs that have been *served* (drawn/consumed) this session. Populated
+   * at the single consumption choke-point (removeItemFromQueue), so it reflects
+   * a draw the instant it happens — earlier than `_sessionRecord`, which only
+   * lands once the card is *responded to*.
+   *
+   * Used to keep already-served cards out of newQ on every (re)plan: a `new`
+   * card shown once must never re-enter newQ this session. This is the general
+   * guard against re-presentation — including the case where a replan in flight
+   * captured a now-drawn card (e.g. a +INF require-injected follow-up the
+   * depletion prefetch grabbed just before it was drawn). Reviews/failed cards
+   * legitimately recur and are tracked by their own queues, so this only gates
+   * `new`-origin candidates.
+   */
+  _servedCardIds = /* @__PURE__ */ new Set();
   /**
    * Consumer-supplied hooks invoked after each question response is processed.
    * Seeded from constructor options (threaded from
@@ -13475,6 +13794,7 @@ var SessionController = class _SessionController extends Loggable {
     endTime: ${this.endTime}
     defaultBatchLimit: ${this._defaultBatchLimit}
     initialReviewCap: ${this._initialReviewCap}`);
+    registerActiveController(this);
   }
   tick() {
     this._secondsRemaining = Math.floor((this.endTime.valueOf() - Date.now()) / 1e3);
@@ -13575,15 +13895,23 @@ var SessionController = class _SessionController extends Loggable {
       );
       const inflight = this._replanPromise;
       const queued = inflight.catch(() => void 0).then(() => this._runReplan(opts));
-      this._replanPromise = queued.finally(() => {
-        if (this._replanPromise === queued) this._replanPromise = null;
+      const tracked2 = queued.finally(() => {
+        if (this._replanPromise === tracked2) {
+          this._replanPromise = null;
+          this._activeReplanLabel = null;
+        }
       });
+      this._replanPromise = tracked2;
       return queued;
     }
     const run = this._runReplan(opts);
-    this._replanPromise = run.finally(() => {
-      if (this._replanPromise === run) this._replanPromise = null;
+    const tracked = run.finally(() => {
+      if (this._replanPromise === tracked) {
+        this._replanPromise = null;
+        this._activeReplanLabel = null;
+      }
     });
+    this._replanPromise = tracked;
     await run;
   }
   /**
@@ -13592,12 +13920,12 @@ var SessionController = class _SessionController extends Loggable {
    * triggers in nextCard) return false and may coalesce.
    */
   _replanHasIntent(opts) {
-    if (opts.label) return true;
     if (opts.limit !== void 0) return true;
     if (opts.minFollowUpCards !== void 0) return true;
     if (opts.mode && opts.mode !== "replace") return true;
     if (opts.hints && Object.keys(opts.hints).length > 0) return true;
     if (opts.sessionHints !== void 0) return true;
+    if (opts.mergeSessionHints !== void 0) return true;
     return false;
   }
   /**
@@ -13613,6 +13941,7 @@ var SessionController = class _SessionController extends Loggable {
    * newQ.peek(0) is the imminent draw we need to exclude.
    */
   async _runReplan(opts) {
+    this._activeReplanLabel = opts.label ?? "(auto)";
     if (!opts.hints) opts.hints = {};
     const hints = opts.hints;
     const excludeSet = new Set(hints.excludeCards ?? []);
@@ -13632,6 +13961,10 @@ var SessionController = class _SessionController extends Loggable {
         `[Replan] Session hints ${opts.sessionHints ? "set" : "cleared"}: ${JSON.stringify(opts.sessionHints)}`
       );
     }
+    if (opts.mergeSessionHints !== void 0) {
+      this._sessionHints = mergeHints2([this._sessionHints, opts.mergeSessionHints]) ?? null;
+      this.log(`[Replan] Session hints merged: ${JSON.stringify(this._sessionHints)}`);
+    }
     this._applyHintsToSources(opts.hints, opts.label);
     const labelTag = opts.label ? ` [${opts.label}]` : "";
     this.log(
@@ -13670,6 +14003,45 @@ var SessionController = class _SessionController extends Loggable {
   getSessionHints() {
     return this._sessionHints;
   }
+  /**
+   * Live state snapshot for the debug overlay (window.skuilder.session
+   * .dbgOverlay()). Reads directly from the private queues and hints, so it
+   * always reflects the current moment — unlike the passive SessionDebugger
+   * snapshots, which only capture what was explicitly pushed to them.
+   */
+  getDebugSnapshot() {
+    const describe = (q) => {
+      const cards = [];
+      for (let i = 0; i < q.length; i++) {
+        cards.push(q.peek(i).cardID);
+      }
+      return { length: q.length, dequeueCount: q.dequeueCount, cards };
+    };
+    const drawnCards = this._sessionRecord.map((r) => {
+      const last = r.records[r.records.length - 1];
+      return {
+        cardID: r.item.cardID,
+        status: r.item.status,
+        attempts: r.records.length,
+        correct: last && isQuestionRecord(last) ? last.isCorrect : null,
+        timeSpentMs: r.records.reduce((sum, rec) => sum + rec.timeSpent, 0)
+      };
+    });
+    return {
+      secondsRemaining: this.secondsRemaining,
+      hasCardGuarantee: this.hasCardGuarantee,
+      minCardsGuarantee: this._minCardsGuarantee,
+      wellIndicatedRemaining: this._wellIndicatedRemaining,
+      currentCard: this._currentCard?.item.cardID ?? null,
+      sessionHints: this._sessionHints,
+      replanActive: this._replanPromise !== null,
+      replanLabel: this._activeReplanLabel,
+      reviewQ: describe(this.reviewQ),
+      newQ: describe(this.newQ),
+      failedQ: describe(this.failedQ),
+      drawnCards
+    };
+  }
   /**
    * Merge `hints` into the durable session hints via the pipeline's
    * `mergeHints` (boosts multiply, require/exclude lists concat-dedup).
@@ -13751,9 +14123,13 @@ var SessionController = class _SessionController extends Loggable {
    */
   async _replanUncoalesced(opts) {
     const run = this._runReplan(opts);
-    this._replanPromise = run.finally(() => {
-      if (this._replanPromise === run) this._replanPromise = null;
+    const tracked = run.finally(() => {
+      if (this._replanPromise === tracked) {
+        this._replanPromise = null;
+        this._activeReplanLabel = null;
+      }
     });
+    this._replanPromise = tracked;
     await run;
   }
   /**
@@ -13972,7 +14348,7 @@ var SessionController = class _SessionController extends Loggable {
       mixedWeighted
     );
     const reviewWeighted = mixedWeighted.filter((w) => getCardOrigin(w) === "review").slice(0, this._initialReviewCap);
-    const newWeighted = mixedWeighted.filter((w) => getCardOrigin(w) === "new").slice(0, newLimit);
+    const newWeighted = mixedWeighted.filter((w) => getCardOrigin(w) === "new" && !this._servedCardIds.has(w.cardId)).slice(0, newLimit);
     logger.debug(`[reviews] got ${reviewWeighted.length} reviews from mixer`);
     let report = replan ? "Replan content:\n" : "Mixed content session created with:\n";
     if (!replan) {
@@ -14109,14 +14485,14 @@ var SessionController = class _SessionController extends Loggable {
       this.log(
         `[AutoReplan:depletion] newQ has ${this.newQ.length} card(s) (${otherContent} in other queues) with ${this._secondsRemaining}s remaining. Triggering background replan.`
       );
-      void this.requestReplan();
+      void this.requestReplan({ label: "auto:depletion", mode: "merge" });
     }
     const REPLAN_BUFFER = 3;
     if (!this._suppressQualityReplan && this._wellIndicatedRemaining <= REPLAN_BUFFER && this.newQ.length > 0 && !this._replanPromise) {
       this.log(
         `[AutoReplan:quality] ${this._wellIndicatedRemaining} well-indicated cards remaining (newQ: ${this.newQ.length}). Triggering background replan.`
       );
-      void this.requestReplan();
+      void this.requestReplan({ label: "auto:quality" });
     }
     if (this._secondsRemaining <= 0 && this.failedQ.length === 0 && this._minCardsGuarantee <= 0) {
       this._currentCard = null;
@@ -14250,6 +14626,8 @@ var SessionController = class _SessionController extends Loggable {
    * Remove an item from its source queue after consumption by nextCard().
    */
   removeItemFromQueue(item) {
+    this._clearDurableRequirement(item.cardID);
+    this._servedCardIds.add(item.cardID);
     if (this.reviewQ.peek(0)?.cardID === item.cardID) {
       this.reviewQ.dequeue((queueItem) => queueItem.cardID);
     } else if (this.newQ.peek(0)?.cardID === item.cardID) {
@@ -14261,6 +14639,27 @@ var SessionController = class _SessionController extends Loggable {
       this.failedQ.dequeue((queueItem) => queueItem.cardID);
     }
   }
+  /**
+   * Remove a satisfied card ID from the durable session-hint `requireCards`
+   * list. Called when a card is consumed (see removeItemFromQueue). No-op if
+   * the card was not a durable requirement.
+   *
+   * Matches literal IDs only: a glob/pattern requirement (which may stand for
+   * several cards) is NOT considered satisfied by a single draw and is left in
+   * place — durable patterns are the caller's responsibility, one-shot `hints`
+   * remain the right tool for them.
+   */
+  _clearDurableRequirement(cardID) {
+    const req = this._sessionHints?.requireCards;
+    if (!req || req.length === 0) return;
+    const next = req.filter((id) => id !== cardID);
+    if (next.length === req.length) return;
+    this._sessionHints = {
+      ...this._sessionHints,
+      requireCards: next.length > 0 ? next : void 0
+    };
+    this.log(`[Replan] Durable requirement satisfied & cleared on draw: ${cardID}`);
+  }
   /**
    * End the session and record learning outcomes.
    *