@dzhechkov/harness-core 0.7.11 → 0.7.12

package/src/feature-adr-routing.ts

@@ -1321,9 +1321,36 @@ export function isSafeCodexId(id: string): boolean {
  * unquoted, so a malformed `args.codexModel` could corrupt or extend the command the agent runs.
  * Reject anything that is not a plain id, and single-quote it anyway.
  */
-export function codexProbeCommand(id: string): string | null {
+/**
+ * Which binary bounds a dispatched run. `timeout(1)` is GNU coreutils and is NOT on macOS; brew's
+ * coreutils installs it as `gtimeout`.
+ *
+ * An ALLOWLIST rather than a free string, because this value is interpolated into a shell command.
+ *
+ * MEASURED 2026-08-25 (field report, and reproduced here): with neither binary present the dispatch
+ * exits 127 and cross-family QE — a NAMED safety property, that the model which wrote the code must
+ * not review it — silently did not happen for a whole run.
+ *
+ * Deliberately NOT the portable `perl -e 'alarm N; exec @ARGV'` the report proposed: MEASURED on
+ * this machine, that form exits **142** (SIGALRM kills the exec'd process) while GNU timeout exits
+ * **124**, and `classifyCodexQeOutcome` keys `timeout` on `exit === 124` — a rule its own comment
+ * says wins over every content rule. The suggested remedy would have silently reclassified every
+ * timeout as a tool error. A remedy that breaks the classifier is worse than the defect.
+ */
+export const TIMEOUT_BINS: Readonly<Record<string, true>> = { timeout: true, gtimeout: true };
+
+/** The requested timeout binary if it is one we allow, else the default. Never a free string. */
+export function timeoutBinOrDefault(bin: unknown): string {
+  const b = typeof bin === 'string' ? bin : '';
+  return TIMEOUT_BINS[b] === true ? b : 'timeout';
+}
+
+export function codexProbeCommand(id: string, timeoutBin?: string): string | null {
   if (!isSafeCodexId(id)) return null;
-  return "timeout 60 codex exec -m '" + id + "' 'Reply with exactly: OK'";
+  // `< /dev/null` is not cosmetic: without it `codex exec` waits on stdin forever (measured
+  // 2026-08-19, 45 minutes lost). It was present in the workflow mirror and MISSING here — a drift
+  // invisible to the suite because this function is not in the lift test's function list.
+  return timeoutBinOrDefault(timeoutBin) + " 60 codex exec -m '" + id + "' 'Reply with exactly: OK' < /dev/null";
 }
 
 export interface CodexProbeOutput {
@@ -1396,6 +1423,9 @@ export function parseCodexExecResult(text: string | null | undefined): CodexExec
 
 /** Mode-A wall-clock bound. Run 3 measured 146 s; 600 s is ~4× headroom and still bounded. */
 export const CODEX_REVIEW_TIMEOUT_SECONDS = 600;
+
+/** The `codex exec` wall-clock bound. Mirrors the workflow's own constant (field report 27). */
+export const CODEX_EXEC_TIMEOUT_SECONDS = 280;
 /** MEASURED (probe 0.3): `codex review` accepts and echoes `reasoning effort: high`. */
 export const CODEX_REVIEW_DEFAULT_EFFORT = 'high';
 /** The sentinel a wrapper returns when the command hit its `timeout` — distinct from CODEX_UNAVAILABLE. */
@@ -1427,6 +1457,22 @@ export interface CodexReviewCommandInput {
   readonly ref?: string | null;
   readonly modelId?: string | null;
   readonly reasoning?: string | null;
+  /**
+   * Which binary bounds the run — `timeout` (default) or `gtimeout` on a mac with brew coreutils.
+   * An INPUT rather than a platform sniff inside the builder, so the function stays pure and every
+   * pinned command string in the tests stays byte-identical when it is omitted.
+   */
+  readonly timeoutBin?: string | null;
+  /**
+   * The repo the review must run IN. Field report 27: `codex review` was dispatched with no working
+   * directory at all, so it ran in the SESSION cwd — on a run against an external checkout it read a
+   * different tree, resolved `--uncommitted` / `--base` against the wrong git repo, and still exited 0
+   * with a `Grade:` line that the pipeline recorded as a verdict. `codex review` has NO `-C` flag
+   * (MEASURED on codex-cli 0.149.1: `codex exec --help` carries `-C, --cd <DIR>`, `codex review --help`
+   * does not), so the working directory can only be set by a `cd` prefix. Omitted ⇒ no prefix, which
+   * keeps every previously pinned command string byte-identical.
+   */
+  readonly repo?: string | null;
   /**
    * Accepted and DELIBERATELY IGNORED. MEASURED 2026-08-21: every scope flag refuses a positional
    * prompt — `--commit`, `--base <BRANCH>` and `--uncommitted` each exit 2 with
@@ -1457,6 +1503,44 @@ export interface CodexReviewCommandResult {
  * Default scope is `uncommitted` (probe 0.4b: it and `--base HEAD` reviewed the identical uncommitted
  * diff, and `uncommitted` needs no ref, so it has no ref-injection surface at all).
  */
+/** Shell-quote one argument. A repo path may contain a space; it must never contain a command. */
+function codexSq(s: string): string {
+  return "'" + String(s).replace(/'/g, "'\\''") + "'";
+}
+
+/**
+ * The `cd <repo> && ` prefix, or `''` when no repo was named. Empty is not a silent default — it is
+ * the pre-2026-08-25 behaviour, preserved so an omitted `repo` keeps every pinned string identical.
+ */
+function codexCd(repo: string): string {
+  return repo === '' ? '' : 'cd ' + codexSq(repo) + ' && ';
+}
+
+/**
+ * The `codex exec` dispatch, built as a pure string so the working directory is pinned by a test
+ * rather than by whichever directory the dispatching agent happened to stand in (field report 27).
+ * `-C` is real on codex-cli 0.149.1 and MEASURED: `-C <this repo>` answered in 4.6 s exit 0, while
+ * `-C /tmp` exited 1 with "Not inside a trusted directory" — so the flag genuinely changes the tree,
+ * and a non-git target is a LOUD failure rather than a quiet read of the wrong one.
+ */
+export function codexExecCommand(input: {
+  readonly modelId?: string | null;
+  readonly prompt?: string | null;
+  readonly timeoutBin?: string | null;
+  readonly timeoutSeconds?: number | null;
+  readonly repo?: string | null;
+}): string | null {
+  const o = input || {};
+  const modelId = String(o.modelId === undefined || o.modelId === null ? '' : o.modelId);
+  if (!isSafeCodexId(modelId)) return null;
+  const raw = Number(o.timeoutSeconds);
+  const seconds = raw === raw && raw !== Infinity && raw > 0 ? Math.floor(raw) : CODEX_EXEC_TIMEOUT_SECONDS;
+  const repo = String(o.repo === undefined || o.repo === null ? '' : o.repo);
+  const cd = repo === '' ? '' : ' -C ' + codexSq(repo);
+  return timeoutBinOrDefault(o.timeoutBin) + ' ' + seconds + ' codex exec' + cd
+    + ' -m ' + codexSq(modelId) + ' ' + codexSq(String(o.prompt === undefined || o.prompt === null ? '' : o.prompt)) + ' < /dev/null';
+}
+
 export function codexReviewCommand(input: CodexReviewCommandInput): CodexReviewCommandResult {
   const o = input || ({} as CodexReviewCommandInput);
   const scope = o.scope === undefined || o.scope === null || o.scope === '' ? 'uncommitted' : String(o.scope);
@@ -1477,7 +1561,8 @@ export function codexReviewCommand(input: CodexReviewCommandInput): CodexReviewC
   }
   const raw = Number(o.timeoutSeconds);
   const seconds = raw === raw && raw !== Infinity && raw > 0 ? Math.floor(raw) : CODEX_REVIEW_TIMEOUT_SECONDS;
-  let cmd = 'timeout ' + seconds + " codex review -c model='" + modelId + "' -c model_reasoning_effort='" + effort + "'";
+  const repo = String(o.repo === undefined || o.repo === null ? '' : o.repo);
+  let cmd = codexCd(repo) + timeoutBinOrDefault(o.timeoutBin) + ' ' + seconds + " codex review -c model='" + modelId + "' -c model_reasoning_effort='" + effort + "'";
   if (scope === 'commit') cmd += " --commit '" + ref + "'";
   else if (scope === 'base') cmd += " --base '" + ref + "'";
   else cmd += ' --uncommitted';
@@ -1662,7 +1747,7 @@ export function gradeFromReviewFindings(findings: readonly CodexQeFinding[] | nu
  * The LOCKED decline taxonomy. A `kind` outside this set is a bug, not a new case — which is why
  * {@link codexQeDeclineReason} throws on one rather than rendering something plausible.
  */
-export const CODEX_QE_DECLINE_KINDS: readonly string[] = ['timeout', 'no-verdict', 'tool-error', 'unusable-output', 'unavailable', 'over-ceiling'];
+export const CODEX_QE_DECLINE_KINDS: readonly string[] = ['timeout', 'no-verdict', 'tool-error', 'unusable-output', 'unavailable', 'over-ceiling', 'wrong-tree'];
 
 export interface ClassifyCodexQeInput {
   readonly exit?: number | null;
@@ -1675,6 +1760,49 @@ export interface ClassifyCodexQeInput {
    * that was never wrapped (a saved fixture, a file on disk), where content is all there is.
    */
   readonly signalExpected?: boolean;
+  /**
+   * The files the dispatch DECLARED it would review. Used only by the wrong-tree rule below; absent
+   * ⇒ that rule cannot fire and the classifier behaves exactly as it did before field report 27.
+   */
+  readonly declaredFiles?: readonly string[] | null;
+}
+
+/**
+ * Did the reviewer fail to FIND the very files it was told to read?
+ *
+ * A review dispatched into the wrong working directory does not error: the paths simply are not
+ * there, the model says so in prose, and the command still exits 0 — often with a `Grade:` line,
+ * which the pipeline then records as a verdict about code nobody read.
+ *
+ * The rule is deliberately narrow, because a review of a file-handling module may legitimately
+ * DISCUSS "No such file or directory" — a mention is not a claim. So it fires only when one LINE
+ * carries both the not-found phrase and one of the declared paths. With no declared paths there is
+ * nothing to discriminate against and the rule stays silent rather than guessing.
+ */
+export function codexReviewMissedItsFiles(body: string | null | undefined, declaredFiles?: readonly string[] | null): boolean {
+  const text = String(body === undefined || body === null ? '' : body);
+  const files = Array.isArray(declaredFiles) ? declaredFiles.filter((f) => typeof f === 'string' && f !== '') : [];
+  if (text === '' || files.length === 0) return false;
+  // Only quotes, whitespace and a colon may sit between the path and the failure. Prose may not —
+  // and that single restriction is what separates "the tool could not open this path" from "this
+  // finding is ABOUT this path": a review finding always names its file, so anything looser marks
+  // every file-handling review as wrong-tree. (Codex, gpt-5.6-sol, on the first version of this
+  // function: the finding line "- [P2] Do not swallow file not found - src/io.ts:42" plus a stated
+  // grade C was classified wrong-tree, discarding a valid cross-family verdict and falling back to
+  // same-family QE — the guard against a false-clean review destroying a true one.)
+  const GAP = '["\'\u2018\u2019\u201c\u201d\u0060(\\[\\s:,]{0,4}';
+  const NOT_FOUND = 'no such file or directory|file not found|not found|does not exist|is not present|cannot be found';
+  const VERB = '(?:cannot|can\'t|could not|couldn\'t|unable to|failed to|error(?: while)?)\\s+(?:open|read|find|access|stat|locate|load)';
+  for (const f of files) {
+    const q = f.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const shapes = [
+      q + GAP + '(?:' + NOT_FOUND + ')',          // src/io.ts: No such file or directory
+      '(?:' + NOT_FOUND + ')' + GAP + q,          // No such file or directory: src/io.ts
+      VERB + GAP + q,                             // cannot open 'src/io.ts'
+    ];
+    for (const shape of shapes) if (new RegExp(shape, 'i').test(text)) return true;
+  }
+  return false;
 }
 
 /**
@@ -1711,6 +1839,10 @@ export function classifyCodexQeOutcome(input: ClassifyCodexQeInput): { kind: str
   } else if (exit !== 0) {
     return { kind: 'tool-error' };
   }
+  // BEFORE the grade rule, and deliberately so: a wrong-tree review usually DOES state a grade, and
+  // that grade is the most dangerous output this pipeline can produce — a clean letter about code
+  // nobody read, recorded while crossFamilyQe.happened stays true.
+  if (codexReviewMissedItsFiles(body, input ? input.declaredFiles : null)) return { kind: 'wrong-tree' };
   if (grade !== null) return { kind: 'verdict' };
   return { kind: 'no-verdict' };
 }
@@ -1750,6 +1882,9 @@ export function codexQeDeclineReason(kind: string | null | undefined, detail?: C
   const exit = d.exit === undefined || d.exit === null ? '?' : String(d.exit);
   const chars = d.chars === undefined || d.chars === null ? '?' : String(d.chars);
   const extra = d.detail === undefined || d.detail === null || String(d.detail) === '' ? 'no detail' : String(d.detail);
+  if (canonical === 'wrong-tree') {
+    return 'codex reported that the declared file(s) do not exist — the review ran in the WRONG working directory and its verdict is about a tree nobody asked for; ' + files + ' file(s) declared, exit ' + exit + ' (' + extra + ')';
+  }
   if (canonical === 'timeout') {
     return 'codex review timed out after ' + elapsed + 's on scope ' + ref + ' (' + files + ' files) — NARROW the scope (this is reconnaissance cost, not thinking time)';
   }
@@ -1763,7 +1898,11 @@ export function codexQeDeclineReason(kind: string | null | undefined, detail?: C
     return 'codex exec unusable — ' + (d.reason === undefined || d.reason === null || String(d.reason) === '' ? 'codex exec returned no text' : String(d.reason));
   }
   if (canonical === 'unavailable') {
-    return 'codex not used — ' + (d.reason === undefined || d.reason === null || String(d.reason) === '' ? 'codex exec reported it could not run' : String(d.reason));
+    // The detail is the ONE field that carries the shell error, and this branch used to drop it
+    // while `tool-error` right above rendered it — an asymmetry that made the field report's
+    // "codex exec reported it could not run" unfixable blind. Same `extra`, same shape.
+    const why = d.reason === undefined || d.reason === null || String(d.reason) === '' ? 'codex exec reported it could not run' : String(d.reason);
+    return 'codex not used — ' + why + (extra === 'no detail' ? '' : ' (' + extra + ')');
   }
   if (canonical === 'over-ceiling') {
     return 'prompt is ' + chars + ' chars / unscoped — refused before dispatch';
@@ -1804,12 +1943,12 @@ export interface CodexReviewResult {
  * wrapper and calls {@link classifyCodexQeOutcome} directly with `signalExpected: true`, so a
  * swallowed sentinel there is a `tool-error` and never a pass. A wiring test pins that.
  */
-export function parseCodexReviewResult(text: string | null | undefined): CodexReviewResult {
+export function parseCodexReviewResult(text: string | null | undefined, declaredFiles?: readonly string[] | null): CodexReviewResult {
   const sig = parseCodexReviewSignal(text);
   const findings = parseCodexReviewFindings(sig.body);
   const stated = parseCodexGrade(sig.body);
   const grade = stated !== null ? stated : gradeFromReviewFindings(findings);
-  const outcome = classifyCodexQeOutcome({ exit: sig.exit, body: sig.body, grade: grade, findings: findings, signalExpected: sig.signalPresent });
+  const outcome = classifyCodexQeOutcome({ exit: sig.exit, body: sig.body, grade: grade, findings: findings, signalExpected: sig.signalPresent, declaredFiles: declaredFiles === undefined ? null : declaredFiles });
   const kind = outcome.kind === 'unusable-output' ? 'empty' : outcome.kind;
   const ok = kind === 'verdict';
   const reason = ok ? null : codexQeDeclineReason(kind, { elapsedSeconds: sig.elapsedSeconds, exit: sig.exit, chars: sig.body.length });

package/src/index.ts

@@ -81,6 +81,9 @@ export { stampCheckpointLine } from './checkpoint-stamp.js';
 export { TELEMETRY_VOCAB_VERSION, TELEMETRY_FIELDS, PROVISIONAL_TELEMETRY_FIELDS, LOCAL_FIELD_ALIASES, telemetryFieldFor } from './telemetry-vocabulary.js';
 export type { TelemetryField, FieldSource } from './telemetry-vocabulary.js';
 export { planLedgerBackfill, LEDGER_FILL_SOURCE, AMBIGUOUS, resolveLedgerRunId } from './ledger-backfill.js';
+// project-skills root resolution (field report doc-25b): the ONE builder behind both the Step-0
+// probe and the PS_GUIDANCE paragraph, so the two can never look at different roots again.
+export { projectSkillsOneRoot, projectSkillsProbeCommand } from './project-skills-root.js';
 export type { LedgerBackfillPlan, LedgerBackfillRow, RunCostFacts } from './ledger-backfill.js';
 export type { SweepResult, DriftedSkill, SyncResult, SyncCanonicalOptions } from './skill-drift.js';
 export { benchmarkSkill, benchmarkSkills, compareSkills } from './benchmark.js';
@@ -119,12 +122,18 @@ export {
 } from './qe-bridge.js';
 export type { BridgeFamily, BridgeFailureReason, BridgeFinding, BridgeSignoff, BridgeParse, BridgeParseOk, BridgeParseFail, BridgeChannels, BridgeAudit, ClaudeResultExtraction, NamedExtract, BridgePromptInput } from './qe-bridge.js';
 export type { PatternRecord, SessionRecord, LearningConfig, MemoryLearningConfig, LoadOptions, ConsolidateResult, ConsolidateOptions, SqliteBackendMode, RecallHit, SessionsSource, PruneNoiseResult, RemovePatternsResult, SnapshotStoreResult, ReinforcementState, ReinforcePatternResult, StoreStats, LessonDeltaReport, LessonDeltaRow, QuarantineState, PromoteResult, QuarantineExpiryCandidate } from './patterns.js';
-export { DEFAULT_REINFORCE_THRESHOLD, NoopLearningBackend, NativeReinforcementBackend, resolveLearningBackend, isLearningSignalBackend } from './learning-backend.js';
-export type { LearningSignalBackend, LearningSignalStats, LearningSample, SignalCandidate, EnhanceContext, TrainingResult, LearningBackendMode } from './learning-backend.js';
+export { DEFAULT_REINFORCE_THRESHOLD, NoopLearningBackend, NativeReinforcementBackend, resolveLearningBackend, isLearningSignalBackend, applyLearningSignals, applyLearningSignalsWithDelta, applyLearningSignalsWithTerms } from './learning-backend.js';
+export type { LearningSignalBackend, LearningSignalStats, LearningSample, SignalCandidate, EnhanceContext, TrainingResult, LearningBackendMode, RerankTerm } from './learning-backend.js';
+// lesson-bandit-rerank (I-8): the ACL's public surface only. The vendored engine class is
+// deliberately NOT exported — `selectArm`'s "pick one and commit" is authority this domain denies
+// the ranker, and a foreign, invariant-blind API has no business on our safety-critical seam.
+export { resolveBanditConfig, payoffTermsFor, recordReward, recordExposures, contextKeyFor, banditStats, renderBanditHealth, narrowBanditReport, loadBanditState, banditStatePath, banditStateDir, freshBanditEnvelope, makeRewardEvent, classifySignal, BANDIT_LOCK_NAME, BANDIT_STATE_SCHEMA } from './lesson-payoff.js';
+export type { ResolvedBanditConfig, RewardEvent, ExposureEvent, PayoffTerm, PayoffTerms, BanditStateEnvelope, BanditLoadReason, BanditRecallReport, BanditHealth, BanditWriteOutcome } from './lesson-payoff.js';
 export {
   DEFAULT_VECTOR_TIMEOUT_MS,
   DEFAULT_HARMONIZE_THRESHOLD,
   REINFORCE_RRF_CAP,
+  BANDIT_RRF_CAP,
   withVectorTimeout,
   isVectorNoise,
   patternVectorEntry,
@@ -634,6 +643,11 @@ export {
   SCOPED_QE_PROMPT_MAX_CHARS,
   isSafeCodexRef,
   codexReviewCommand,
+  codexExecCommand,
+  codexReviewMissedItsFiles,
+  CODEX_EXEC_TIMEOUT_SECONDS,
+  timeoutBinOrDefault,
+  TIMEOUT_BINS,
   codexQeSignalCommand,
   scopedQePrompt,
   parseCodexReviewSignal,

package/src/learning-backend.ts

@@ -30,6 +30,11 @@ export interface LearningSample {
   readonly kind: LearningSampleKind;
   readonly reward?: number;
   readonly ts: string;
+  /** The recall domain this sample happened in, when the caller knows it. Threaded through to the
+   * bandit so a confirmation lands in the SAME context bucket the recall read from — without it a
+   * `dz recall --domain <x>` hit confirmed later writes to `general`, and `<x>` never sees it, which
+   * leaves domain-scoped re-ranking permanently inert (cross-family QE, gpt-5.6-sol). */
+  readonly domain?: string;
 }
 
 export interface TrainingResult {
@@ -122,6 +127,7 @@ export class NativeReinforcementBackend implements LearningSignalBackend {
         ts: sample.ts,
         ...(sample.reward !== undefined ? { reward: sample.reward } : {}),
         ...(sample.kind === 'recall-hit' ? { exposure: true } : {}),
+        ...(sample.domain !== undefined ? { domain: sample.domain } : {}),
       });
       if (r.ok) flushed += 1;
       else {
@@ -192,19 +198,70 @@ export function resolveLearningBackend(projectRoot: string, config: MemoryLearni
   }
 }
 
-export function applyLearningSignals<H extends { readonly score: number }>(
+/**
+ * One bounded re-rank term in the pipeline {@link applyLearningSignalsWithTerms} applies
+ * (feature lesson-bandit-rerank, architecture §6).
+ *
+ * WHY THIS EXISTS. `memory.learning.deltaRerank` is not a re-rank hook: it is a boolean that
+ * switches on ONE computation and selects between exactly two call sites. Reusing it for a second
+ * payoff signal would force one of two bad shapes — two independent features behind one switch, or
+ * a third `applyLearningSignalsWith…` function (and a fourth after that). A term LIST is the shape
+ * that stops growing.
+ */
+export interface RerankTerm {
+  /** `'delta'` | `'bandit'` — travels into the observability record. */
+  readonly id: string;
+  /** Raw per-candidate value, positionally aligned with `hits`/`candidates`. */
+  readonly byIndex: readonly number[];
+  /** Absolute bound on THIS term's contribution to a score. */
+  readonly cap: number;
+  /** Default `Math.tanh` (any magnitude → [-1,1]). A pre-bounded term passes identity. */
+  readonly squash?: (v: number) => number;
+}
+
+/**
+ * The one scoring pipeline: `adjusted = hit.score + cap*signal[i] + Σ_t t.cap * squash(t.byIndex[i])`,
+ * stable-sorted with the original index as tie-break.
+ *
+ * With `terms: []` this is {@link applyLearningSignals} in behaviour; with one `'delta'` term it is
+ * {@link applyLearningSignalsWithDelta}. Both remain exported as thin wrappers, so every existing
+ * caller and test is untouched — the widening is additive at the API level too.
+ *
+ * A non-finite raw value contributes 0 and never NaN-poisons the sort (the guard the delta function
+ * already carried; generalising it would have been the easiest place to drop it).
+ */
+export function applyLearningSignalsWithTerms<H extends { readonly score: number }>(
   hits: readonly H[],
   backend: LearningSignalBackend,
   candidates: readonly SignalCandidate[],
   cap: number,
+  terms: readonly RerankTerm[] = [],
 ): H[] {
   const signals = backend.enhance(candidates, { kind: 'recall', cap });
   return hits
-    .map((hit, i) => ({ hit, adjusted: hit.score + cap * (signals[i] ?? 0), i }))
+    .map((hit, i) => {
+      let extra = 0;
+      for (const t of terms) {
+        const raw = t.byIndex[i];
+        if (typeof raw !== 'number' || !Number.isFinite(raw)) continue;
+        const squashed = (t.squash ?? Math.tanh)(raw);
+        if (Number.isFinite(squashed)) extra += t.cap * squashed;
+      }
+      return { hit, adjusted: hit.score + cap * (signals[i] ?? 0) + extra, i };
+    })
     .sort((a, b) => b.adjusted - a.adjusted || a.i - b.i)
     .map((x) => x.hit);
 }
 
+export function applyLearningSignals<H extends { readonly score: number }>(
+  hits: readonly H[],
+  backend: LearningSignalBackend,
+  candidates: readonly SignalCandidate[],
+  cap: number,
+): H[] {
+  return applyLearningSignalsWithTerms(hits, backend, candidates, cap, []);
+}
+
 /**
  * {@link applyLearningSignals} plus a bounded ± SAFLA-delta term (rUv-scout #2 Phase 3). `deltaByIndex[i]`
  * is candidate `i`'s raw payoff SLOPE (0 when it has no slope signal); each is squashed through `tanh`
@@ -220,13 +277,7 @@ export function applyLearningSignalsWithDelta<H extends { readonly score: number
   deltaByIndex: readonly number[],
   deltaCap: number,
 ): H[] {
-  const signals = backend.enhance(candidates, { kind: 'recall', cap });
-  return hits
-    .map((hit, i) => {
-      const d = deltaByIndex[i];
-      const deltaTerm = typeof d === 'number' && Number.isFinite(d) ? deltaCap * Math.tanh(d) : 0;
-      return { hit, adjusted: hit.score + cap * (signals[i] ?? 0) + deltaTerm, i };
-    })
-    .sort((a, b) => b.adjusted - a.adjusted || a.i - b.i)
-    .map((x) => x.hit);
+  return applyLearningSignalsWithTerms(hits, backend, candidates, cap, [
+    { id: 'delta', byIndex: deltaByIndex, cap: deltaCap },
+  ]);
 }

package/src/lesson-bandit.ts

@@ -0,0 +1,279 @@
+/**
+ * VENDORED — contextual Thompson-Sampling bandit (feature lesson-bandit-rerank, ADR-001 D-1).
+ *
+ * Upstream: agentdb@3.0.0-alpha.20 — dist/src/backends/rvf/SolverBandit.js
+ * Licence:  MIT, Copyright (c) 2024-2025 ruv
+ * Vendored: 2026-08-26. 215 lines, ZERO imports (both re-verified at copy time:
+ *           `wc -l` → 215, `grep -cE 'require|^import'` → 0).
+ * SHA-256:  0199299fb60ef67afa030182185894c950126038398032349fe3618d910f6d7d
+ *           (of the upstream .js at copy time; pinned by lesson-bandit-vendor.test.ts)
+ * Reason:   the path is NOT in agentdb's package.json "exports" map (verified 2026-08-26);
+ *           a deep import of a private path in a 3.0.0-alpha prerelease can change silently,
+ *           and a ranking feature that quietly stops ranking looks exactly like one that works.
+ *
+ * Do not edit logic. Re-vendor from upstream and re-diff instead.
+ *
+ * WHAT CHANGED relative to the upstream .js, and nothing else:
+ *   · `class SolverBandit` → `class LessonBandit` (ADR-001 D-1: one name, no alias);
+ *   · TYPES added (field declarations, method signatures, the three exported interfaces);
+ *   · `armKeys[0]` → `armKeys[0]!` and `ctx.get(armKey)` → `!` — required by this package's
+ *     `noUncheckedIndexedAccess`; the emitted arithmetic is unchanged.
+ * The Jöhnk / Marsaglia-Tsang samplers, the `a<=1 && b<=1 ⇒ Math.random()` short-circuit, the
+ * exploration bonus and the cost EMA are preserved verbatim — the MEASURED API behaviour (200
+ * pulls on a 0.85-vs-0.15 pair → 100/100 correct picks) is a property of exactly this arithmetic.
+ *
+ * THIS FILE MUST STAY IMPORT-FREE (NFR-2 / C-7 / INV-6) — asserted by a repo test.
+ */
+
+/** Beta posterior + bookkeeping for one `(ContextKey, ArmKey)` pair. */
+export interface ArmStats {
+  alpha: number;
+  beta: number;
+  pulls: number;
+  totalReward: number;
+  costEma: number;
+}
+
+/** Engine hyperparameters. This feature passes the vendored defaults through untouched. */
+export interface BanditConfig {
+  costWeight: number;
+  costDecay: number;
+  explorationBonus: number;
+}
+
+/** The engine's own JSON-safe state. `version` belongs to the vendored copy, never to our envelope. */
+export interface SerializedBanditState {
+  version: number;
+  config: BanditConfig;
+  contexts: Record<string, Record<string, ArmStats>>;
+}
+
+/** Aggregate counters over every context. */
+export interface BanditAggregateStats {
+  contexts: number;
+  totalArms: number;
+  totalPulls: number;
+  totalReward: number;
+}
+
+/**
+ * Thompson Sampling bandit with contextual arms.
+ *
+ * Usage:
+ *   const bandit = new LessonBandit();
+ *   const arm = bandit.selectArm('code_review', ['skill-a', 'skill-b', 'skill-c']);
+ *   // ... execute the selected arm ...
+ *   bandit.recordReward('code_review', arm, 0.85);
+ */
+export class LessonBandit {
+  private contexts = new Map<string, Map<string, ArmStats>>();
+  private readonly config: BanditConfig;
+
+  constructor(config?: Partial<BanditConfig>) {
+    this.config = {
+      costWeight: config?.costWeight ?? 0.01,
+      costDecay: config?.costDecay ?? 0.1,
+      explorationBonus: config?.explorationBonus ?? 0.1,
+    };
+  }
+
+  /**
+   * Select the best arm for a given context using Thompson Sampling.
+   *
+   * For each candidate arm, samples from its Beta(alpha, beta) distribution
+   * and subtracts a cost penalty. Returns the arm with the highest score.
+   * Unknown arms get an exploration bonus.
+   */
+  selectArm(contextKey: string, armKeys: readonly string[]): string {
+    if (armKeys.length === 0)
+      throw new Error('No arms provided');
+    if (armKeys.length === 1)
+      return armKeys[0]!;
+    const ctx = this.contexts.get(contextKey);
+    let bestArm = armKeys[0]!;
+    let bestScore = -Infinity;
+    for (const arm of armKeys) {
+      const stats = ctx?.get(arm);
+      let score: number;
+      if (!stats || stats.pulls === 0) {
+        // Unknown arm: sample from uniform + exploration bonus
+        score = Math.random() + this.config.explorationBonus;
+      }
+      else {
+        // Thompson sample from Beta(alpha, beta)
+        const sample = this.sampleBeta(stats.alpha, stats.beta);
+        score = sample - stats.costEma * this.config.costWeight;
+      }
+      if (score > bestScore) {
+        bestScore = score;
+        bestArm = arm;
+      }
+    }
+    return bestArm;
+  }
+
+  /**
+   * Record the outcome of pulling an arm.
+   *
+   * @param contextKey - The context bucket (e.g., task type)
+   * @param armKey - The arm that was pulled (e.g., skill name)
+   * @param reward - Success signal in [0, 1]
+   * @param cost - Optional cost signal (latency, tokens, etc.)
+   */
+  recordReward(contextKey: string, armKey: string, reward: number, cost?: number): void {
+    if (!this.contexts.has(contextKey)) {
+      this.contexts.set(contextKey, new Map());
+    }
+    const ctx = this.contexts.get(contextKey)!;
+    if (!ctx.has(armKey)) {
+      ctx.set(armKey, { alpha: 1, beta: 1, pulls: 0, totalReward: 0, costEma: 0 });
+    }
+    const arm = ctx.get(armKey)!;
+    // Update Beta distribution
+    const r = Math.max(0, Math.min(1, reward));
+    arm.alpha += r;
+    arm.beta += (1 - r);
+    arm.pulls++;
+    arm.totalReward += r;
+    // Update cost EMA
+    if (cost !== undefined) {
+      arm.costEma = arm.costEma * (1 - this.config.costDecay) + cost * this.config.costDecay;
+    }
+  }
+
+  /**
+   * Rerank a list of candidates using bandit scores.
+   * Returns indices sorted by Thompson-sampled score (best first).
+   */
+  rerank(contextKey: string, armKeys: readonly string[]): string[] {
+    if (armKeys.length <= 1)
+      return [...armKeys];
+    const ctx = this.contexts.get(contextKey);
+    const scored = armKeys.map((arm) => {
+      const stats = ctx?.get(arm);
+      let score: number;
+      if (!stats || stats.pulls === 0) {
+        score = Math.random() + this.config.explorationBonus;
+      }
+      else {
+        score = this.sampleBeta(stats.alpha, stats.beta) - stats.costEma * this.config.costWeight;
+      }
+      return { arm, score };
+    });
+    scored.sort((a, b) => b.score - a.score);
+    return scored.map((s) => s.arm);
+  }
+
+  /** Get arm stats for a specific context */
+  getArmStats(contextKey: string, armKey: string): ArmStats | null {
+    return this.contexts.get(contextKey)?.get(armKey) ?? null;
+  }
+
+  /** Get aggregate statistics */
+  getStats(): BanditAggregateStats {
+    let totalArms = 0, totalPulls = 0, totalReward = 0;
+    for (const ctx of this.contexts.values()) {
+      totalArms += ctx.size;
+      for (const arm of ctx.values()) {
+        totalPulls += arm.pulls;
+        totalReward += arm.totalReward;
+      }
+    }
+    return { contexts: this.contexts.size, totalArms, totalPulls, totalReward };
+  }
+
+  /** Serialize to JSON-safe state */
+  serialize(): SerializedBanditState {
+    const contexts: Record<string, Record<string, ArmStats>> = {};
+    for (const [ctxKey, arms] of this.contexts) {
+      contexts[ctxKey] = {};
+      for (const [armKey, stats] of arms) {
+        contexts[ctxKey]![armKey] = { ...stats };
+      }
+    }
+    return { version: 1, config: { ...this.config }, contexts };
+  }
+
+  /**
+   * Restore from serialized state.
+   *
+   * STATIC (C-2). A first draft that called it as an instance method threw `TypeError`; the
+   * signature here makes the static call the only one that compiles.
+   */
+  static deserialize(state: SerializedBanditState): LessonBandit {
+    const bandit = new LessonBandit(state.config);
+    for (const [ctxKey, arms] of Object.entries(state.contexts)) {
+      const ctx = new Map<string, ArmStats>();
+      for (const [armKey, stats] of Object.entries(arms)) {
+        ctx.set(armKey, { ...stats });
+      }
+      bandit.contexts.set(ctxKey, ctx);
+    }
+    return bandit;
+  }
+
+  /** Reset all learned state */
+  reset(): void {
+    this.contexts.clear();
+  }
+
+  // ─── Private ───
+
+  /**
+   * Sample from Beta(a, b) using the Jöhnk algorithm.
+   * Fast approximation for typical bandit parameters.
+   */
+  private sampleBeta(a: number, b: number): number {
+    // For a=1, b=1 (uniform): just return Math.random()
+    if (a <= 1 && b <= 1)
+      return Math.random();
+    // Jöhnk's algorithm for general Beta
+    if (a < 1 && b < 1) {
+      for (let iter = 0; iter < 1000; iter++) {
+        const u = Math.random();
+        const v = Math.random();
+        const x = Math.pow(u, 1 / a);
+        const y = Math.pow(v, 1 / b);
+        if (x + y <= 1)
+          return x / (x + y);
+      }
+      return Math.random(); // fallback (extremely unlikely)
+    }
+    // For larger parameters, use Gamma ratio
+    const ga = this.sampleGamma(a);
+    const gb = this.sampleGamma(b);
+    return ga / (ga + gb);
+  }
+
+  /**
+   * Sample from Gamma(shape, 1) using Marsaglia & Tsang's method.
+   */
+  private sampleGamma(shape: number): number {
+    if (shape < 1) {
+      return this.sampleGamma(shape + 1) * Math.pow(Math.random(), 1 / shape);
+    }
+    const d = shape - 1 / 3;
+    const c = 1 / Math.sqrt(9 * d);
+    for (let iter = 0; iter < 1000; iter++) {
+      let x: number, v: number;
+      do {
+        x = this.sampleNormal();
+        v = 1 + c * x;
+      } while (v <= 0);
+      v = v * v * v;
+      const u = Math.random();
+      if (u < 1 - 0.0331 * (x * x) * (x * x))
+        return d * v;
+      if (Math.log(u) < 0.5 * x * x + d * (1 - v + Math.log(v)))
+        return d * v;
+    }
+    return d; // fallback (extremely unlikely)
+  }
+
+  /** Box-Muller normal sample */
+  private sampleNormal(): number {
+    const u1 = Math.random();
+    const u2 = Math.random();
+    return Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+  }
+}