@vue-skuilder/db 0.2.2 → 0.2.4

package/dist/{types-W8n-B6HG.d.cts → types-BFUa1pa3.d.cts}

@@ -1,5 +1,5 @@
 import { CourseConfig } from '@vue-skuilder/common';
-import { D as DocType } from './types-legacy-JXDxinpU.cjs';
+import { D as DocType } from './types-legacy-4tlwHnXo.cjs';
 
 interface StaticCourseManifest {
     version: string;

package/dist/{types-CJrLM1Ew.d.ts → types-CHgpWQAY.d.ts}

@@ -1,5 +1,5 @@
 import { CourseConfig } from '@vue-skuilder/common';
-import { D as DocType } from './types-legacy-JXDxinpU.js';
+import { D as DocType } from './types-legacy-4tlwHnXo.js';
 
 interface StaticCourseManifest {
     version: string;

package/dist/{types-legacy-JXDxinpU.d.cts → types-legacy-4tlwHnXo.d.cts}

@@ -157,4 +157,4 @@ interface QuestionRecord extends CardRecord, Evaluation {
     priorAttemps: number;
 }
 
-export { type CardHistory as C, DocType as D, type Field as F, GuestUsername as G, type QualifiedCardID as Q, type SkuilderCourseData as S, type TagStub as T, type Tag as a, DocTypePrefixes as b, type CardRecord as c, type CardData as d, type CourseListData as e, type DisplayableData as f, type DataShapeData as g, type QuestionData as h, type QuestionRecord as i, log as l };
+export { type CardHistory as C, DocType as D, type Field as F, GuestUsername as G, type QualifiedCardID as Q, type SkuilderCourseData as S, type TagStub as T, type Tag as a, DocTypePrefixes as b, type CardRecord as c, type QuestionRecord as d, type CardData as e, type CourseListData as f, type DisplayableData as g, type DataShapeData as h, type QuestionData as i, log as l };

package/dist/{types-legacy-JXDxinpU.d.ts → types-legacy-4tlwHnXo.d.ts}

@@ -157,4 +157,4 @@ interface QuestionRecord extends CardRecord, Evaluation {
     priorAttemps: number;
 }
 
-export { type CardHistory as C, DocType as D, type Field as F, GuestUsername as G, type QualifiedCardID as Q, type SkuilderCourseData as S, type TagStub as T, type Tag as a, DocTypePrefixes as b, type CardRecord as c, type CardData as d, type CourseListData as e, type DisplayableData as f, type DataShapeData as g, type QuestionData as h, type QuestionRecord as i, log as l };
+export { type CardHistory as C, DocType as D, type Field as F, GuestUsername as G, type QualifiedCardID as Q, type SkuilderCourseData as S, type TagStub as T, type Tag as a, DocTypePrefixes as b, type CardRecord as c, type QuestionRecord as d, type CardData as e, type CourseListData as f, type DisplayableData as g, type DataShapeData as h, type QuestionData as i, log as l };

package/dist/util/packer/index.d.cts

@@ -1,5 +1,5 @@
-export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-W8n-B6HG.cjs';
-export { C as CouchDBToStaticPacker } from '../../index-Ba7hYbHj.cjs';
+export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-BFUa1pa3.cjs';
+export { C as CouchDBToStaticPacker } from '../../index-k9NFHpS1.cjs';
 import '@vue-skuilder/common';
-import '../../types-legacy-JXDxinpU.cjs';
+import '../../types-legacy-4tlwHnXo.cjs';
 import 'moment';

package/dist/util/packer/index.d.ts

@@ -1,5 +1,5 @@
-export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-CJrLM1Ew.js';
-export { C as CouchDBToStaticPacker } from '../../index-BWvO-_rJ.js';
+export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-CHgpWQAY.js';
+export { C as CouchDBToStaticPacker } from '../../index-BLLT5BYE.js';
 import '@vue-skuilder/common';
-import '../../types-legacy-JXDxinpU.js';
+import '../../types-legacy-4tlwHnXo.js';
 import 'moment';

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Database layer for vue-skuilder",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@nilock2/pouchdb-authentication": "^1.0.2",
-    "@vue-skuilder/common": "0.2.2",
+    "@vue-skuilder/common": "0.2.4",
     "cross-fetch": "^4.1.0",
     "moment": "^2.29.4",
     "pouchdb": "^9.0.0",
@@ -62,5 +62,5 @@
     "vite": "^8.0.0",
     "vitest": "^4.1.0"
   },
-  "stableVersion": "0.2.2"
+  "stableVersion": "0.2.4"
 }

package/src/core/navigators/Pipeline.ts

@@ -48,7 +48,7 @@ function cardMatchesTagPattern(card: WeightedCard, pattern: string): boolean {
   return (card.tags ?? []).some((tag) => globMatch(tag, pattern));
 }
 
-function mergeHints(allHints: Array<ReplanHints | null | undefined>): ReplanHints | undefined {
+export function mergeHints(allHints: Array<ReplanHints | null | undefined>): ReplanHints | undefined {
   const defined = allHints.filter((h): h is ReplanHints => h !== null && h !== undefined);
   if (defined.length === 0) return undefined;
 

package/src/study/SessionController.ts

@@ -12,14 +12,16 @@ import {
   StudySessionReviewItem,
 } from '@db/impl/couch';
 
-import { CardRecord, CardHistory, CourseRegistrationDoc, QuestionRecord } from '@db/core';
+import { CardRecord, CardHistory, CourseRegistrationDoc, QuestionRecord, isQuestionRecord } from '@db/core';
 import { recordUserOutcome } from '@db/core/orchestration/recording';
 import { Loggable } from '@db/util';
 import { getCardOrigin } from '@db/core/navigators';
 import { ReplanHints } from '@db/core/navigators/generators/types';
+import { mergeHints } from '@db/core/navigators/Pipeline';
 import { SourceMixer, QuotaRoundRobinMixer, SourceBatch } from './SourceMixer';
 import { captureMixerRun } from './MixerDebugger';
 import { startSessionTracking, recordCardPresentation, snapshotQueues, endSessionTracking } from './SessionDebugger';
+import { registerActiveController, type SessionDebugSnapshot, type SessionQueueDebug } from './SessionOverlay';
 
 // ReplanHints is defined in generators/types to avoid circular dependencies.
 // Re-exported here for backward compatibility.
@@ -35,6 +37,28 @@ export type { ReplanHints } from '@db/core/navigators/generators/types';
 export interface ReplanOptions {
   /** Scoring hints forwarded to the pipeline (boost/exclude/require). */
   hints?: ReplanHints;
+  /**
+   * Session-durable scoring hints. Unlike `hints` (one-shot, applied to
+   * exactly the run this replan triggers), `sessionHints` are stashed on
+   * the controller and re-merged into *every* subsequent pipeline run for
+   * the remainder of the session — including the bare auto-replans
+   * (depletion/quality) that carry no caller hints, and the wedge-breaker.
+   *
+   * Use for "emphasis that should outlive a single queue rebuild" — e.g.
+   * boosting a just-failed concept tag, or a post-lesson concept boost set
+   * at session start. Without this, a one-shot `hints` boost evaporates on
+   * the next replan and the freshly-rebuilt (replace-mode) queue clobbers
+   * whatever it surfaced.
+   *
+   * Semantics (KISS): setting `sessionHints` *replaces* the prior session
+   * hints wholesale (caller beware — no accumulation, no decay). They live
+   * until session end or until explicitly overwritten. Normal usage applies
+   * a fixed boost, so repeated identical requests are no-ops.
+   *
+   * Merged with per-run `hints` via the pipeline's `mergeHints` (boosts
+   * multiply, require/exclude lists concatenate).
+   */
+  sessionHints?: ReplanHints;
   /**
    * Maximum number of new cards to return from the pipeline.
    * Default: 20 (the standard session batch size).
@@ -102,6 +126,64 @@ export interface ResponseResult {
   shouldClearFeedbackShadow: boolean;
 }
 
+/**
+ * Read-only snapshot of a single processed response, handed to every
+ * registered {@link OutcomeObserver} after ELO/SRS have been recorded.
+ *
+ * Only emitted for question records (non-question dismisses are skipped).
+ */
+export interface SessionOutcome {
+  /** The user's response. Includes `isCorrect`, `performance`, `priorAttemps`. */
+  readonly record: QuestionRecord;
+  /**
+   * The card that was answered, including its `tags` — the primary key an
+   * observer matches against (e.g. `gpc:exercise:*`). `card_elo` reflects
+   * pre-update state; the ELO write for this response is already in flight.
+   */
+  readonly card: StudySessionRecord['card'];
+  /** The navigation decision produced for this response (read-only). */
+  readonly result: Readonly<ResponseResult>;
+}
+
+/**
+ * The narrow capability surface handed to an {@link OutcomeObserver}. This is
+ * the *only* way an observer can affect the session — it cannot touch ELO,
+ * the queues, the timer, or mutate the `ResponseResult`. A misbehaving
+ * observer degrades to "wrong boost", never "corrupted session".
+ */
+export interface SessionControls {
+  /** Current session-durable hints, or null. For read-modify-write. */
+  getSessionHints(): ReplanHints | null;
+  /** Replace the session-durable hints wholesale (no decay). */
+  setSessionHints(hints: ReplanHints | null): void;
+  /**
+   * Merge `hints` into the existing session-durable hints via the pipeline's
+   * `mergeHints` (boosts multiply, require/exclude lists concat-dedup).
+   * Convenience for the common "add a boost on top of what's there" case.
+   * Note: multiplicative + no decay — clamp boost factors yourself if a
+   * repeatedly-failed tag could compound unboundedly.
+   */
+  mergeSessionHints(hints: ReplanHints): void;
+  /** Request a replan (e.g. `{ mode: 'merge' }` for immediate visibility). */
+  requestReplan(opts?: ReplanOptions): Promise<void>;
+}
+
+/**
+ * A consumer-supplied hook invoked after each question response is processed.
+ *
+ * Fires on *every* question response (gate inside on `record.isCorrect` /
+ * `result.nextCardAction` as needed). Awaited but isolated: a throwing
+ * observer is caught and logged, never wedging the session. Keep the
+ * synchronous body cheap and `void` any long work (e.g. a triggered replan)
+ * so you don't stall navigation.
+ *
+ * Registered via `StudySessionConfig.outcomeObservers` → constructor options.
+ */
+export type OutcomeObserver = (
+  outcome: SessionOutcome,
+  controls: SessionControls
+) => void | Promise<void>;
+
 interface SessionServices {
   response: ResponseProcessor;
 }
@@ -155,6 +237,14 @@ export class SessionController<TView = unknown> extends Loggable {
    */
   private _replanPromise: Promise<void> | null = 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.
+   */
+  private _activeReplanLabel: string | null = null;
+
   /**
    * Number of well-indicated new cards remaining before the queue
    * degrades to poorly-indicated content. Decremented on each newQ
@@ -177,6 +267,35 @@ export class SessionController<TView = unknown> extends Loggable {
    */
   private _minCardsGuarantee: number = 0;
 
+  /**
+   * Session-durable scoring hints. Re-merged into every pipeline run for
+   * the rest of the session (initial plan + every replan, including bare
+   * auto-replans and the wedge-breaker), via `_applyHintsToSources`.
+   *
+   * Set by `setSessionHints()` (e.g. session-start post-lesson boost) or by
+   * any replan carrying `ReplanOptions.sessionHints` (e.g. a just-failed
+   * concept boost). Replace semantics, no decay — lives until overwritten
+   * or session end. See `ReplanOptions.sessionHints` for rationale.
+   *
+   * Note: the controller-managed auto-excludes (current card, session
+   * record, imminent draw) are intentionally NOT folded in here — those are
+   * recomputed per-run in `_runReplan` and would otherwise go stale.
+   */
+  private _sessionHints: ReplanHints | null = null;
+
+  /**
+   * Consumer-supplied hooks invoked after each question response is processed.
+   * Seeded from constructor options (threaded from
+   * `StudySessionConfig.outcomeObservers`). See {@link OutcomeObserver}.
+   */
+  private _outcomeObservers: OutcomeObserver[] = [];
+
+  /**
+   * Lazily-built, stable capability object handed to observers. Bound to
+   * `this`; constructed once so observers can rely on referential identity.
+   */
+  private _sessionControls: SessionControls | null = null;
+
   private startTime: Date;
   private endTime: Date;
   private _secondsRemaining: number;
@@ -219,7 +338,11 @@ export class SessionController<TView = unknown> extends Loggable {
     dataLayer: DataLayerProvider,
     getViewComponent: (viewId: string) => TView,
     mixer?: SourceMixer,
-    options?: { defaultBatchLimit?: number; initialReviewCap?: number }
+    options?: {
+      defaultBatchLimit?: number;
+      initialReviewCap?: number;
+      outcomeObservers?: OutcomeObserver[];
+    }
   ) {
     super();
 
@@ -249,12 +372,20 @@ export class SessionController<TView = unknown> extends Loggable {
     if (options?.initialReviewCap !== undefined) {
       this._initialReviewCap = options.initialReviewCap;
     }
+    if (options?.outcomeObservers?.length) {
+      this._outcomeObservers = [...options.outcomeObservers];
+    }
 
     this.log(`Session constructed:
     startTime: ${this.startTime}
     endTime: ${this.endTime}
     defaultBatchLimit: ${this._defaultBatchLimit}
     initialReviewCap: ${this._initialReviewCap}`);
+
+    // Expose this (now the most-recently-constructed) controller to the debug
+    // overlay (window.skuilder.session.dbgOverlay()). A new session overwrites
+    // the prior handle; no-op overhead when the overlay is never opened.
+    registerActiveController(this);
   }
 
   private tick() {
@@ -383,17 +514,33 @@ export class SessionController<TView = unknown> extends Loggable {
         .catch(() => undefined)
         .then(() => this._runReplan(opts));
 
-      this._replanPromise = queued.finally(() => {
-        if (this._replanPromise === queued) this._replanPromise = null;
+      // Compare against the promise we actually store. `.finally()` returns a
+      // NEW promise, so guarding on `=== queued` (the pre-finally promise) never
+      // matches and would leak _replanPromise. `tracked` is read only inside the
+      // async callback (after init), so the self-reference is safe.
+      const tracked: Promise<void> = queued.finally(() => {
+        if (this._replanPromise === tracked) {
+          this._replanPromise = null;
+          this._activeReplanLabel = null;
+        }
       });
+      this._replanPromise = tracked;
 
       return queued;
     }
 
     const run = this._runReplan(opts);
-    this._replanPromise = run.finally(() => {
-      if (this._replanPromise === run) this._replanPromise = null;
+    // Compare against the wrapped promise we store, not `run` — `.finally()`
+    // returns a new promise, so `=== run` never matches and _replanPromise
+    // would never clear (perpetual "replan in progress"). Safe self-reference:
+    // `tracked` is read only in the async callback, after initialization.
+    const tracked: Promise<void> = run.finally(() => {
+      if (this._replanPromise === tracked) {
+        this._replanPromise = null;
+        this._activeReplanLabel = null;
+      }
     });
+    this._replanPromise = tracked;
 
     await run;
   }
@@ -404,11 +551,17 @@ export class SessionController<TView = unknown> extends Loggable {
    * triggers in nextCard) return false and may coalesce.
    */
   private _replanHasIntent(opts: ReplanOptions): boolean {
-    if (opts.label) return true;
+    // NOTE: `label` is intentionally NOT an intent signal. It is observability-
+    // only metadata (debug overlay spinner, log tags, Pipeline strategy names),
+    // so labelling a replan must never change scheduling. Intent is strictly
+    // "does this replan carry scheduling-relevant options". This lets the
+    // unlabeled-but-named auto-replans (auto:depletion / auto:quality) keep
+    // coalescing while still showing a reason in the overlay.
     if (opts.limit !== undefined) return true;
     if (opts.minFollowUpCards !== undefined) return true;
     if (opts.mode && opts.mode !== 'replace') return true;
     if (opts.hints && Object.keys(opts.hints).length > 0) return true;
+    if (opts.sessionHints !== undefined) return true;
     return false;
   }
 
@@ -425,6 +578,11 @@ export class SessionController<TView = unknown> extends Loggable {
    * newQ.peek(0) is the imminent draw we need to exclude.
    */
   private async _runReplan(opts: ReplanOptions): Promise<void> {
+    // Surface the executing replan's reason to the debug overlay spinner.
+    // `label` is observability-only (see _replanHasIntent); '(auto)' covers any
+    // unlabeled path.
+    this._activeReplanLabel = opts.label ?? '(auto)';
+
     // Exclude all cards already presented this session. The pipeline may
     // not yet see their encounter records (async writes), so without this
     // they can re-enter newQ via replaceAll and cause duplicates.
@@ -455,17 +613,21 @@ export class SessionController<TView = unknown> extends Loggable {
 
     hints.excludeCards = [...excludeSet];
 
-    // Forward hints to all sources (CourseDB stashes them, Pipeline consumes them)
-    if (opts.hints) {
-      // Thread label into hints so Pipeline can attach it to provenance
-      const hintsWithLabel = opts.label
-        ? { ...opts.hints, _label: opts.label }
-        : opts.hints;
-      for (const source of this.sources) {
-        source.setEphemeralHints?.(hintsWithLabel);
-      }
+    // Replace session-durable hints if this replan carries them. KISS:
+    // wholesale replace, no accumulation/decay (see ReplanOptions.sessionHints).
+    if (opts.sessionHints !== undefined) {
+      this._sessionHints = opts.sessionHints;
+      this.log(
+        `[Replan] Session hints ${opts.sessionHints ? 'set' : 'cleared'}: ` +
+        `${JSON.stringify(opts.sessionHints)}`
+      );
     }
 
+    // Forward hints to all sources (CourseDB stashes them, Pipeline consumes
+    // them). The one-shot `opts.hints` are merged with the durable
+    // `_sessionHints` so session emphasis survives this and every later run.
+    this._applyHintsToSources(opts.hints, opts.label);
+
     const labelTag = opts.label ? ` [${opts.label}]` : '';
     this.log(
       `Mid-session replan requested${labelTag}` +
@@ -487,6 +649,146 @@ export class SessionController<TView = unknown> extends Loggable {
     // );
   }
 
+  /**
+   * Set the session-durable scoring hints (replace semantics, no decay).
+   *
+   * Unlike a one-shot replan hint, these are re-merged into every pipeline
+   * run for the rest of the session — including the initial plan when set
+   * before `prepareSession()`, every replan, the bare auto-replans, and the
+   * wedge-breaker. Pass `null` to clear.
+   *
+   * Typical callers:
+   * - `StudySession` at session start, threading `StudySessionConfig.initHints`
+   *   (e.g. a post-lesson concept boost) — so the boost outlives the first
+   *   queue rebuild instead of being clobbered by the first auto-replan.
+   * - A consumer view on a failure, boosting the just-failed concept tag.
+   *
+   * Does not itself trigger a replan; the next plan/replan picks it up.
+   */
+  public setSessionHints(hints: ReplanHints | null): void {
+    this._sessionHints = hints;
+    this.log(`Session hints ${hints ? 'set' : 'cleared'}: ${JSON.stringify(hints)}`);
+  }
+
+  /**
+   * Read the current session-durable hints (for read-modify-write callers,
+   * e.g. an outcome observer that clamps a compounding boost).
+   */
+  public getSessionHints(): ReplanHints | null {
+    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.
+   */
+  public getDebugSnapshot(): SessionDebugSnapshot {
+    const describe = <T extends { cardID: string }>(q: ItemQueue<T>): SessionQueueDebug => {
+      const cards: string[] = [];
+      for (let i = 0; i < q.length; i++) {
+        cards.push(q.peek(i).cardID);
+      }
+      return { length: q.length, dequeueCount: q.dequeueCount, cards };
+    };
+    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),
+    };
+  }
+
+  /**
+   * Merge `hints` into the durable session hints via the pipeline's
+   * `mergeHints` (boosts multiply, require/exclude lists concat-dedup).
+   * Convenience over get-then-set for the common additive case. Note the
+   * multiplicative, no-decay semantics — clamp boost factors at the call
+   * site if a repeatedly-emphasised tag could compound unboundedly.
+   */
+  public mergeSessionHints(hints: ReplanHints): void {
+    this._sessionHints = mergeHints([this._sessionHints, hints]) ?? null;
+    this.log(`Session hints merged: ${JSON.stringify(this._sessionHints)}`);
+  }
+
+  /**
+   * Merge the durable `_sessionHints` with this run's one-shot hints and
+   * push the result to every source for consumption on the next pipeline
+   * run. Centralised so the initial plan and all replan paths apply session
+   * emphasis identically. No-op when there are no hints of either kind.
+   */
+  private _applyHintsToSources(oneShot?: ReplanHints, label?: string): void {
+    // Thread the provenance label into the one-shot layer; mergeHints will
+    // fold it into the combined `_label`.
+    const oneShotWithLabel: ReplanHints | undefined =
+      oneShot && label ? { ...oneShot, _label: label } : oneShot;
+
+    const merged = mergeHints([this._sessionHints, oneShotWithLabel]);
+    if (!merged) return;
+
+    for (const source of this.sources) {
+      source.setEphemeralHints?.(merged);
+    }
+  }
+
+  /**
+   * Build (once) the stable capability object handed to outcome observers.
+   * Methods are bound to `this`; the object identity is stable across calls
+   * so observers may key off it.
+   */
+  private _getSessionControls(): SessionControls {
+    if (!this._sessionControls) {
+      this._sessionControls = {
+        getSessionHints: () => this.getSessionHints(),
+        setSessionHints: (h) => this.setSessionHints(h),
+        mergeSessionHints: (h) => this.mergeSessionHints(h),
+        requestReplan: (opts) => this.requestReplan(opts),
+      };
+    }
+    return this._sessionControls;
+  }
+
+  /**
+   * Notify registered outcome observers about a processed response.
+   *
+   * Only question records are surfaced (non-question dismisses are skipped).
+   * Observers run after ELO/SRS are recorded and before navigation. Each is
+   * awaited but isolated in try/catch — a throwing observer is logged and
+   * skipped, never wedging the session. Keep observers cheap and `void` any
+   * long work (e.g. a triggered replan) to avoid stalling the draw.
+   */
+  private async _notifyOutcomeObservers(
+    record: CardRecord,
+    currentCard: StudySessionRecord,
+    result: ResponseResult
+  ): Promise<void> {
+    if (this._outcomeObservers.length === 0) return;
+    if (!isQuestionRecord(record)) return;
+
+    const outcome: SessionOutcome = {
+      record,
+      card: currentCard.card,
+      result,
+    };
+    const controls = this._getSessionControls();
+
+    for (const observer of this._outcomeObservers) {
+      try {
+        await observer(outcome, controls);
+      } catch (e) {
+        this.error('[OutcomeObserver] observer threw; ignoring', e);
+      }
+    }
+  }
+
   /**
    * Run a replan, bypassing requestReplan()'s coalesce logic.
    *
@@ -501,9 +803,14 @@ export class SessionController<TView = unknown> extends Loggable {
    */
   private async _replanUncoalesced(opts: ReplanOptions): Promise<void> {
     const run = this._runReplan(opts);
-    this._replanPromise = run.finally(() => {
-      if (this._replanPromise === run) this._replanPromise = null;
+    // See requestReplan: guard against the wrapped promise we store, not `run`.
+    const tracked: Promise<void> = run.finally(() => {
+      if (this._replanPromise === tracked) {
+        this._replanPromise = null;
+        this._activeReplanLabel = null;
+      }
     });
+    this._replanPromise = tracked;
     await run;
   }
 
@@ -519,7 +826,7 @@ export class SessionController<TView = unknown> extends Loggable {
     if (!input) return {};
 
     // If the input has any ReplanOptions-specific key, treat it as ReplanOptions
-    const replanKeys = ['hints', 'limit', 'mode', 'label', 'minFollowUpCards'];
+    const replanKeys = ['hints', 'sessionHints', 'limit', 'mode', 'label', 'minFollowUpCards'];
     const inputKeys = Object.keys(input);
     if (inputKeys.some((k) => replanKeys.includes(k))) {
       return input as ReplanOptions;
@@ -706,6 +1013,14 @@ export class SessionController<TView = unknown> extends Loggable {
     // never touch reviewQ, so the inflation is unnecessary there.
     const fetchLimit = replan ? newLimit : newLimit + this._initialReviewCap;
 
+    // Initial plan: push session-durable hints to sources so the very first
+    // pipeline run reflects them (e.g. a post-lesson boost). Replans push
+    // their own session+one-shot merge via _runReplan before reaching here,
+    // so we must NOT re-apply here or we'd drop their per-run excludeCards.
+    if (!replan) {
+      this._applyHintsToSources();
+    }
+
     // Collect batches from each source
     const batches: SourceBatch[] = [];
 
@@ -1031,7 +1346,8 @@ export class SessionController<TView = unknown> extends Loggable {
         `(${otherContent} in other queues) with ${this._secondsRemaining}s remaining. ` +
         `Triggering background replan.`
       );
-      void this.requestReplan();
+      // label is observability-only (overlay/logs); does not affect coalescing.
+      void this.requestReplan({ label: 'auto:depletion' });
     }
 
     // Opportunistic quality: few well-indicated cards remain.
@@ -1047,7 +1363,8 @@ export class SessionController<TView = unknown> extends Loggable {
         `[AutoReplan:quality] ${this._wellIndicatedRemaining} well-indicated cards remaining ` +
         `(newQ: ${this.newQ.length}). Triggering background replan.`
       );
-      void this.requestReplan();
+      // label is observability-only (overlay/logs); does not affect coalescing.
+      void this.requestReplan({ label: 'auto:quality' });
     }
 
     if (this._secondsRemaining <= 0 && this.failedQ.length === 0 && this._minCardsGuarantee <= 0) {
@@ -1192,7 +1509,7 @@ export class SessionController<TView = unknown> extends Loggable {
       ...currentCard.item,
     };
 
-    return await this.services.response.processResponse(
+    const result = await this.services.response.processResponse(
       cardRecord,
       cardHistory,
       studySessionItem,
@@ -1204,6 +1521,14 @@ export class SessionController<TView = unknown> extends Loggable {
       maxSessionViews,
       sessionViews
     );
+
+    // Surface the processed outcome to any registered observers (e.g. a
+    // difficulty-booster that bumps session hints on a failed exercise tag).
+    // Runs after ELO/SRS recording, before the caller navigates. Isolated so
+    // a faulty observer can't break response handling.
+    await this._notifyOutcomeObservers(cardRecord, currentCard, result);
+
+    return result;
   }
 
   private dismissCurrentCard(action: SessionAction = 'dismiss-success') {

package/src/study/SessionDebugger.ts

@@ -1,5 +1,6 @@
 import { logger } from '../util/logger';
 import { clearRunHistory as clearPipelineRunHistory } from '../core/navigators/PipelineDebugger';
+import { toggleSessionOverlay } from './SessionOverlay';
 
 // ============================================================================
 // SESSION DEBUGGER
@@ -344,6 +345,14 @@ export const sessionDebugAPI = {
     showCurrentQueue();
   },
 
+  /**
+   * Toggle the pinned, live-updating DOM overlay for the active controller
+   * (queues, session hints, timer). No-ops in non-browser hosts.
+   */
+  dbgOverlay(): void {
+    toggleSessionOverlay();
+  },
+
   /**
    * Show presentation history for current or past session.
    */
@@ -413,6 +422,7 @@ export const sessionDebugAPI = {
 🎯 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