nlm-memory 0.20.1 → 0.21.12

package/dist/mcp/server.js

@@ -26,15 +26,28 @@ import { composeWorkstreamRecall } from "../core/workstream/compose-recall.js";
 import { normalizeLabel } from "../core/workstream/model.js";
 import { resolveWorkstreamId } from "../core/workstream/resolve.js";
 import { suggestMerges } from "../core/workstream/merge-suggest.js";
+import { normalizeSignal } from "../core/signals/ingest-signal.js";
+import { stampSignalScope } from "../core/signals/stamp-scope.js";
+import { deriveOutcome } from "../core/outcome/rollup.js";
+import { buildSqliteOutcomeDeps } from "../core/storage/sqlite-outcome-store.js";
+import { completeLearnerCourse, enrollCourse, getCourseSummary, recordLearningEvent, } from "../core/learner/service.js";
+import { truncateSummary } from "../core/hook/pointer-block.js";
+import { SIGNAL_OUTCOMES } from "../shared/types.js";
 const CHARACTER_LIMIT = 25_000;
 const DEFAULT_LIMIT = 10;
 const SERVER_NAME = "nlm-memory-mcp-server";
 const SERVER_VERSION = "0.5.9";
 /** TOON encoding cuts token usage on large recall payloads. Opt in via
- *  NLM_FORMAT=toon in the MCP server's env (see .mcp.json). Defaults to JSON. */
-const USE_TOON = process.env.NLM_FORMAT === "toon";
+ *  NLM_FORMAT=toon. Defaults to JSON.
+ *
+ *  Read at call time, not module scope: on the HTTP transport this module is
+ *  imported by the daemon long before buildStack() calls autoloadEnv(), so an
+ *  eager read would capture the environment before ~/.nlm/.env was loaded and
+ *  silently ignore the setting. Only the stdio path, where the runtime passes
+ *  env directly to the child, would have worked. */
+const useToon = () => process.env.NLM_FORMAT === "toon";
 function format(data) {
-    if (USE_TOON) {
+    if (useToon()) {
         try {
             return toonEncode(data);
         }
@@ -86,7 +99,7 @@ export function mcpRuntimeFromClient(client) {
     const name = client?.name?.trim().toLowerCase();
     return name ? name : null;
 }
-export async function recallSessionsHandler(deps, input, runtime = null) {
+export async function recallSessionsHandler(deps, tenantId, input, runtime = null) {
     try {
         const rewrite = input.rewrite ?? mcpRewriteDefault();
         const query = {
@@ -102,12 +115,12 @@ export async function recallSessionsHandler(deps, input, runtime = null) {
             ...(input.kind !== undefined ? { kind: input.kind } : {}),
             ...(input.workstream !== undefined ? { workstream: input.workstream } : {}),
         };
-        const result = await deps.recall.search(query);
+        const result = await deps.recall.search(tenantId, query);
         const conversationId = resolveConversationByQuery(input.query ?? "") ?? undefined;
         // Telemetry — the MCP path is the real agent-usage path; without this it
         // is invisible to query_log.jsonl and the Recall page. Fire-and-forget,
         // mirrors the HTTP /api/recall handler.
-        void logQuery({
+        void logQuery(tenantId, {
             source: "mcp",
             runtime,
             query: input.query ?? null,
@@ -125,20 +138,20 @@ export async function recallSessionsHandler(deps, input, runtime = null) {
         return err(e);
     }
 }
-export async function workSummaryHandler(deps, input) {
+export async function workSummaryHandler(deps, tenantId, input) {
     if (!deps.workDigest) {
         return okText("work_summary is not available in this deployment.");
     }
     try {
         const date = input.date ?? localToday();
-        const digest = await buildWorkDigest(deps.workDigest, date);
+        const digest = await buildWorkDigest(deps.workDigest, tenantId, date);
         return okText(composeWorkDigest(digest));
     }
     catch (e) {
         return err(e);
     }
 }
-export async function recallWorkstreamHandler(deps, input, runtime = null) {
+export async function recallWorkstreamHandler(deps, tenantId, input, runtime = null) {
     if (!deps.workstreams)
         return okText("recall_workstream is not available in this deployment.");
     try {
@@ -147,13 +160,13 @@ export async function recallWorkstreamHandler(deps, input, runtime = null) {
             return okText("Provide a workstream id or label.");
         const conversationId = resolveConversationByQuery(idOrLabel) ?? undefined;
         const ws = deps.workstreams.store;
-        const found = (await ws.getById(idOrLabel)) ?? (await ws.findByNormalizedLabel(normalizeLabel(idOrLabel)));
+        const found = (await ws.getById(tenantId, idOrLabel)) ?? (await ws.findByNormalizedLabel(tenantId, normalizeLabel(idOrLabel)));
         if (!found)
             return okText(`No workstream matches "${idOrLabel}".`);
-        const view = await rollupWorkstream({ workstreams: deps.workstreams.store, sessions: deps.workstreams.sessions, facts: deps.workstreams.facts, exemplars: deps.workstreams.exemplars }, found.id);
+        const view = await rollupWorkstream({ workstreams: deps.workstreams.store, sessions: deps.workstreams.sessions, facts: deps.workstreams.facts, exemplars: deps.workstreams.exemplars }, tenantId, found.id);
         if (!view)
             return okText(`No workstream matches "${idOrLabel}".`);
-        void logQuery({
+        void logQuery(tenantId, {
             source: "mcp",
             runtime,
             query: idOrLabel,
@@ -171,17 +184,17 @@ export async function recallWorkstreamHandler(deps, input, runtime = null) {
         return err(e);
     }
 }
-/** idOrLabel -> live survivor workstream (merged_into resolved) | null. One source of truth for lifecycle handlers. */
-async function resolveWorkstream(store, idOrLabel) {
-    const found = (await store.getById(idOrLabel)) ?? (await store.findByNormalizedLabel(normalizeLabel(idOrLabel)));
+/** idOrLabel -> live survivor workstream (merged_into resolved) | null, within tenantId. One source of truth for lifecycle handlers. */
+async function resolveWorkstream(store, tenantId, idOrLabel) {
+    const found = (await store.getById(tenantId, idOrLabel)) ?? (await store.findByNormalizedLabel(tenantId, normalizeLabel(idOrLabel)));
     if (!found)
         return null;
-    const all = await store.listAll();
+    const all = await store.listAll(tenantId);
     const byId = new Map(all.map((w) => [w.id, { id: w.id, mergedInto: w.mergedInto }]));
     const survivorId = resolveWorkstreamId(found.id, byId);
-    return survivorId === found.id ? found : ((await store.getById(survivorId)) ?? found);
+    return survivorId === found.id ? found : ((await store.getById(tenantId, survivorId)) ?? found);
 }
-export async function renameWorkstreamHandler(deps, input) {
+export async function renameWorkstreamHandler(deps, tenantId, input) {
     if (!deps.workstreams)
         return okText("rename_workstream is not available in this deployment.");
     try {
@@ -190,38 +203,38 @@ export async function renameWorkstreamHandler(deps, input) {
         if (!idOrLabel || !label)
             return okText("Provide the workstream (id or label) and the new label.");
         const ws = deps.workstreams.store;
-        const target = await resolveWorkstream(ws, idOrLabel);
+        const target = await resolveWorkstream(ws, tenantId, idOrLabel);
         if (!target)
             return okText(`No workstream matches "${idOrLabel}".`);
-        const collision = await ws.findByNormalizedLabel(normalizeLabel(label));
+        const collision = await ws.findByNormalizedLabel(tenantId, normalizeLabel(label));
         if (collision && collision.id !== target.id) {
             return okText(`Label "${label}" is already used by workstream "${collision.label}" (${collision.id}).`);
         }
-        await ws.setLabel(target.id, label);
+        await ws.setLabel(tenantId, target.id, label);
         return okText(`Renamed workstream ${target.id}: "${target.label}" -> "${label}".`);
     }
     catch (e) {
         return err(e);
     }
 }
-export async function retireWorkstreamHandler(deps, input) {
+export async function retireWorkstreamHandler(deps, tenantId, input) {
     if (!deps.workstreams)
         return okText("retire_workstream is not available in this deployment.");
     try {
         const idOrLabel = (input.idOrLabel ?? "").trim();
         if (!idOrLabel)
             return okText("Provide a workstream id or label.");
-        const target = await resolveWorkstream(deps.workstreams.store, idOrLabel);
+        const target = await resolveWorkstream(deps.workstreams.store, tenantId, idOrLabel);
         if (!target)
             return okText(`No workstream matches "${idOrLabel}".`);
-        await deps.workstreams.store.setStatus(target.id, "retired");
+        await deps.workstreams.store.setStatus(tenantId, target.id, "retired");
         return okText(`Retired workstream "${target.label}" (${target.id}).`);
     }
     catch (e) {
         return err(e);
     }
 }
-export async function mergeWorkstreamsHandler(deps, input) {
+export async function mergeWorkstreamsHandler(deps, tenantId, input) {
     if (!deps.workstreams)
         return okText("merge_workstreams is not available in this deployment.");
     try {
@@ -230,22 +243,22 @@ export async function mergeWorkstreamsHandler(deps, input) {
         if (!fromArg || !intoArg)
             return okText("Provide both `from` and `into` (workstream id or label).");
         const ws = deps.workstreams.store;
-        const from = await resolveWorkstream(ws, fromArg);
-        const into = await resolveWorkstream(ws, intoArg);
+        const from = await resolveWorkstream(ws, tenantId, fromArg);
+        const into = await resolveWorkstream(ws, tenantId, intoArg);
         if (!from)
             return okText(`No workstream matches "${fromArg}".`);
         if (!into)
             return okText(`No workstream matches "${intoArg}".`);
         if (from.id === into.id)
             return okText(`"${fromArg}" and "${intoArg}" resolve to the same workstream — nothing to merge.`);
-        await ws.merge(from.id, into.id);
+        await ws.merge(tenantId, from.id, into.id);
         return okText(`Merged "${from.label}" (${from.id}) into "${into.label}" (${into.id}).`);
     }
     catch (e) {
         return err(e);
     }
 }
-export async function rebindSessionHandler(deps, input) {
+export async function rebindSessionHandler(deps, tenantId, input) {
     if (!deps.workstreams)
         return okText("rebind_session is not available in this deployment.");
     try {
@@ -253,10 +266,10 @@ export async function rebindSessionHandler(deps, input) {
         const wsArg = (input.workstream ?? "").trim();
         if (!sessionId || !wsArg)
             return okText("Provide both a sessionId and a workstream (id or label).");
-        const ws = await resolveWorkstream(deps.workstreams.store, wsArg);
+        const ws = await resolveWorkstream(deps.workstreams.store, tenantId, wsArg);
         if (!ws)
             return okText(`No workstream matches "${wsArg}".`);
-        await deps.store.setWorkstreamBinding(sessionId, ws.id, "operator", null);
+        await deps.store.setWorkstreamBinding(tenantId, sessionId, ws.id, "operator", null);
         return okText(`Rebound session ${sessionId} -> workstream "${ws.label}" (${ws.id}).`);
     }
     catch (e) {
@@ -270,9 +283,9 @@ function localToday() {
     const da = String(d.getDate()).padStart(2, "0");
     return `${d.getFullYear()}-${mo}-${da}`;
 }
-export async function getSessionHandler(deps, input) {
+export async function getSessionHandler(deps, tenantId, input) {
     try {
-        const session = await deps.store.getById(input.id);
+        const session = await deps.store.getById(tenantId, input.id);
         if (!session) {
             return err(new Error(`session ${input.id} not found`));
         }
@@ -281,38 +294,58 @@ export async function getSessionHandler(deps, input) {
             ...(session.supersedes ?? []),
             ...(session.supersededBy ? [session.supersededBy] : []),
         ];
-        const linked = linkedIds.length > 0 ? await deps.store.getByIds(linkedIds) : [];
+        const linked = linkedIds.length > 0 ? await deps.store.getByIds(tenantId, linkedIds) : [];
         const byId = new Map(linked.map((s) => [s.id, s]));
         // Load supersedence log once so we can join reason + recordedBy onto supersededBy
         const supersedenceLog = session.supersededBy
-            ? await readSupersedenceLog()
+            ? await readSupersedenceLog(tenantId)
             : [];
         const supersedenceMap = new Map(supersedenceLog.map((e) => [e.predecessorId, e]));
         const supersedes = (session.supersedes ?? []).map((id) => {
             const s = byId.get(id);
             return s ? { id, label: s.label, summary: s.summary } : { id, label: "", summary: "" };
         });
+        // Supersedence-enrichment fencing (program spec §4.6 hardening 2): even
+        // though readSupersedenceLog now reads the caller's own tenant file, a
+        // log entry's `reason`/`recordedBy` may only surface for a successor id
+        // that resolved through the tenant-filtered getByIds above (`byId`) —
+        // defense in depth against any pre-M6 legacy entry that predates
+        // per-tenant log files. An unresolved id contributes nothing — not even
+        // its reason — same as the by-id not-found shape (case 4).
         const supersededBy = session.supersededBy
             ? (() => {
                 const s = byId.get(session.supersededBy);
+                if (!s)
+                    return { id: session.supersededBy, label: "", summary: "" };
                 const logEntry = supersedenceMap.get(session.id);
-                const base = s
-                    ? { id: session.supersededBy, label: s.label, summary: s.summary }
-                    : { id: session.supersededBy, label: "", summary: "" };
                 return {
-                    ...base,
+                    id: session.supersededBy,
+                    label: s.label,
+                    summary: s.summary,
                     reason: logEntry?.reason,
                     recordedBy: logEntry?.source,
                 };
             })()
             : null;
-        return ok({ ...session, supersedes, supersededBy });
+        // Isolated: the outcome rollup is enrichment, not the payload. A throw
+        // here (SQLITE_BUSY, stale handle, unmigrated db) must degrade to
+        // no-outcome, never fail the whole get_session call.
+        let outcome;
+        if (deps.outcomeDb) {
+            try {
+                outcome = await deriveOutcome(tenantId, session.id, await buildSqliteOutcomeDeps(deps.outcomeDb, tenantId));
+            }
+            catch {
+                outcome = undefined;
+            }
+        }
+        return ok({ ...session, supersedes, supersededBy, ...(outcome ? { outcome } : {}) });
     }
     catch (e) {
         return err(e);
     }
 }
-export async function recallFactsHandler(deps, input, runtime = null) {
+export async function recallFactsHandler(deps, tenantId, input, runtime = null) {
     if (!deps.factRecall) {
         return err(new Error("fact recall not wired in this deployment"));
     }
@@ -331,10 +364,10 @@ export async function recallFactsHandler(deps, input, runtime = null) {
                 ? { minConfidence: input.minConfidence }
                 : {}),
         };
-        const result = await deps.factRecall.search(query);
+        const result = await deps.factRecall.search(tenantId, query);
         const conversationId = resolveConversationByQuery(input.query ?? "") ?? undefined;
         // Telemetry — see recallSessionsHandler. Fire-and-forget.
-        void logFactQuery({
+        void logFactQuery(tenantId, {
             source: "mcp",
             runtime,
             query: input.query ?? null,
@@ -353,12 +386,12 @@ export async function recallFactsHandler(deps, input, runtime = null) {
         return err(e);
     }
 }
-export async function getFactHistoryHandler(deps, input) {
+export async function getFactHistoryHandler(deps, tenantId, input) {
     if (!deps.factStore) {
         return err(new Error("fact store not wired in this deployment"));
     }
     try {
-        const chains = await deps.factStore.getHistory(input.subject, input.predicate);
+        const chains = await deps.factStore.getHistory(tenantId, input.subject, input.predicate);
         return ok({ subject: input.subject, predicate: input.predicate ?? null, chains });
     }
     catch (e) {
@@ -427,6 +460,10 @@ run, or any quote you intend to reference verbatim.
 The recall_sessions digest is optimized for ranking and scanning; the full body
 contains the actual conversation transcript that produced the decision.
 
+When wired, the response includes an \`outcome\` object: whether the session's
+decision held, was overturned, was built upon, was re-derived later, or
+remains unobserved, plus the evidence tier/confidence behind that verdict.
+
 Args:
   - id: Canonical session ID returned by recall_sessions (e.g. "cc_abc123",
         "sess_pgvector"). Pass the id field from the recall_sessions result.`;
@@ -516,13 +553,13 @@ Args:
 
 Idempotent. Re-marking the same pair is a no-op. Returns the linked pair on
 success; errors if either id is unknown or the two ids are equal.`;
-export async function markSupersededHandler(deps, input) {
+export async function markSupersededHandler(deps, tenantId, input) {
     if (!input.predecessor_id || !input.successor_id) {
         return err(new Error("predecessor_id and successor_id are required"));
     }
     try {
-        await deps.store.markSuperseded(input.predecessor_id, input.successor_id);
-        void appendSupersedence({
+        await deps.store.markSuperseded(tenantId, input.predecessor_id, input.successor_id);
+        void appendSupersedence(tenantId, {
             predecessorId: input.predecessor_id,
             successorId: input.successor_id,
             source: "mcp",
@@ -560,7 +597,7 @@ Args:
 
 Idempotent: calling it twice on the same id is a no-op. Errors if fact_id
 is unknown.`;
-export async function supersedeFactHandler(deps, input) {
+export async function supersedeFactHandler(deps, tenantId, input) {
     if (!input.fact_id || input.fact_id.length < 4) {
         return err(new Error("fact_id is required"));
     }
@@ -568,8 +605,8 @@ export async function supersedeFactHandler(deps, input) {
         return err(new Error("fact store not available"));
     }
     try {
-        await deps.factStore.retire(input.fact_id);
-        void appendFactSupersedence({
+        await deps.factStore.retire(tenantId, input.fact_id);
+        void appendFactSupersedence(tenantId, {
             factId: input.fact_id,
             source: "mcp",
             ...(input.reason !== undefined ? { reason: input.reason } : {}),
@@ -584,39 +621,96 @@ export async function supersedeFactHandler(deps, input) {
         return err(e);
     }
 }
-export async function citeSessionHandler(input) {
+export async function citeSessionHandler(tenantId, input) {
     if (!input.id || input.id.length < MIN_CITE_ID_LEN) {
         return err(new Error(`id must be at least ${MIN_CITE_ID_LEN} characters`));
     }
     try {
-        await appendCitation({
-            // Agents rarely pass conversation_id; resolve it server-side from the
-            // surfaced-memo so the citation joins to its hook fire (NLM #345).
-            conversationId: input.conversation_id ?? resolveConversationForSession(input.id) ?? "mcp_tool",
+        // Agents rarely pass conversation_id, so resolve it server-side. The
+        // surfaced-memo only knows sessions the recall HOOK injected, which is
+        // empty whenever ambient recall is off or failing — that gap silently
+        // unattributed every pull-driven citation. Fall back to the same
+        // transcript scan the recall handlers use: the runtime has already
+        // written this cite_session tool_use (carrying `id`) to the transcript
+        // before this handler runs, so the id is a reliable join key.
+        const conversationId = input.conversation_id ??
+            resolveConversationForSession(tenantId, input.id) ??
+            resolveConversationByQuery(input.id) ??
+            "mcp_tool";
+        const logged = await appendCitation(tenantId, {
+            conversationId,
             citedId: input.id,
             kind: "tool_use",
             ...(input.reason !== undefined ? { responsePreview: input.reason } : {}),
         });
-        return ok({ logged: true, id: input.id });
+        // An unattributable citation is dropped by the write path; reporting it as
+        // logged would make a dead telemetry path look healthy.
+        return ok({ logged, id: input.id, ...(logged ? {} : { reason: "unattributable_conversation" }) });
     }
     catch (e) {
         return err(e);
     }
 }
-export async function listMergeSuggestionsHandler(deps, input) {
+const REPORT_OUTCOME_DESCRIPTION = `Record whether a session's decision held up or was overturned. THIS IS THE CONTRACT SURFACE for outcome signals: it writes the same append-only \`signals\` row that POST /api/signal writes (producer "mcp"), just over MCP instead of HTTP.
+
+Expected callers are deterministic producers: hooks, CI pipelines, and automation platforms confirming a build/deploy/test result against a prior session. Agents rarely self-report their own outcome; outcome should come from independent evidence, not the agent's opinion of its own work.
+
+Args:
+  - session_id or correlation_key: at least one required. session_id is the NLM session this outcome applies to. correlation_key is an external identifier (e.g. a CI run id) to use when no NLM session_id is known; it is recorded on the row for traceability but is not (yet) joined into the Tier-B outcome rollup.
+  - outcome: one of pass | fail | fix | exhausted, the same vocabulary POST /api/signal accepts.
+  - source_of_record: required. Identifies the deterministic system asserting this outcome (e.g. "ci:github-actions", "hook:post-tool-use", "n8n:deploy-workflow").
+  - detail: optional passthrough object for additional context.`;
+/** The kind stamped on rows this tool writes. Loosely, this row represents an
+ *  outcome *review* of a prior session's decision, and "review" is the closest
+ *  fit among the existing SignalKind vocabulary (gate|eval|review|test); no
+ *  literal "outcome" kind exists (see rollup.ts's own note on this same
+ *  ambiguity). Tier-A correlation in rollup.ts keys on session_id only, so
+ *  this choice does not affect verdict derivation. */
+const REPORT_OUTCOME_KIND = "review";
+export async function reportOutcomeHandler(deps, tenantId, input) {
+    if (!input.session_id && !input.correlation_key) {
+        return err(new Error("session_id or correlation_key is required"));
+    }
+    if (!input.source_of_record || input.source_of_record.length === 0) {
+        return err(new Error("source_of_record is required"));
+    }
+    if (!deps.signalStore || deps.installScope === undefined) {
+        return err(new Error("signal store not available"));
+    }
+    try {
+        let signal = normalizeSignal({
+            kind: REPORT_OUTCOME_KIND,
+            producer: "mcp",
+            outcome: input.outcome,
+            session: input.session_id ?? null,
+            detail: {
+                ...(input.detail ?? {}),
+                source_of_record: input.source_of_record,
+                ...(input.correlation_key ? { correlation_key: input.correlation_key } : {}),
+            },
+        }, deps.installScope);
+        signal = await stampSignalScope(signal, tenantId, { sessionScopeReader: deps.sessionScopeReader });
+        await deps.signalStore.insert(tenantId, signal);
+        return ok({ recorded: true, id: signal.id, outcome: signal.outcome });
+    }
+    catch (e) {
+        return err(e);
+    }
+}
+export async function listMergeSuggestionsHandler(deps, tenantId, input) {
     if (!deps.workstreams)
         return okText("list_merge_suggestions is not available in this deployment.");
     try {
         const minScore = typeof input.minScore === "number" ? input.minScore : 0.5;
-        const all = (await deps.workstreams.store.listAll()).filter((w) => w.status === "active");
+        const all = (await deps.workstreams.store.listAll(tenantId)).filter((w) => w.status === "active");
         if (all.length < 2)
             return okText("Not enough active workstreams to suggest merges.");
         const ids = all.map((w) => w.id);
-        const entMap = await deps.workstreams.store.entitiesFor(ids);
+        const entMap = await deps.workstreams.store.entitiesFor(tenantId, ids);
         const items = await Promise.all(all.map(async (w) => ({
             id: w.id, label: w.label,
             entities: entMap.get(w.id) ?? [],
-            sessionIds: await deps.workstreams.sessions.listSessionIdsByWorkstreams([w.id]),
+            sessionIds: await deps.workstreams.sessions.listSessionIdsByWorkstreams(tenantId, [w.id]),
         })));
         const suggestions = suggestMerges(items, minScore);
         if (suggestions.length === 0)
@@ -632,7 +726,144 @@ export async function listMergeSuggestionsHandler(deps, input) {
         return err(e);
     }
 }
-export function createMcpServer(deps) {
+const LEARNER_ENROLL_DESCRIPTION = `\
+Enroll a learner in a course, binding the enrollment to a workstream so later
+sessions resolve their learning state at recall time. The course plan itself
+stays with the caller — NLM stores only its reference, revision, and
+fingerprint, and refuses writes when a re-enrolled plan differs.`;
+const LEARNER_RECORD_DESCRIPTION = `\
+Record a learning event: concepts covered plus per-concept attempts (task,
+response, result/help/kind), an interpretation, and the next step. Identical
+event ids are safe no-ops; conflicting ids fail rather than rewriting
+history. A submitted exercise is not evidence until recorded here.`;
+const LEARNER_SUMMARY_DESCRIPTION = `\
+Summarize what a learner has demonstrably learned in a course: per-concept
+status (exposed/practicing/demonstrated/retained), the latest next step, and
+sessions bound to the enrollment's workstream since the last recorded event
+(unrecorded candidates — record them with learner_record, don't assume).`;
+const LEARNER_COMPLETE_DESCRIPTION = `\
+Mark a learner's course completed. Preserves completion history and actual
+evidence; untaught or untested topics stay explicitly marked.`;
+const LEARNER_SUMMARY_DEFAULT_LIMIT = 50;
+const LEARNER_UNRECORDED_CAP = 10;
+export async function learnerEnrollHandler(deps, tenantId, input) {
+    if (!deps.learners)
+        return okText("learner tools are not available in this deployment.");
+    try {
+        const enrollment = await enrollCourse({ learners: deps.learners.store, workstreams: deps.learners.workstreams }, tenantId, {
+            learnerId: input.learner,
+            ...(input.label !== undefined ? { learnerLabel: input.label } : {}),
+            courseId: input.course,
+            workstream: input.workstream,
+            planRef: input.plan_ref,
+            planRevision: input.plan_revision,
+            planFingerprint: input.plan_fingerprint,
+        });
+        return okText(`Enrolled ${input.learner} in ${input.course} (${enrollment.status}, plan rev ${enrollment.planRevision}).`);
+    }
+    catch (e) {
+        return err(e);
+    }
+}
+export async function learnerRecordHandler(deps, tenantId, input) {
+    if (!deps.learners)
+        return okText("learner tools are not available in this deployment.");
+    try {
+        const result = await recordLearningEvent({ learners: deps.learners.store, workstreams: deps.learners.workstreams }, tenantId, input.learner, input.course, {
+            id: input.event.id,
+            date: input.event.date,
+            covered: input.event.covered,
+            attempts: input.event.attempts,
+            interpretation: input.event.interpretation,
+            nextStep: input.event.next_step,
+        });
+        return result === "inserted"
+            ? okText(`Recorded event ${input.event.id} for ${input.learner}/${input.course}.`)
+            : okText(`Event ${input.event.id} already recorded (identical) — no change.`);
+    }
+    catch (e) {
+        return err(e);
+    }
+}
+export async function learnerSummaryHandler(deps, tenantId, input) {
+    if (!deps.learners)
+        return okText("learner tools are not available in this deployment.");
+    try {
+        let course = input.course?.trim() ? input.course.trim() : undefined;
+        if (!course) {
+            const enrollments = await deps.learners.store.listEnrollments(tenantId, input.learner);
+            const active = enrollments.filter((e) => e.status === "active");
+            if (active.length === 0)
+                return okText(`No active enrollments for learner ${input.learner}.`);
+            if (active.length > 1) {
+                return okText(`Multiple active courses for ${input.learner}; specify course: ${active.map((e) => e.courseId).join(", ")}.`);
+            }
+            course = active[0].courseId;
+        }
+        const summary = await getCourseSummary({ learners: deps.learners.store, workstreams: deps.learners.workstreams }, tenantId, input.learner, course);
+        if (!summary)
+            return okText(`No enrollment for learner ${input.learner} in course ${course}.`);
+        const lines = [];
+        lines.push(`LEARNER ${summary.learnerId} · ${summary.courseId} (${summary.status}, rev ${summary.planRevision}, ${summary.eventCount} events)`);
+        const limit = input.limit ?? LEARNER_SUMMARY_DEFAULT_LIMIT;
+        const concepts = summary.concepts.slice(0, Math.max(0, limit));
+        if (concepts.length === 0) {
+            lines.push("(no concepts recorded yet)");
+        }
+        else {
+            lines.push("CONCEPTS:");
+            for (const c of concepts) {
+                const n = c.attemptCount === 1 ? "1 attempt" : `${c.attemptCount} attempts`;
+                lines.push(`  - [${c.status}] ${c.concept} (${n})`);
+            }
+            if (summary.concepts.length > concepts.length) {
+                lines.push(`  (+${summary.concepts.length - concepts.length} more — raise limit)`);
+            }
+        }
+        lines.push(`Next: ${summary.nextStep ? truncateSummary(summary.nextStep) : "(none recorded)"}`);
+        if (summary.workstreamId) {
+            const ids = await deps.learners.sessions.listSessionIdsByWorkstreams(tenantId, [summary.workstreamId]);
+            if (ids.length > 0) {
+                const sessions = await deps.learners.sessions.getByIds(tenantId, ids);
+                const cutoff = summary.lastEventDate ?? "";
+                const unrecorded = sessions
+                    .filter((s) => s.startedAt.slice(0, 10) > cutoff)
+                    .sort((a, b) => (a.startedAt < b.startedAt ? -1 : 1))
+                    .slice(0, LEARNER_UNRECORDED_CAP);
+                if (unrecorded.length > 0) {
+                    lines.push(`Unrecorded sessions (${unrecorded.length}):`);
+                    for (const s of unrecorded) {
+                        lines.push(`  - ${s.id} · ${truncateSummary(s.label, 80)} (${s.startedAt.slice(0, 10)})`);
+                    }
+                }
+            }
+        }
+        return okText(lines.join("\n"));
+    }
+    catch (e) {
+        return err(e);
+    }
+}
+export async function learnerCompleteHandler(deps, tenantId, input) {
+    if (!deps.learners)
+        return okText("learner tools are not available in this deployment.");
+    try {
+        await completeLearnerCourse({ learners: deps.learners.store, workstreams: deps.learners.workstreams }, tenantId, input.learner, input.course);
+        return okText(`Marked ${input.course} completed for ${input.learner}.`);
+    }
+    catch (e) {
+        return err(e);
+    }
+}
+/**
+ * The composition root for the MCP surface (program spec §4.6 "M2 threading
+ * semantics until M3"): `tenantId` is required here, not defaulted, and
+ * every tool handler below receives it explicitly rather than reading a
+ * module-level constant. The stdio caller (src/cli/nlm.ts) is local-mode
+ * only and always passes DEFAULT_TEAM_ID; the HTTP /mcp mount
+ * (src/http/app.ts) passes the token-resolved team (M3).
+ */
+export function createMcpServer(deps, tenantId) {
     const server = new McpServer({
         name: SERVER_NAME,
         version: SERVER_VERSION,
@@ -679,7 +910,7 @@ export function createMcpServer(deps) {
             idempotentHint: true,
             openWorldHint: true,
         },
-    }, async (args) => recallSessionsHandler(deps, args, mcpRuntimeFromClient(server.server.getClientVersion())));
+    }, async (args) => recallSessionsHandler(deps, tenantId, args, mcpRuntimeFromClient(server.server.getClientVersion())));
     server.registerTool("get_session", {
         title: "Get Full NLM Session",
         description: GET_SESSION_DESCRIPTION,
@@ -692,7 +923,7 @@ export function createMcpServer(deps) {
             idempotentHint: true,
             openWorldHint: true,
         },
-    }, async (args) => getSessionHandler(deps, args));
+    }, async (args) => getSessionHandler(deps, tenantId, args));
     if (deps.factRecall && deps.factStore) {
         server.registerTool("recall_facts", {
             title: "Recall Facts from NLM",
@@ -742,7 +973,7 @@ export function createMcpServer(deps) {
                 idempotentHint: true,
                 openWorldHint: true,
             },
-        }, async (args) => recallFactsHandler(deps, args, mcpRuntimeFromClient(server.server.getClientVersion())));
+        }, async (args) => recallFactsHandler(deps, tenantId, args, mcpRuntimeFromClient(server.server.getClientVersion())));
         server.registerTool("get_fact_history", {
             title: "Get Fact Supersedence History",
             description: GET_FACT_HISTORY_DESCRIPTION,
@@ -759,7 +990,7 @@ export function createMcpServer(deps) {
                 idempotentHint: true,
                 openWorldHint: true,
             },
-        }, async (args) => getFactHistoryHandler(deps, args));
+        }, async (args) => getFactHistoryHandler(deps, tenantId, args));
         server.registerTool("supersede_fact", {
             title: "Supersede a Stale NLM Fact",
             description: SUPERSEDE_FACT_DESCRIPTION,
@@ -779,7 +1010,7 @@ export function createMcpServer(deps) {
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (args) => supersedeFactHandler(deps, args));
+        }, async (args) => supersedeFactHandler(deps, tenantId, args));
     }
     server.registerTool("cite_session", {
         title: "Cite NLM Session",
@@ -801,7 +1032,40 @@ export function createMcpServer(deps) {
             idempotentHint: false,
             openWorldHint: false,
         },
-    }, async (args) => citeSessionHandler(args));
+    }, async (args) => citeSessionHandler(tenantId, args));
+    if (deps.signalStore && deps.installScope !== undefined) {
+        server.registerTool("report_outcome", {
+            title: "Report Session Outcome",
+            description: REPORT_OUTCOME_DESCRIPTION,
+            inputSchema: {
+                session_id: z
+                    .string()
+                    .optional()
+                    .describe("NLM session ID this outcome applies to. Required if correlation_key is omitted."),
+                correlation_key: z
+                    .string()
+                    .optional()
+                    .describe("External correlation identifier (e.g. a CI run id) when no NLM session_id is known. Required if session_id is omitted."),
+                outcome: z
+                    .enum(SIGNAL_OUTCOMES)
+                    .describe("pass = held. fail | fix | exhausted = overturned."),
+                source_of_record: z
+                    .string()
+                    .min(1)
+                    .describe("The deterministic system asserting this outcome (e.g. \"ci:github-actions\", \"hook:post-tool-use\")."),
+                detail: z
+                    .record(z.string(), z.unknown())
+                    .optional()
+                    .describe("Optional passthrough context, stored on the signal row."),
+            },
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (args) => reportOutcomeHandler(deps, tenantId, args));
+    }
     server.registerTool("mark_superseded", {
         title: "Mark NLM Session Superseded",
         description: MARK_SUPERSEDED_DESCRIPTION,
@@ -825,7 +1089,7 @@ export function createMcpServer(deps) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async (args) => markSupersededHandler(deps, args));
+    }, async (args) => markSupersededHandler(deps, tenantId, args));
     server.registerTool("work_summary", {
         title: "Daily work summary",
         description: "The operator's agent-assisted work recap for a day: where attention went (active time by topic), focus quality (context switches, longest block), and progress (decisions, open loops). Optional `date` (YYYY-MM-DD); defaults to today.",
@@ -837,7 +1101,7 @@ export function createMcpServer(deps) {
                 .describe("Day to summarize, YYYY-MM-DD. Defaults to today."),
         },
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    }, async (args) => workSummaryHandler(deps, args));
+    }, async (args) => workSummaryHandler(deps, tenantId, args));
     server.registerTool("recall_workstream", {
         title: "Recall a workstream's accumulated context",
         description: "Return the coherent project view for a workstream: its member sessions, current decisions and open loops, accumulated facts, and code exemplars. Accepts a workstream id or label; merge chains resolve to the live workstream.",
@@ -845,7 +1109,7 @@ export function createMcpServer(deps) {
             idOrLabel: z.string().describe("Workstream id (ws_...) or label (e.g. 'NLM')."),
         },
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    }, async (args) => recallWorkstreamHandler(deps, args, mcpRuntimeFromClient(server.server.getClientVersion())));
+    }, async (args) => recallWorkstreamHandler(deps, tenantId, args, mcpRuntimeFromClient(server.server.getClientVersion())));
     server.registerTool("rebind_session", {
         title: "Rebind a session to a different workstream",
         description: "Move a session's primary workstream binding (operator correction). Sets binding_source=operator. The session's facts and exemplars roll up under the new workstream automatically (rollup is by session binding).",
@@ -854,7 +1118,7 @@ export function createMcpServer(deps) {
             workstream: z.string().describe("Target workstream id (ws_...) or label."),
         },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    }, async (args) => rebindSessionHandler(deps, args));
+    }, async (args) => rebindSessionHandler(deps, tenantId, args));
     server.registerTool("merge_workstreams", {
         title: "Merge one workstream into another",
         description: "Supersede a duplicate workstream into the one to keep: sets merged_into, marks it merged, and unions its entity index. Sessions, facts, and exemplars resolve to the survivor automatically (no session rewrite). Accepts ids or labels; merge chains resolve.",
@@ -863,7 +1127,7 @@ export function createMcpServer(deps) {
             into: z.string().describe("Workstream to keep (the survivor); id or label."),
         },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-    }, async (args) => mergeWorkstreamsHandler(deps, args));
+    }, async (args) => mergeWorkstreamsHandler(deps, tenantId, args));
     server.registerTool("rename_workstream", {
         title: "Rename a workstream",
         description: "Relabel a workstream. Refuses a label that collides with a different existing workstream's normalized label (prevents accidental duplicates). Accepts id or label.",
@@ -872,19 +1136,19 @@ export function createMcpServer(deps) {
             label: z.string().describe("New label."),
         },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    }, async (args) => renameWorkstreamHandler(deps, args));
+    }, async (args) => renameWorkstreamHandler(deps, tenantId, args));
     server.registerTool("retire_workstream", {
         title: "Retire a workstream",
         description: "Mark a workstream retired (status=retired). Operator cleanup for dead one-off workstreams. Reversible by re-setting status. Accepts id or label.",
         inputSchema: { idOrLabel: z.string().describe("Workstream id or label.") },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    }, async (args) => retireWorkstreamHandler(deps, args));
+    }, async (args) => retireWorkstreamHandler(deps, tenantId, args));
     server.registerTool("list_merge_suggestions", {
         title: "Suggest duplicate workstreams to merge",
         description: "Score active workstream pairs by shared entities, co-occurring sessions, and label similarity; list likely duplicates for one-click merge_workstreams. Computed on demand; read-only.",
         inputSchema: { minScore: z.number().optional().describe("Minimum similarity score 0..1 (default 0.5).") },
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    }, async (args) => listMergeSuggestionsHandler(deps, args));
+    }, async (args) => listMergeSuggestionsHandler(deps, tenantId, args));
     if (deps.exemplarStore &&
         deps.installScope &&
         process.env["NLM_CODE_EXEMPLARS_ENABLED"] === "1") {
@@ -926,7 +1190,7 @@ export function createMcpServer(deps) {
                 openWorldHint: false,
             },
         }, async (args) => {
-            const result = await recallCode({
+            const result = await recallCode(tenantId, {
                 query: args.query,
                 installScope,
                 ...(args.repo ? { repo: args.repo } : {}),
@@ -939,7 +1203,7 @@ export function createMcpServer(deps) {
                 ...result.positives.map((e) => e.id),
                 ...result.negatives.map((e) => e.id),
             ];
-            void logQuery({
+            void logQuery(tenantId, {
                 source: "mcp",
                 runtime: mcpRuntimeFromClient(server.server.getClientVersion()),
                 query: args.query,
@@ -972,10 +1236,69 @@ export function createMcpServer(deps) {
             if (patch.retired === undefined && patch.outcome === undefined) {
                 return { content: [{ type: "text", text: JSON.stringify({ error: "provide retire and/or outcome" }) }] };
             }
-            const res = await exemplarStore.setVerdict(a.exemplar_id, patch, "human");
+            const res = await exemplarStore.setVerdict(tenantId, a.exemplar_id, patch, "human");
             return { content: [{ type: "text", text: JSON.stringify({ exemplar_id: a.exemplar_id, status: res.status }) }] };
         });
     }
+    if (deps.learners) {
+        server.registerTool("learner_enroll", {
+            title: "Enroll Learner in Course",
+            description: LEARNER_ENROLL_DESCRIPTION,
+            inputSchema: {
+                learner: z.string().min(1).describe("Learner id (lowercase slug). Auto-created on first enroll."),
+                label: z.string().optional().describe("Display label for a new learner; defaults to the id."),
+                course: z.string().min(1).describe("Course id (lowercase slug)."),
+                workstream: z.string().min(1).describe("Workstream id or label to bind the enrollment to."),
+                plan_ref: z.string().min(1).describe("Caller-side course plan reference (NLM stores the ref, not the plan)."),
+                plan_revision: z.number().int().min(1).describe("Plan revision; a changed plan must bump, never silently upsert."),
+                plan_fingerprint: z.string().min(1).describe("Plan content fingerprint; mismatch blocks writes until reconciled."),
+            },
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        }, async (args) => learnerEnrollHandler(deps, tenantId, args));
+        server.registerTool("learner_record", {
+            title: "Record Learning Event",
+            description: LEARNER_RECORD_DESCRIPTION,
+            inputSchema: {
+                learner: z.string().min(1).describe("Learner id."),
+                course: z.string().min(1).describe("Course id."),
+                event: z.object({
+                    id: z.string().min(1).describe("Event id (lowercase slug, unique per enrollment)."),
+                    date: z.string().describe("ISO date YYYY-MM-DD, never in the future."),
+                    covered: z.array(z.string()).describe("Concept ids covered (subject.concept)."),
+                    attempts: z.array(z.object({
+                        concept: z.string().describe("Concept id attempted."),
+                        task: z.string().min(1).describe("The task given."),
+                        response: z.string().min(1).describe("Short excerpt of the learner's response."),
+                        result: z.enum(["correct", "partial", "incorrect"]),
+                        help: z.enum(["none", "hint", "worked-example"]),
+                        kind: z.enum(["application", "retrieval", "transfer"]),
+                    })).describe("Per-concept attempts (may be empty for an untested lesson)."),
+                    interpretation: z.string().describe("Tentative explanation of the evidence (may be empty)."),
+                    next_step: z.string().min(1).describe("What the next teacher should try or ask."),
+                }).describe("The learning event to record."),
+            },
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        }, async (args) => learnerRecordHandler(deps, tenantId, args));
+        server.registerTool("learner_summary", {
+            title: "Summarize Learner Progress",
+            description: LEARNER_SUMMARY_DESCRIPTION,
+            inputSchema: {
+                learner: z.string().min(1).describe("Learner id."),
+                course: z.string().optional().describe("Course id. Omit only when exactly one active enrollment exists."),
+                limit: z.number().int().min(1).max(200).optional().describe("Max concepts to list (default 50)."),
+            },
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        }, async (args) => learnerSummaryHandler(deps, tenantId, args));
+        server.registerTool("learner_complete_course", {
+            title: "Complete Learner Course",
+            description: LEARNER_COMPLETE_DESCRIPTION,
+            inputSchema: {
+                learner: z.string().min(1).describe("Learner id."),
+                course: z.string().min(1).describe("Course id."),
+            },
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        }, async (args) => learnerCompleteHandler(deps, tenantId, args));
+    }
     return server;
 }
 const RECALL_CODE_DESCRIPTION = `\