Turn services + agent DI: chat-handler becomes the composition root (stage 4)

The chat turn is now composed, not implemented, by chat-handler.ts:

- src/server/turn-service.ts: one named, error-contained seam per turn
  responsibility — buildTeacherContext (W8 read channel), persistTurn
  (canonical state write), spawnTurnJobs (async protocol kick-off),
  foldTurnIntoGraph (session→graph consolidation; the extraction-pipeline
  stage swaps this body behind the same seam). Each takes its deps
  explicitly; failures log one [chat <id>] line and never touch the
  response.
- chat-handler.ts wires: storage ports (stores), the job runner, the
  teacher tools (ctx = chatId + injected ChatStore), and the services.
  It no longer contains any logic beyond request validation.

Agent layer now receives dependencies instead of importing them — a new
lint zone enforces it (src/agent never imports src/server or src/store;
verified to fire both ways):

- runner.ts: createJobRunner({ chatStore, jobStore }) factory returning
  the spawn hook + the three job runners; the model-override test seam
  stays module-level. Bodies otherwise verbatim.
- plan tools: persist through the ctx-injected ChatStore
  (TeacherToolContext = { chatId, chatStore }).
- teacher-agent's dependency-free default registry is now the true
  client-side set: questionTools + jobTools (jobTools was ctx-parameter-
  shaped but never used its ctx — now honestly context-free). Production
  always passes createTeacherTools({ chatId, chatStore }); tests that
  drive a bare mock model get the client-side set unchanged.

Zero behavior change: tsc clean, 190/190 tests, eslint clean, production
build clean. Tests inject the same fs ports the chat-handler does.

src/server/chat-handler.ts

@@ -1,10 +1,9 @@
 import { createAgentUIStreamResponse, type UIMessage } from "ai";
 import { createTeacherAgent, type TeacherAgent } from "../agent/teacher-agent.ts";
+import { createJobRunner } from "../agent/subagents/runner.ts";
 import { createTeacherTools } from "../agent/tools.ts";
-import { spawnPendingJobs } from "../agent/subagents/runner.ts";
-import { emitChat, getGraph } from "../core/graph.ts";
-import { buildGraphContext } from "../core/graph-context.ts";
 import { stores } from "./stores.ts";
+import { buildTeacherContext, foldTurnIntoGraph, persistTurn, spawnTurnJobs } from "./turn-service.ts";
 
 /**
  * One chat turn: run the teacher agent over the client's message list and
@@ -12,9 +11,14 @@ import { stores } from "./stores.ts";
  * so tests can drive it directly with a scripted mock model — the Next route
  * handler in app/api/chat is a one-line wrapper.
  *
- * The client owns the message list between turns (useChat); the server
- * persists the canonical state (client messages + agent response) onFinish.
+ * This module is the TURN COMPOSITION ROOT: it wires the storage ports, the
+ * job runner, the teacher tools, and the turn services (turn-service.ts)
+ * together — all actual work lives behind those seams. The background job
+ * runner closes over the same port objects the services see.
  */
+
+const jobRunner = createJobRunner(stores);
+
 export async function handleChatRequest(req: Request, agent?: TeacherAgent): Promise<Response> {
 	let body: { chatId?: unknown; messages?: unknown };
 	try {
@@ -30,48 +34,19 @@ export async function handleChatRequest(req: Request, agent?: TeacherAgent): Pro
 		return Response.json({ error: "messages must be an array" }, { status: 400 });
 	}
 
-	// W8 (vision §1 "the graph as session context"): the learner's knowledge
-	// graph rides along as part of the teacher's instructions. Built per
-	// request — stateless, and self-updating as the graph grows mid-session
-	// (the emission hook below folds each turn). A read failure must never
-	// take the lesson down: the block is context, not a dependency.
-	let graphContext: string | null = null;
-	try {
-		graphContext = buildGraphContext(getGraph(stores.graphStore));
-	} catch (err) {
-		console.error(`[chat ${chatId}] graph context build failed:`, err);
-	}
-
 	return createAgentUIStreamResponse({
-		agent: agent ?? createTeacherAgent(undefined, createTeacherTools({ chatId }), graphContext),
+		agent:
+			agent ??
+			createTeacherAgent(
+				undefined,
+				createTeacherTools({ chatId, chatStore: stores.chatStore }),
+				buildTeacherContext(stores.graphStore, chatId),
+			),
 		uiMessages: body.messages as UIMessage[],
 		onFinish: ({ messages, isAborted }) => {
-			// Persist even when aborted: the partial transcript (including any
-			// pending question part) is what makes resume work.
-			try {
-				stores.chatStore.saveMessages(chatId, messages as UIMessage[]);
-			} catch (err) {
-				console.error(`[chat ${chatId}] persist failed:`, err, { isAborted });
-			}
-			// Async sub-agent protocol (contracts.ts): scan the last assistant
-			// message for pending job tool parts and fire the background runners —
-			// fire-and-forget, never awaited; the HTTP response is already gone.
-			try {
-				spawnPendingJobs(chatId, messages as UIMessage[]);
-			} catch (err) {
-				console.error(`[chat ${chatId}] job spawn failed:`, err);
-			}
-			// W4: fold this chat into the knowledge-graph ledgers (tree nodes /
-			// edges, quiz outcomes, taught events) — synchronous but tiny
-			// (append-only JSONL), and errors never touch the response.
-			// Skipped under tests: scripted chats are fixtures, not knowledge.
-			if (process.env.NODE_ENV !== "test") {
-				try {
-					emitChat(chatId, stores);
-				} catch (err) {
-					console.error(`[chat ${chatId}] graph emission failed:`, err);
-				}
-			}
+			persistTurn(stores.chatStore, chatId, messages as UIMessage[], isAborted);
+			spawnTurnJobs(jobRunner, chatId, messages as UIMessage[]);
+			foldTurnIntoGraph(stores, chatId);
 		},
 	});
 }