nlm-memory 0.21.0 → 0.21.13

package/dist/http/app.js

@@ -19,7 +19,6 @@
  */
 import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { timingSafeEqual } from "node:crypto";
-import { homedir } from "node:os";
 import { dirname, extname, join, normalize, sep } from "node:path";
 import { Hono } from "hono";
 import pkg from "../../package.json" with { type: "json" };
@@ -39,6 +38,7 @@ import { classifyPrompt } from "../core/hook/gate.js";
 import { selectHits } from "../core/hook/select.js";
 import { formatPointerBlock } from "../core/hook/pointer-block.js";
 import { factRecallStats, logFactQuery } from "../core/recall-facts/fact-query-log.js";
+import { pickRelatedConcepts } from "../core/recall/related-concepts.js";
 import { buildDataset } from "../core/dataset/build-dataset.js";
 import { ClassifierBox } from "../llm/classifier-box.js";
 import { SourceRegistry, PgSourceRegistry, } from "../core/sources/source-registry.js";
@@ -62,6 +62,10 @@ import { laneHealthSnapshot } from "../core/health/embedding-lane-state.js";
 import { inflightSnapshot } from "../core/health/embed-inflight.js";
 import { corpusSnapshot } from "../core/health/corpus-state.js";
 import { DEFAULT_NLM_PORT } from "../shared/net.js";
+import { DEFAULT_TEAM_ID } from "../core/tenancy/default-team.js";
+import { tenantStatePath } from "../core/tenancy/tenant-state-path.js";
+import { isHostedMode } from "../core/tenancy/hosted-mode.js";
+import { resolveTeamByToken } from "../core/tenancy/team-auth.js";
 const HERMES_RELATIVE_FLOOR = parseRelativeFloor(process.env["NLM_RECALL_REL_FLOOR"], 0.9);
 const MIME_TYPES = {
     ".html": "text/html; charset=utf-8",
@@ -87,6 +91,16 @@ const DATA_STAT_TABLES = [
     "sources",
     "providers",
 ];
+/**
+ * Tenancy (program spec §4.6 disposition LOCAL, M2 plan Wave B6): `GET
+ * /api/data/stats` is a LOCAL-dispositioned route (spec §4.6) — hard-403'd
+ * under `NLM_HOSTED=1` by Wave C's hosted-mode gate, same class as
+ * `/api/dataset` and `/api/data/backup`. These are per-table row counts +
+ * migration bookkeeping for the Settings → Data page, not corpus content;
+ * left whole-DB deliberately rather than fake-filtered by tenant, which
+ * would misrepresent what the counts mean (they're meant to show the whole
+ * install's state, e.g. for a local operator sanity-checking their db).
+ */
 function sqliteDataStats(db, dbPath) {
     const countOf = (table) => {
         try {
@@ -219,7 +233,8 @@ const VALID_FACT_KINDS = ["decision", "open", "attribute"];
 export function createApp(deps) {
     const app = new Hono();
     const boundPort = process.env["NLM_PORT"] ? Number.parseInt(process.env["NLM_PORT"], 10) : Number.parseInt(DEFAULT_NLM_PORT, 10);
-    installLocalOnlyMiddleware(app, boundPort);
+    installLocalOnlyMiddleware(app, boundPort, deps);
+    installHostedModeGate(app);
     registerHealthRoute(app, deps);
     registerMcpRoute(app, deps);
     registerRecallRoutes(app, deps);
@@ -236,6 +251,7 @@ export function createApp(deps) {
     registerProviderRoutes(app, deps);
     registerSessionRoute(app, deps);
     registerSignalRoutes(app, deps);
+    registerJobRoutes(app, deps);
     const nonceStore = createNonceStore();
     registerNonceRoute(app, nonceStore);
     if (deps.uiDist) {
@@ -270,25 +286,68 @@ function registerNonceRoute(app, nonceStore) {
 function uiAuthMode() {
     return process.env["NLM_UI_AUTH"] === "cookie" ? "cookie" : "none";
 }
-function installLocalOnlyMiddleware(app, boundPort) {
+/**
+ * Tenant resolution + auth for every /api/* request (program spec §3, M3).
+ * Host/Origin checks are network-position defenses and stay skippable under
+ * VITEST/NODE_ENV=test (in-process `app.request()` calls carry no real
+ * socket). Tenant resolution does NOT skip under that flag — the contract's
+ * token-swap case (spec §6 case 8) and any other test that wires a real
+ * `teamTokens` store must exercise the actual resolveTeamByToken path, not a
+ * bypass, so a garbage token really does 401 inside a `vitest` run.
+ *
+ * Resolution order:
+ *   1. Hosted mode (NLM_HOSTED=1): a resolvable Bearer token is mandatory.
+ *      No cookie fallback, no ungated fallback — absent/unresolvable token
+ *      is 401 before any corpus read, always.
+ *   2. Local mode, NLM_UI_AUTH unset ("none", the default): zero UX change
+ *      from pre-M3 — requests resolve to DEFAULT_TEAM_ID. A resolvable
+ *      Bearer token is still honored when presented (lets local multi-team
+ *      dev and in-process tests exercise real resolution), but nothing is
+ *      ever rejected in this mode — that's the point of leaving auth off.
+ *   3. Local mode, NLM_UI_AUTH=cookie: the existing HMAC session cookie
+ *      (still keyed off NLM_MCP_TOKEN directly — unchanged, local-only
+ *      concern) resolves to DEFAULT_TEAM_ID. A Bearer token resolves via
+ *      the same team_tokens lookup as every other transport instead of the
+ *      old exact-string compare; unresolved token or no credential is 401.
+ */
+function installLocalOnlyMiddleware(app, boundPort, deps) {
     const skipLocalGate = !!process.env["VITEST"] || process.env["NODE_ENV"] === "test";
     const extras = parseAllowedOrigins(process.env["NLM_ALLOWED_ORIGINS"] ?? "");
     app.use("/api/*", async (c, next) => {
-        if (skipLocalGate)
-            return next();
-        const host = c.req.header("host");
-        if (!isLoopbackHost(host, boundPort) && !extras.hosts.has(host?.toLowerCase() ?? "")) {
-            return c.json({ error: "host header not allowed" }, 403);
+        if (!skipLocalGate) {
+            const host = c.req.header("host");
+            if (!isLoopbackHost(host, boundPort) && !extras.hosts.has(host?.toLowerCase() ?? "")) {
+                return c.json({ error: "host header not allowed" }, 403);
+            }
         }
         if (c.req.path === "/api/health") {
             return next();
         }
-        const origin = c.req.header("origin");
-        if (origin !== undefined && !isLoopbackOrigin(origin, boundPort) && !extras.origins.has(origin.toLowerCase())) {
-            return c.json({ error: "origin not allowed" }, 403);
+        if (!skipLocalGate) {
+            const origin = c.req.header("origin");
+            if (origin !== undefined && !isLoopbackOrigin(origin, boundPort) && !extras.origins.has(origin.toLowerCase())) {
+                return c.json({ error: "origin not allowed" }, 403);
+            }
+        }
+        const auth = c.req.header("authorization") ?? "";
+        const match = /^Bearer\s+(\S+)$/i.exec(auth);
+        const presentedToken = match?.[1];
+        if (isHostedMode()) {
+            const resolved = deps.teamTokens ? await resolveTeamByToken(deps.teamTokens, presentedToken) : null;
+            if (!resolved)
+                return c.json({ error: "unauthorized" }, 401);
+            c.set("tenantId", resolved.teamId);
+            return next();
         }
         if (uiAuthMode() === "none") {
-            // Auth disabled by user. Loopback Host + Origin checks already passed.
+            // Auth disabled by user (or never configured). Loopback Host + Origin
+            // checks already passed. A resolvable token still wins when present;
+            // otherwise fall back to the single local operator team exactly as
+            // before M3 — this mode never rejects a request.
+            const resolved = presentedToken && deps.teamTokens
+                ? await resolveTeamByToken(deps.teamTokens, presentedToken)
+                : null;
+            c.set("tenantId", resolved ? resolved.teamId : DEFAULT_TEAM_ID);
             return next();
         }
         const token = process.env["NLM_MCP_TOKEN"];
@@ -299,26 +358,55 @@ function installLocalOnlyMiddleware(app, boundPort) {
         }
         // UI session cookie (HMAC of the token, set by /ui/auth bootstrap).
         // Carries the browser's API calls and survives token-stable restarts.
+        // Local-only concern (program spec §3 M3): unchanged, always resolves
+        // to the single local operator team.
         const cookies = parseCookies(c.req.header("cookie"));
         if (verifySessionCookie(cookies[SESSION_COOKIE_NAME], token)) {
             // Rolling expiry: every authenticated hit re-issues Set-Cookie so an
             // actively-used session never sees an expiry. Only 30 days of true
             // inactivity force a re-bootstrap.
             c.header("Set-Cookie", buildSessionCookie(deriveSessionValue(token)));
+            c.set("tenantId", DEFAULT_TEAM_ID);
             return next();
         }
         // Bearer: programmatic clients (Hermes WebUI, agents, the MCP path).
-        // Same secret as the cookie HMAC derives from, but transmitted directly.
-        const auth = c.req.header("authorization") ?? "";
-        const match = /^Bearer\s+(\S+)$/i.exec(auth);
-        const given = Buffer.from(match?.[1] ?? "", "utf8");
-        const want = Buffer.from(token, "utf8");
-        if (match && given.length === want.length && timingSafeEqual(given, want)) {
+        // Resolved via the same team_tokens lookup every other transport uses.
+        const resolved = presentedToken && deps.teamTokens
+            ? await resolveTeamByToken(deps.teamTokens, presentedToken)
+            : null;
+        if (resolved) {
+            c.set("tenantId", resolved.teamId);
             return next();
         }
         return c.json({ error: "unauthorized" }, 401);
     });
 }
+const HOSTED_GATED_ROUTES = [
+    { method: "GET", path: "/api/dataset", disposition: "LOCAL" },
+    { method: "GET", path: "/api/data/backup", disposition: "LOCAL" },
+    { method: "POST", path: "/api/data/restore", disposition: "LOCAL" },
+    { method: "GET", path: "/api/data/stats", disposition: "LOCAL" },
+    { method: "POST", path: "/api/classifier", disposition: "LOCAL" },
+    // Single-operator process supervision — starting/stopping the daemon's
+    // own reprocess child has no per-tenant meaning, same LOCAL class as the
+    // classifier swap above.
+    { method: "POST", path: "/api/jobs/reprocess", disposition: "LOCAL" },
+    { method: "DELETE", path: "/api/jobs/reprocess", disposition: "LOCAL" },
+];
+function installHostedModeGate(app) {
+    const gated = new Map();
+    for (const r of HOSTED_GATED_ROUTES)
+        gated.set(`${r.method} ${r.path}`, r.disposition);
+    app.use("/api/*", async (c, next) => {
+        if (!isHostedMode())
+            return next();
+        const disposition = gated.get(`${c.req.method} ${c.req.path}`);
+        if (disposition) {
+            return c.json({ error: `route disabled in hosted mode (disposition: ${disposition})`, disposition }, 403);
+        }
+        return next();
+    });
+}
 // ── UI session-cookie gate ───────────────────────────────────────────
 //
 // Closes the port-forward bypass: any client reaching localhost:3940
@@ -416,7 +504,13 @@ function registerHealthRoute(app, deps) {
             latest: cachedUpdate.disabled ? null : cachedUpdate.latest,
             behind: cachedUpdate.disabled ? false : cachedUpdate.behind,
         };
-        return c.json({ status: "ok", service: "nlm-memory", version: pkg.version, warmup: warmupSnapshot(), embedding: laneHealthSnapshot(), embedInflight: inflightSnapshot(), corpus, update });
+        // "idle" (never started, or this daemon process's initial state — see
+        // job-supervisor.ts) reports as `job: null` rather than an idle block:
+        // an operator polling /api/health wants to know whether a run exists,
+        // not to distinguish "never run" from a five-field block of zeros.
+        const jobSnap = deps.jobSupervisor ? deps.jobSupervisor.snapshot() : null;
+        const job = jobSnap && jobSnap.state !== "idle" ? jobSnap : null;
+        return c.json({ status: "ok", service: "nlm-memory", version: pkg.version, warmup: warmupSnapshot(), embedding: laneHealthSnapshot(), embedInflight: inflightSnapshot(), corpus, update, job });
     });
     // Passive update poll for the UI. Same daily-cached check the CLI
     // startup banner uses — see src/core/update-check/check.ts for the
@@ -433,30 +527,33 @@ function registerHealthRoute(app, deps) {
 function registerMcpRoute(app, deps) {
     if (!deps.mcpDeps)
         return;
-    const mcpToken = process.env["NLM_MCP_TOKEN"];
-    if (!mcpToken) {
-        throw new Error("NLM_MCP_TOKEN must be set when mcpDeps is provided — " +
+    if (!deps.teamTokens) {
+        throw new Error("teamTokens must be wired when mcpDeps is provided — " +
             "refusing to mount an unauthenticated /mcp endpoint");
     }
     const capturedMcpDeps = deps.mcpDeps;
+    const teamTokens = deps.teamTokens;
     app.all("/mcp", async (c) => {
         const auth = c.req.header("authorization") ?? "";
         const match = /^Bearer\s+(\S+)$/i.exec(auth);
-        const given = Buffer.from(match?.[1] ?? "", "utf8");
-        const want = Buffer.from(mcpToken, "utf8");
-        if (!match || given.length !== want.length || !timingSafeEqual(given, want)) {
+        const resolved = await resolveTeamByToken(teamTokens, match?.[1]);
+        if (!resolved) {
             return c.json({ error: "unauthorized" }, 401);
         }
         // No sessionIdGenerator = stateless mode: no session ID in responses,
         // no session validation. Correct for per-request agent calls.
         const transport = new WebStandardStreamableHTTPServerTransport({});
-        const server = createMcpServer(capturedMcpDeps);
+        const server = createMcpServer(capturedMcpDeps, resolved.teamId);
         await server.connect(transport);
         return transport.handleRequest(c.req.raw);
     });
 }
 function registerRecallRoutes(app, deps) {
     app.get("/api/recall", async (c) => {
+        // Composition point for this request (program spec §3 M3): the tenant
+        // the general gate resolved from the Bearer token / cookie / local-mode
+        // default, stashed on the Hono context by installLocalOnlyMiddleware.
+        const tenantId = c.get("tenantId");
         const q = c.req.query("q") ?? "";
         const entity = c.req.query("entity");
         const kind = c.req.query("kind");
@@ -500,6 +597,18 @@ function registerRecallRoutes(app, deps) {
         else if (source === "hook") {
             withRelatedFacts = true;
         }
+        // Learner evidence (spec 2026-10-06): `?withConcepts=true` (or hook
+        // source = automatic) attaches a relatedConcepts array. Same posture
+        // as facts; empty when no enrollments match, so non-learner callers
+        // see zero behavior change.
+        const conceptsParam = c.req.query("withConcepts");
+        let withRelatedConcepts;
+        if (conceptsParam !== undefined) {
+            withRelatedConcepts = conceptsParam === "true" || conceptsParam === "1";
+        }
+        else if (source === "hook") {
+            withRelatedConcepts = true;
+        }
         // Spec §E: `?withExemplars=true` attaches relatedExemplars (passive code exemplar recall).
         const withExemplars = c.req.query("withExemplars") === "true";
         // Task #303: superseded sessions are opt-in over HTTP and DEFAULT OFF.
@@ -515,12 +624,13 @@ function registerRecallRoutes(app, deps) {
             ...(kind !== undefined ? { kind: kind } : {}),
             ...(rewrite !== undefined ? { rewrite } : {}),
             ...(withRelatedFacts !== undefined ? { withRelatedFacts } : {}),
+            ...(withRelatedConcepts !== undefined ? { withRelatedConcepts } : {}),
             ...(withExemplars ? { withRelatedExemplars: true } : {}),
             ...(includeSuperseded !== undefined ? { includeSuperseded } : {}),
         };
-        const result = await deps.recall.search(query);
+        const result = await deps.recall.search(tenantId, query);
         // Fire-and-forget telemetry — never blocks the response.
-        void logQuery({
+        void logQuery(tenantId, {
             source,
             runtime,
             query: q || null,
@@ -535,22 +645,29 @@ function registerRecallRoutes(app, deps) {
         return c.json(result);
     });
     app.get("/api/recall/stats", async (c) => {
+        const tenantId = c.get("tenantId");
         const daysStr = c.req.query("days") ?? "7";
         const days = Number.parseInt(daysStr, 10);
         if (!Number.isFinite(days) || days < 1 || days > 365) {
             return c.json({ error: "days must be 1..365" }, 400);
         }
-        const stats = await recallStats(days, ...(deps.queryLogPath !== undefined ? [deps.queryLogPath] : []));
+        const stats = await recallStats(tenantId, days, ...(deps.queryLogPath !== undefined ? [deps.queryLogPath] : []));
         return c.json(stats);
     });
     app.get("/api/recall/recent", (c) => {
-        const limit = parseLimit(c.req.query("limit"), 50, 200);
-        const entries = recentQueryLog(limit, ...(deps.queryLogPath !== undefined ? [deps.queryLogPath] : []));
+        const tenantId = c.get("tenantId");
+        // Cap raised from 200: consumers strip probe traffic client-side, so the
+        // window has to hold a full day of RAW entries. A host emitting ~800
+        // probes/day filled all 200 rows with probes inside 7h, and the digest
+        // reported "0 queries yesterday" on a day with 27 real ones (2026-08-13).
+        const limit = parseLimit(c.req.query("limit"), 50, 5000);
+        const entries = recentQueryLog(tenantId, limit, ...(deps.queryLogPath !== undefined ? [deps.queryLogPath] : []));
         return c.json({ entries });
     });
     // Citation events from the Stop hook. One POST per surfaced ID the
     // assistant cited in its response. Feeds the recall precision metric.
     app.post("/api/recall/cite-event", async (c) => {
+        const tenantId = c.get("tenantId");
         let body;
         try {
             body = (await c.req.json());
@@ -568,7 +685,7 @@ function registerRecallRoutes(app, deps) {
         }
         const responsePreview = body["response_preview"];
         const kind = body["kind"];
-        await appendCitation({
+        await appendCitation(tenantId, {
             conversationId,
             citedId,
             ...(kind === "tool_use" || kind === "prose" ? { kind } : {}),
@@ -579,12 +696,13 @@ function registerRecallRoutes(app, deps) {
         return c.json({ ok: true });
     });
     app.get("/api/recall/cite-stats", async (c) => {
+        const tenantId = c.get("tenantId");
         const daysStr = c.req.query("days") ?? "7";
         const days = Number.parseInt(daysStr, 10);
         if (!Number.isFinite(days) || days < 1 || days > 365) {
             return c.json({ error: "days must be 1..365" }, 400);
         }
-        const stats = await citationStats(days, ...(deps.citationLogPath !== undefined ? [deps.citationLogPath] : []));
+        const stats = await citationStats(tenantId, days, ...(deps.citationLogPath !== undefined ? [deps.citationLogPath] : []));
         return c.json(stats);
     });
     // Explicit citation from the cite_session MCP tool. One POST per session
@@ -592,6 +710,7 @@ function registerRecallRoutes(app, deps) {
     // so the training extractor can distinguish deterministic tool citations
     // from stop-hook detected prose citations.
     app.post("/api/citation/explicit", async (c) => {
+        const tenantId = c.get("tenantId");
         let body;
         try {
             body = (await c.req.json());
@@ -603,10 +722,10 @@ function registerRecallRoutes(app, deps) {
         if (typeof id !== "string" || !id) {
             return c.json({ error: "id required" }, 400);
         }
-        await appendCitation({
+        await appendCitation(tenantId, {
             conversationId: typeof body["conversation_id"] === "string"
                 ? body["conversation_id"]
-                : (resolveConversationForSession(id) ?? "mcp_tool"),
+                : (resolveConversationForSession(tenantId, id) ?? "mcp_tool"),
             citedId: id,
             kind: "tool_use",
             ...(typeof body["reason"] === "string" ? { responsePreview: body["reason"] } : {}),
@@ -621,6 +740,7 @@ function registerHookRoutes(app) {
     // suppressed by stale "already surfaced" gates.
     // Payload: { conversation_id, transcript_path?, surfaced_set?, ts? }
     app.post("/api/hook/pre-compact", async (c) => {
+        const tenantId = c.get("tenantId");
         let body;
         try {
             body = (await c.req.json());
@@ -632,10 +752,18 @@ function registerHookRoutes(app) {
         if (typeof conversationId !== "string" || !conversationId) {
             return c.json({ error: "conversation_id required" }, 400);
         }
-        const flushed = loadSurfaced(conversationId).size;
-        clearSurfaced(conversationId);
+        const flushed = loadSurfaced(tenantId, conversationId).size;
+        clearSurfaced(tenantId, conversationId);
         const compactedAt = new Date().toISOString();
-        const logPath = process.env["NLM_HOOK_LOG"] ?? join(homedir(), ".nlm", "hook-log.jsonl");
+        // Mirrors hook-log.ts's own path derivation (core/tenancy/tenant-state-path.ts):
+        // the default team's log honors NLM_HOOK_LOG; every other tenant is isolated
+        // under ~/.nlm/tenants/<tenantId>/hook-log.jsonl. This route writes a
+        // differently-shaped record (`kind: "pre-compact"`) than appendHookLog's
+        // HookLogEntry, so it can't reuse that function directly, but must still
+        // land in the same tenant-scoped file.
+        const logPath = tenantId === DEFAULT_TEAM_ID
+            ? (process.env["NLM_HOOK_LOG"] ?? tenantStatePath(tenantId, "hook-log.jsonl"))
+            : tenantStatePath(tenantId, "hook-log.jsonl");
         try {
             mkdirSync(dirname(logPath), { recursive: true });
             appendFileSync(logPath, `${JSON.stringify({ ts: compactedAt, kind: "pre-compact", conversationId, flushed })}\n`, "utf8");
@@ -679,7 +807,8 @@ function registerHermesAgentHookRoutes(app, deps) {
             return c.json({ context: null });
         }
         try {
-            const result = await deps.recall.search({
+            const tenantId = c.get("tenantId");
+            const result = await deps.recall.search(tenantId, {
                 query: userMessage,
                 mode: "keyword",
                 limit: 5,
@@ -692,7 +821,7 @@ function registerHermesAgentHookRoutes(app, deps) {
                 startedAt: r.startedAt,
                 matchScore: r.matchScore,
             }));
-            const surfaced = loadSurfaced(sessionId);
+            const surfaced = loadSurfaced(tenantId, sessionId);
             const selected = selectHits({ hits, surfaced, scoreThreshold: 0, relativeFloor: HERMES_RELATIVE_FLOOR, perFireCap: 3, perConversationCap: 10 });
             if (selected.length === 0 &&
                 (result.relatedFacts ?? []).length === 0 &&
@@ -700,7 +829,7 @@ function registerHermesAgentHookRoutes(app, deps) {
                 return c.json({ context: null });
             }
             if (selected.length > 0) {
-                recordSurfaced(sessionId, selected.map((h) => h.id));
+                recordSurfaced(tenantId, sessionId, selected.map((h) => h.id));
             }
             return c.json({
                 context: formatPointerBlock(selected, result.relatedFacts ?? [], (result.relatedExemplars ?? []).map((e) => ({
@@ -715,6 +844,7 @@ function registerHermesAgentHookRoutes(app, deps) {
     // post-turn: scan assistant_response for session IDs that were surfaced in
     // this conversation and log prose citation events.
     app.post("/api/hook/hermes-agent/post-turn", async (c) => {
+        const tenantId = c.get("tenantId");
         let body;
         try {
             body = (await c.req.json());
@@ -730,7 +860,7 @@ function registerHermesAgentHookRoutes(app, deps) {
         if (typeof assistantResponse !== "string" || !assistantResponse) {
             return c.json({ ok: true, cited: 0 });
         }
-        const surfacedIds = [...loadSurfaced(sessionId)];
+        const surfacedIds = [...loadSurfaced(tenantId, sessionId)];
         const cited = [];
         for (const id of surfacedIds) {
             if (assistantResponse.includes(id))
@@ -738,13 +868,14 @@ function registerHermesAgentHookRoutes(app, deps) {
         }
         const preview = assistantResponse.slice(0, 200);
         for (const citedId of cited) {
-            await appendCitation({ conversationId: sessionId, citedId, kind: "prose", responsePreview: preview }, ...(deps.citationLogPath !== undefined ? [deps.citationLogPath] : []));
+            await appendCitation(tenantId, { conversationId: sessionId, citedId, kind: "prose", responsePreview: preview }, ...(deps.citationLogPath !== undefined ? [deps.citationLogPath] : []));
         }
         return c.json({ ok: true, cited: cited.length });
     });
     // session-lifecycle: memo housekeeping for on_session_{start,end,finalize,reset}.
     // start is a no-op (memo is created lazily). end/finalize/reset clear the memo.
     app.post("/api/hook/hermes-agent/session-lifecycle", async (c) => {
+        const tenantId = c.get("tenantId");
         let body;
         try {
             body = (await c.req.json());
@@ -759,8 +890,8 @@ function registerHermesAgentHookRoutes(app, deps) {
         if (event !== "start") {
             const sessionId = body["session_id"];
             if (typeof sessionId === "string" && sessionId) {
-                clearSurfaced(sessionId);
-                clearCited(sessionId);
+                clearSurfaced(tenantId, sessionId);
+                clearCited(tenantId, sessionId);
             }
         }
         return c.json({ ok: true, event });
@@ -772,6 +903,7 @@ function registerFactRoutes(app, deps) {
         if (!deps.factRecall) {
             return c.json({ error: "fact recall not wired in this deployment" }, 503);
         }
+        const tenantId = c.get("tenantId");
         const q = c.req.query("q") ?? "";
         const subject = c.req.query("subject");
         const predicate = c.req.query("predicate");
@@ -807,10 +939,10 @@ function registerFactRoutes(app, deps) {
             ...(kind !== undefined ? { kind: kind } : {}),
             ...(minConfidence !== undefined ? { minConfidence } : {}),
         };
-        const result = await deps.factRecall.search(query);
+        const result = await deps.factRecall.search(tenantId, query);
         const source = c.req.header("x-recall-source") ?? "http";
         const runtime = c.req.header("x-recall-runtime") ?? null;
-        void logFactQuery({
+        void logFactQuery(tenantId, {
             source,
             runtime,
             query: q || null,
@@ -837,31 +969,40 @@ function registerFactRoutes(app, deps) {
             return c.json({ error: "subject is required" }, 400);
         }
         const predicate = c.req.query("predicate");
-        const chains = await deps.factStore.getHistory(subject, predicate);
+        const tenantId = c.get("tenantId");
+        const chains = await deps.factStore.getHistory(tenantId, subject, predicate);
         return c.json({ subject, predicate: predicate ?? null, chains });
     });
     app.get("/api/recall/facts/stats", async (c) => {
+        const tenantId = c.get("tenantId");
         const daysStr = c.req.query("days") ?? "7";
         const days = Number.parseInt(daysStr, 10);
         if (!Number.isFinite(days) || days < 1 || days > 365) {
             return c.json({ error: "days must be 1..365" }, 400);
         }
-        const stats = await factRecallStats(days, ...(deps.factQueryLogPath !== undefined ? [deps.factQueryLogPath] : []));
+        const stats = await factRecallStats(tenantId, days, ...(deps.factQueryLogPath !== undefined ? [deps.factQueryLogPath] : []));
         return c.json(stats);
     });
 }
 function registerLiveRoutes(app, deps) {
-    app.get("/api/live/recent-writes", (c) => {
+    // Pre-existing bug fixed in passing (C2): PgSessionStore's recentWrites/
+    // recentMarkers are async (return a Promise), but SqliteSessionStore's are
+    // synchronous — these handlers must be async + await the call so pg
+    // callers get the resolved array, not an unresolved Promise serialized as
+    // JSON.
+    app.get("/api/live/recent-writes", async (c) => {
         if (!deps.liveStore)
             return c.json({ writes: [] });
+        const tenantId = c.get("tenantId");
         const limit = parseLimit(c.req.query("limit"), 50, 200);
-        return c.json({ writes: deps.liveStore.recentWrites(limit) });
+        return c.json({ writes: await deps.liveStore.recentWrites(tenantId, limit) });
     });
-    app.get("/api/live/recent-markers", (c) => {
+    app.get("/api/live/recent-markers", async (c) => {
         if (!deps.liveStore)
             return c.json({ markers: [] });
+        const tenantId = c.get("tenantId");
         const limit = parseLimit(c.req.query("limit"), 50, 200);
-        return c.json({ markers: deps.liveStore.recentMarkers(limit) });
+        return c.json({ markers: await deps.liveStore.recentMarkers(tenantId, limit) });
     });
 }
 function registerDatasetRoute(app, deps) {
@@ -869,7 +1010,7 @@ function registerDatasetRoute(app, deps) {
         if (!deps.dbPath)
             return c.json({ error: "dataset endpoint requires dbPath" }, 503);
         const includePaths = c.req.query("include_paths") === "true";
-        return c.json(buildDataset(deps.dbPath, { includePaths }));
+        return c.json(buildDataset(deps.dbPath, DEFAULT_TEAM_ID, { includePaths }));
     });
 }
 // ── Data management ─────────────────────────────────────────────
@@ -980,9 +1121,10 @@ function registerActionRoutes(app, deps) {
         if (!parsed)
             return c.json({ error: "invalid action payload" }, 400);
         const store = deps.liveStore;
+        const tenantId = c.get("tenantId");
         const id = store instanceof PgSessionStore
-            ? await writeActionPg(store.pool, parsed)
-            : writeAction(store.rawDb(), parsed);
+            ? await writeActionPg(store.pool, tenantId, parsed)
+            : writeAction(store.rawDb(), tenantId, parsed);
         store.invalidateOverlayCache();
         return c.json({ id, timestamp: new Date().toISOString() });
     });
@@ -998,9 +1140,10 @@ function registerActionRoutes(app, deps) {
         if (inputs.length === 0)
             return c.json({ accepted: 0, ids: [] });
         const store = deps.liveStore;
+        const tenantId = c.get("tenantId");
         const ids = store instanceof PgSessionStore
-            ? await writeActionsBatchPg(store.pool, inputs)
-            : writeActionsBatch(store.rawDb(), inputs);
+            ? await writeActionsBatchPg(store.pool, tenantId, inputs)
+            : writeActionsBatch(store.rawDb(), tenantId, inputs);
         store.invalidateOverlayCache();
         return c.json({ accepted: ids.length, ids });
     });
@@ -1008,9 +1151,10 @@ function registerActionRoutes(app, deps) {
         if (!deps.liveStore)
             return c.json({ error: "actions require liveStore" }, 503);
         const store = deps.liveStore;
+        const tenantId = c.get("tenantId");
         const result = store instanceof PgSessionStore
-            ? await undoActionPg(store.pool, c.req.param("id"))
-            : undoAction(store.rawDb(), c.req.param("id"));
+            ? await undoActionPg(store.pool, tenantId, c.req.param("id"))
+            : undoAction(store.rawDb(), tenantId, c.req.param("id"));
         if (!result)
             return c.json({ error: "action not found or already undone" }, 404);
         store.invalidateOverlayCache();
@@ -1029,9 +1173,10 @@ function registerActionRoutes(app, deps) {
             ...(kind ? { kind } : {}),
         };
         const store = deps.liveStore;
+        const tenantId = c.get("tenantId");
         const rows = store instanceof PgSessionStore
-            ? await listActionsPg(store.pool, opts)
-            : listActions(store.rawDb(), opts);
+            ? await listActionsPg(store.pool, tenantId, opts)
+            : listActions(store.rawDb(), tenantId, opts);
         return c.json({ actions: rows });
     });
 }
@@ -1039,13 +1184,18 @@ function registerClassifierRoutes(app, deps) {
     app.get("/api/classifier/info", (c) => {
         const provider = deps.classifier?.provider ?? "ollama";
         const model = deps.classifier?.model ?? "qwen3.5:4b";
+        const openAiSwapAvailable = deps.classifier?.openAiSwapAvailable ?? false;
         return c.json({
             provider,
             model,
-            available_providers: ["deepseek", "ollama"],
+            available_providers: openAiSwapAvailable
+                ? ["deepseek", "ollama", "openai"]
+                : ["deepseek", "ollama"],
+            openai_swap_available: openAiSwapAvailable,
             env_present: {
                 deepseek: Boolean(process.env["DEEPSEEK_API_KEY"]),
                 ollama: true,
+                openai: openAiSwapAvailable,
             },
             default_models: {
                 deepseek: ["deepseek-v4-flash", "deepseek-v4-pro", "deepseek-chat"],
@@ -1060,8 +1210,15 @@ function registerClassifierRoutes(app, deps) {
         const body = (await c.req.json().catch(() => null));
         const provider = body?.provider;
         const model = body?.model;
-        if (provider !== "deepseek" && provider !== "ollama") {
-            return c.json({ error: "runtime swap supports 'deepseek' or 'ollama'; 'openai' is set via NLM_CLASSIFIER env + restart" }, 400);
+        // "openai-compatible" (the Providers-registry kind for local/self-hosted
+        // endpoints like LM Studio) and "openai" (the registry's real-OpenAI kind)
+        // both ride ClassifierBox's single "openai" ClassifierProvider — both are
+        // just DeepSeekClient against a baseUrl. That baseUrl is fixed at daemon
+        // startup (NLM_CLASSIFIER_BASE_URL), so this swap is model selection
+        // only, never endpoint selection.
+        const isOpenAiKind = provider === "openai" || provider === "openai-compatible";
+        if (provider !== "deepseek" && provider !== "ollama" && !isOpenAiKind) {
+            return c.json({ error: "runtime swap supports 'deepseek', 'ollama', 'openai', or 'openai-compatible'" }, 400);
         }
         if (!model || typeof model !== "string" || model.length === 0) {
             return c.json({ error: "model is required" }, 400);
@@ -1069,7 +1226,14 @@ function registerClassifierRoutes(app, deps) {
         if (provider === "deepseek" && !process.env["DEEPSEEK_API_KEY"]) {
             return c.json({ error: "DEEPSEEK_API_KEY not set — cannot swap to deepseek" }, 400);
         }
-        deps.classifier.swap(provider, model);
+        if (isOpenAiKind && !deps.classifier.openAiSwapAvailable) {
+            return c.json({
+                error: "provider 'openai' has no baseUrl configured — set NLM_CLASSIFIER=openai and " +
+                    "NLM_CLASSIFIER_BASE_URL, then restart the daemon before swapping models on it",
+            }, 400);
+        }
+        const classifierProvider = isOpenAiKind ? "openai" : provider;
+        deps.classifier.swap(classifierProvider, model);
         return c.json({ provider: deps.classifier.provider, model: deps.classifier.model });
     });
 }
@@ -1080,7 +1244,8 @@ function registerSourceRoutes(app, deps) {
     app.get("/api/sources", async (c) => {
         if (!deps.sources)
             return c.json({ sources: [] });
-        return c.json({ sources: await deps.sources.list() });
+        const tenantId = c.get("tenantId");
+        return c.json({ sources: await deps.sources.list(tenantId) });
     });
     app.post("/api/sources", async (c) => {
         if (!deps.sources)
@@ -1089,10 +1254,11 @@ function registerSourceRoutes(app, deps) {
         const parsed = parseSourceInsert(body);
         if (!parsed)
             return c.json({ error: "invalid source payload" }, 400);
-        if (await deps.sources.getByName(parsed.name)) {
+        const tenantId = c.get("tenantId");
+        if (await deps.sources.getByName(tenantId, parsed.name)) {
             return c.json({ error: `source named '${parsed.name}' already exists` }, 409);
         }
-        return c.json(await deps.sources.insert(parsed), 201);
+        return c.json(await deps.sources.insert(tenantId, parsed), 201);
     });
     app.patch("/api/sources/:id", async (c) => {
         if (!deps.sources)
@@ -1104,7 +1270,8 @@ function registerSourceRoutes(app, deps) {
         const patch = parseSourceUpdate(body);
         if (!patch)
             return c.json({ error: "invalid patch payload" }, 400);
-        const updated = await deps.sources.update(id, patch);
+        const tenantId = c.get("tenantId");
+        const updated = await deps.sources.update(tenantId, id, patch);
         if (!updated)
             return c.json({ error: `source ${id} not found` }, 404);
         return c.json(updated);
@@ -1115,7 +1282,8 @@ function registerSourceRoutes(app, deps) {
         const id = Number.parseInt(c.req.param("id"), 10);
         if (!Number.isFinite(id))
             return c.json({ error: "invalid id" }, 400);
-        const ok = await deps.sources.delete(id);
+        const tenantId = c.get("tenantId");
+        const ok = await deps.sources.delete(tenantId, id);
         if (!ok)
             return c.json({ error: `source ${id} not found` }, 404);
         return c.json({ deleted: id });
@@ -1126,7 +1294,8 @@ function registerSourceRoutes(app, deps) {
         const id = Number.parseInt(c.req.param("id"), 10);
         if (!Number.isFinite(id))
             return c.json({ error: "invalid id" }, 400);
-        const token = await deps.sources.regenerateToken(id);
+        const tenantId = c.get("tenantId");
+        const token = await deps.sources.regenerateToken(tenantId, id);
         if (!token)
             return c.json({ error: "regenerate-token only applies to webhook sources" }, 400);
         return c.json({ token });
@@ -1167,7 +1336,11 @@ function registerIngestRoute(app, deps) {
             sourceId: source.id,
         };
         const ingest = deps.ingest;
-        void ingestSession(input, ingest).catch((e) => {
+        // M4 (spec §3/§8): the ingested session is stamped with the resolved
+        // source row's own tenant_id, not the caller's general-gate tenantId —
+        // ingest auth is a distinct credential (the source's webhook token)
+        // from the team_tokens Bearer auth the rest of /api/* uses.
+        void ingestSession(input, ingest, source.tenantId).catch((e) => {
             const msg = e instanceof Error ? e.message : String(e);
             console.error(`[ingest] background failure for ${id}: ${msg}`);
         });
@@ -1181,7 +1354,8 @@ function registerProviderRoutes(app, deps) {
     app.get("/api/providers", async (c) => {
         if (!deps.providers)
             return c.json({ providers: [] });
-        return c.json({ providers: await deps.providers.list() });
+        const tenantId = c.get("tenantId");
+        return c.json({ providers: await deps.providers.list(tenantId) });
     });
     app.post("/api/providers", async (c) => {
         if (!deps.providers)
@@ -1190,10 +1364,11 @@ function registerProviderRoutes(app, deps) {
         const parsed = parseProviderInsert(body);
         if (!parsed)
             return c.json({ error: "invalid provider payload" }, 400);
-        if (await deps.providers.getByName(parsed.name)) {
+        const tenantId = c.get("tenantId");
+        if (await deps.providers.getByName(tenantId, parsed.name)) {
             return c.json({ error: `provider named '${parsed.name}' already exists` }, 409);
         }
-        return c.json(await deps.providers.insert(parsed), 201);
+        return c.json(await deps.providers.insert(tenantId, parsed), 201);
     });
     app.patch("/api/providers/:id", async (c) => {
         if (!deps.providers)
@@ -1205,7 +1380,8 @@ function registerProviderRoutes(app, deps) {
         const patch = parseProviderUpdate(body);
         if (!patch)
             return c.json({ error: "invalid patch payload" }, 400);
-        const updated = await deps.providers.update(id, patch);
+        const tenantId = c.get("tenantId");
+        const updated = await deps.providers.update(tenantId, id, patch);
         if (!updated)
             return c.json({ error: `provider ${id} not found` }, 404);
         return c.json(updated);
@@ -1216,7 +1392,8 @@ function registerProviderRoutes(app, deps) {
         const id = Number.parseInt(c.req.param("id"), 10);
         if (!Number.isFinite(id))
             return c.json({ error: "invalid id" }, 400);
-        const ok = await deps.providers.delete(id);
+        const tenantId = c.get("tenantId");
+        const ok = await deps.providers.delete(tenantId, id);
         if (!ok)
             return c.json({ error: `provider ${id} not found` }, 404);
         return c.json({ deleted: id });
@@ -1227,10 +1404,11 @@ function registerProviderRoutes(app, deps) {
         const id = Number.parseInt(c.req.param("id"), 10);
         if (!Number.isFinite(id))
             return c.json({ error: "invalid id" }, 400);
-        const provider = await deps.providers.get(id);
+        const tenantId = c.get("tenantId");
+        const provider = await deps.providers.get(tenantId, id);
         if (!provider)
             return c.json({ error: `provider ${id} not found` }, 404);
-        const key = await deps.providers.getSecret(id);
+        const key = await deps.providers.getSecret(tenantId, id);
         try {
             const models = await listModels(provider, { apiKey: key });
             return c.json({ models });
@@ -1246,10 +1424,11 @@ function registerProviderRoutes(app, deps) {
         const id = Number.parseInt(c.req.param("id"), 10);
         if (!Number.isFinite(id))
             return c.json({ error: "invalid id" }, 400);
-        const provider = await deps.providers.get(id);
+        const tenantId = c.get("tenantId");
+        const provider = await deps.providers.get(tenantId, id);
         if (!provider)
             return c.json({ error: `provider ${id} not found` }, 404);
-        const key = await deps.providers.getSecret(id);
+        const key = await deps.providers.getSecret(tenantId, id);
         const startedAt = Date.now();
         try {
             const models = await listModels(provider, { apiKey: key });
@@ -1268,17 +1447,44 @@ function registerProviderRoutes(app, deps) {
 function registerSessionRoute(app, deps) {
     app.get("/api/session/:id", async (c) => {
         const id = c.req.param("id");
-        const session = await deps.store.getById(id);
+        const tenantId = c.get("tenantId");
+        const session = await deps.store.getById(tenantId, id);
         if (!session) {
             return c.json({ error: `session ${id} not found` }, 404);
         }
         return c.json(session);
     });
+    // Learner strip data for the session drawer (spec 2026-10-06 M5): concept
+    // rows for enrollments bound to this session's workstream, reusing the
+    // same picker the recall hook uses. Always 200 with possibly-empty arrays
+    // once the session resolves — the UI hides the section when empty.
+    app.get("/api/learner/by-session/:id", async (c) => {
+        const tenantId = c.get("tenantId");
+        if (!deps.learnerRecall) {
+            return c.json({ error: "learner recall not wired" }, 404);
+        }
+        const id = c.req.param("id");
+        const session = await deps.store.getById(tenantId, id);
+        if (!session) {
+            return c.json({ error: `session ${id} not found` }, 404);
+        }
+        const concepts = await pickRelatedConcepts(tenantId, [{ id }], deps.learnerRecall);
+        const wsMap = await deps.learnerRecall.sessions.getWorkstreamIds(tenantId, [id]);
+        const wsId = wsMap.get(id);
+        const enrollments = wsId
+            ? await deps.learnerRecall.learners.listEnrollmentsByWorkstreams(tenantId, [wsId])
+            : [];
+        return c.json({
+            enrollments: enrollments.map((e) => ({ learnerId: e.learnerId, courseId: e.courseId, status: e.status })),
+            concepts,
+        });
+    });
     // Post-hoc supersedence write path. Mirrors the `mark_superseded` MCP tool
     // so UI + CLI + MCP all share one backend gesture. Path param is the
     // predecessor (the session being retired); body names the successor.
     app.post("/api/session/:id/supersede", async (c) => {
         const predecessorId = c.req.param("id");
+        const tenantId = c.get("tenantId");
         let body;
         try {
             body = await c.req.json();
@@ -1299,7 +1505,7 @@ function registerSessionRoute(app, deps) {
             return c.json({ error: "reason must be a string if provided" }, 400);
         }
         try {
-            await deps.store.markSuperseded(predecessorId, successorId);
+            await deps.store.markSuperseded(tenantId, predecessorId, successorId);
         }
         catch (e) {
             const msg = e instanceof Error ? e.message : String(e);
@@ -1308,7 +1514,7 @@ function registerSessionRoute(app, deps) {
                 : 500;
             return c.json({ error: msg }, status);
         }
-        void appendSupersedence({
+        void appendSupersedence(tenantId, {
             predecessorId,
             successorId,
             source: c.req.header("x-supersedence-source") ?? "http",
@@ -1343,7 +1549,8 @@ function parseActionInput(raw) {
     };
 }
 const VALID_SOURCE_KINDS = [
-    "claude-code", "codex", "hermes", "pi", "jsonl-generic", "webhook",
+    "claude-code", "codex", "hermes", "hermes-agent", "muse", "aider", "cursor",
+    "windsurf", "opencode", "pi", "jsonl-generic", "webhook",
 ];
 function parseSourceInsert(raw) {
     if (!raw || typeof raw !== "object")
@@ -1479,12 +1686,13 @@ function registerSignalRoutes(app, deps) {
             return c.json({ error: e instanceof Error ? e.message : "invalid signal" }, 400);
         }
         const rawBody = body;
-        signal = await stampSignalScope(signal, {
+        const tenantId = c.get("tenantId");
+        signal = await stampSignalScope(signal, tenantId, {
             repoPath: typeof rawBody["repo_path"] === "string" ? rawBody["repo_path"] : null,
             sessionScopeReader: deps.sessionScopeReader,
         });
         try {
-            await deps.signalStore.insert(signal);
+            await deps.signalStore.insert(tenantId, signal);
         }
         catch {
             return c.json({ error: "signal insert failed" }, 500);
@@ -1500,11 +1708,11 @@ function registerSignalRoutes(app, deps) {
             try {
                 const exemplar = extractExemplar(signal, { installScope: deps.installScope });
                 if (exemplar) {
-                    const { id, skipped } = await exemplarStore.insert(exemplar);
+                    const { id, skipped } = await exemplarStore.insert(tenantId, exemplar);
                     if (!skipped && deps.codeEmbedder) {
                         void deps.codeEmbedder
                             .embed(composeEmbedText(exemplar.taskContext, exemplar.code), "document")
-                            .then((r) => exemplarStore.upsertEmbedding(id, r.vector))
+                            .then((r) => exemplarStore.upsertEmbedding(tenantId, id, r.vector))
                             .catch(() => { });
                     }
                 }
@@ -1521,7 +1729,8 @@ function registerSignalRoutes(app, deps) {
         if (!repo)
             return c.json({ error: "repo is required" }, 400);
         const model = c.req.query("model");
-        const block = await buildFailureModeBlock(deps.signalStore, { installScope: deps.installScope, repo, ...(model ? { model } : {}) });
+        const tenantId = c.get("tenantId");
+        const block = await buildFailureModeBlock(tenantId, deps.signalStore, { installScope: deps.installScope, repo, ...(model ? { model } : {}) });
         return c.json({ repo, model: model ?? null, block });
     });
     app.get("/api/signals/stats", async (c) => {
@@ -1534,7 +1743,8 @@ function registerSignalRoutes(app, deps) {
             return c.json({ error: "days must be 1..365" }, 400);
         }
         const sinceTs = new Date(Date.now() - days * 86_400_000).toISOString();
-        const rows = await deps.signalStore.listForAggregation({ installScope: deps.installScope, sinceTs });
+        const tenantId = c.get("tenantId");
+        const rows = await deps.signalStore.listForAggregation(tenantId, { installScope: deps.installScope, sinceTs });
         const modes = aggregateFailureModes(rows);
         return c.json({ days, total: rows.length, modes });
     });
@@ -1564,11 +1774,12 @@ function registerSignalRoutes(app, deps) {
             return c.json({ error: e instanceof Error ? e.message : "invalid exemplar" }, 400);
         }
         inp = { ...inp, scope: scopeStampEnabled() ? inp.scope : null };
-        const { id, skipped } = await deps.exemplarStore.insert(inp);
+        const tenantId = c.get("tenantId");
+        const { id, skipped } = await deps.exemplarStore.insert(tenantId, inp);
         if (!skipped && deps.codeEmbedder) {
             // Best-effort embedding: fire-and-forget, never blocks the response.
             deps.codeEmbedder.embed(composeEmbedText(inp.taskContext, inp.code), "document")
-                .then((r) => deps.exemplarStore.upsertEmbedding(id, r.vector))
+                .then((r) => deps.exemplarStore.upsertEmbedding(tenantId, id, r.vector))
                 .catch(() => { });
         }
         return c.json({ id, skipped, status: "accepted" }, 202);
@@ -1596,7 +1807,8 @@ function registerSignalRoutes(app, deps) {
         if (patch.retired === undefined && patch.outcome === undefined) {
             return c.json({ error: "provide retire (boolean) and/or outcome" }, 400);
         }
-        const result = await deps.exemplarStore.setVerdict(c.req.param("id"), patch, "human");
+        const tenantId = c.get("tenantId");
+        const result = await deps.exemplarStore.setVerdict(tenantId, c.req.param("id"), patch, "human");
         if (result.status === "not_found")
             return c.json({ error: "exemplar not found" }, 404);
         return c.json({ id: c.req.param("id"), status: result.status }, 200);
@@ -1617,7 +1829,8 @@ function registerSignalRoutes(app, deps) {
         const lang = c.req.query("lang");
         const model = c.req.query("model");
         const includeNegatives = c.req.query("negatives") !== "0";
-        const result = await recallCode({
+        const tenantId = c.get("tenantId");
+        const result = await recallCode(tenantId, {
             query,
             installScope: deps.installScope,
             ...(repo ? { repo } : {}),
@@ -1629,6 +1842,52 @@ function registerSignalRoutes(app, deps) {
         return c.json(result);
     });
 }
+// ── Reprocess job supervision (single operator process, LOCAL disposition) ──
+// Thin HTTP wrapping over JobSupervisor (core/jobs/job-supervisor.ts).
+// start() is synchronous and throws BY DESIGN both when a run is already
+// active and when the injected spawnChild adapter itself fails to launch
+// the child — this route is the required catch point so neither case ever
+// crashes the daemon (binding note from Task 1's review).
+function registerJobRoutes(app, deps) {
+    app.post("/api/jobs/reprocess", async (c) => {
+        if (!deps.jobSupervisor)
+            return c.json({ error: "job supervisor not wired in this deployment" }, 503);
+        let body = null;
+        try {
+            const text = await c.req.text();
+            body = text ? JSON.parse(text) : null;
+        }
+        catch {
+            return c.json({ error: "body must be JSON" }, 400);
+        }
+        const rawArgs = body?.args;
+        if (rawArgs !== undefined && (!Array.isArray(rawArgs) || !rawArgs.every((a) => typeof a === "string"))) {
+            return c.json({ error: "args must be an array of strings" }, 400);
+        }
+        // Passed straight through as argv entries by the real spawnChild
+        // adapter (never through a shell) — no interpolation risk here either
+        // way, but validating shape (not content) keeps this a passthrough,
+        // exactly as the reprocess CLI itself validates its own flags.
+        const args = rawArgs ?? [];
+        try {
+            deps.jobSupervisor.start(args);
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            if (message === "reprocess job already active") {
+                return c.json({ error: message, snapshot: deps.jobSupervisor.snapshot() }, 409);
+            }
+            return c.json({ error: message }, 500);
+        }
+        return c.json({ ok: true, snapshot: deps.jobSupervisor.snapshot() }, 202);
+    });
+    app.delete("/api/jobs/reprocess", (c) => {
+        if (!deps.jobSupervisor)
+            return c.json({ error: "job supervisor not wired in this deployment" }, 503);
+        deps.jobSupervisor.stop();
+        return c.json({ ok: true, snapshot: deps.jobSupervisor.snapshot() }, 200);
+    });
+}
 function mountSpa(app, dist) {
     const indexHtml = join(dist, "index.html");
     if (!existsSync(indexHtml))