Pi-style ack-and-steer sub-agent protocol: dispatch mid-turn, steer via server wake turn

The job tools (research/demo/visual) switch from client-side turn-breaking
calls to pi's model: execute resolves IMMEDIATELY with a fire-and-forget
ack, the teacher's turn continues, and the result arrives later as an
injected user-role steer message that wakes the teacher in a new
server-side turn.

- contracts.ts: THE ASYNC PROTOCOL rewritten (ack now, steer later); steer
  types (SubagentSteerMessage, metadata.subagentResult + data-subagent-
  artifact part), pure buildSubagentSteer/steerDelivered/isSubagentFailure
- tools/jobs.ts: jobTools(ctx) factory — server-side execute creates the
  job (deduped by toolCallId), fires spawn with the dispatch-time input
  (the part isn't persisted yet at execute — a transcript scan would race)
- runner.ts: runJob(jobId, input?) builds the steer and hands it to the
  injected deliver seam; pipeline owns the done/error flip (a polling
  client re-syncs once, at the end); failures still steer
- server/jobs.ts (new pipeline): per-chat serialized queues on globalThis,
  idle gates (turn liveness + pending question, 1.5s grace), 409 retry
  with backoff, idempotent per jobId, stale-job recovery sweep (re-deliver
  or re-spawn); wake turns run through the same handleChatRequest
  composition via setTurnRunner injection
- chat-handler.ts: wires runner+deliver+tools ctx; drops spawnTurnJobs
  from onFinish; teacher default registry = question tools only
- plan.ts: PlanToolContext split out (plan tools need no job wiring)
- visual-maker: edit_svg added (pi parity — exact-match single
  replacement, fuzzy context on a miss); researcher: pi's kept/dropped
  source accounting restored
- prompts 20-jobs/40-demos: async discipline rewritten (announce and keep
  teaching, no waiting/polling/fabricating, parallel dispatch, teach with
  the artifact when it arrives)
- tests: jobs.test.ts rewritten (dispatch ack mid-turn, runner steers,
  wake pipeline: deferral/409/idempotency/failure), demos.test.tsx runner
  tests ported to runJob + fake deliver; 222 green

FLAGGED surgical touches outside the stream's owned files, for master
review at merge: src/core/contracts.ts (protocol doc + steer types),
src/core/ui-message.ts (job tool + data-part types), src/server/
chat-handler.ts (wiring), src/server/turn-service.ts (spawnTurnJobs
retirement), src/agent/teacher-agent.ts (default tools), src/agent/tools/
plan.ts (context type split).

Verified live on PORT=3003 with real models: teacher dispatched research
mid-turn, researcher ran real searches/fetches, steer injected on quiz
answer, wake turn wove the brief in citing its sources, job flipped done;
a client/wake race correctly 409'd.

src/server/chat-handler.ts

@@ -3,9 +3,10 @@ import { createTeacherAgent, type TeacherAgent } from "../agent/teacher-agent.ts
 import { createJobRunner } from "../agent/subagents/runner.ts";
 import { createExtractionPipeline } from "../agent/subagents/extraction.ts";
 import { createTeacherTools } from "../agent/tools.ts";
+import { deliverJobResult, setJobRespawn, setTurnRunner } from "./jobs.ts";
 import { stores } from "./stores.ts";
 import { beginTurn, endTurn } from "./turn-liveness.ts";
-import { buildTeacherContext, persistTurn, spawnTurnJobs, triggerExtraction } from "./turn-service.ts";
+import { buildTeacherContext, persistTurn, triggerExtraction } from "./turn-service.ts";
 
 /**
  * One chat turn: run the teacher agent over the client's message list and
@@ -14,14 +15,38 @@ import { buildTeacherContext, persistTurn, spawnTurnJobs, triggerExtraction } fr
  * handler in app/api/chat is a one-line wrapper.
  *
  * 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.
+ * job runner + wake pipeline, the teacher tools, and the turn services
+ * (turn-service.ts) together — all actual work lives behind those seams.
+ * THE SAME COMPOSITION serves both entry points: client requests and the
+ * wake pipeline's server-side steers (src/server/jobs.ts) — one code path
+ * for write-ahead persistence, turn liveness, and the turn services.
  */
 
-const jobRunner = createJobRunner(stores);
+const jobRunner = createJobRunner({
+	chatStore: stores.chatStore,
+	jobStore: stores.jobStore,
+	deliver: deliverJobResult,
+});
 const extraction = createExtractionPipeline(stores);
 
+// Wake-pipeline wiring (contracts.ts "THE ASYNC PROTOCOL" §4): the pipeline
+// fires its server-side teacher turns through THIS composition root, and
+// crash recovery re-spawns orphaned sub-agent loops through THIS runner.
+setTurnRunner(async (chatId, messages) => {
+	const res = await handleChatRequest(
+		new Request("http://localhost/api/chat", {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({ chatId, messages }),
+		}),
+	);
+	// Drive the stream to completion server-side — nobody else will read it,
+	// and onFinish (persist, extraction, endTurn) only runs when it drains.
+	await res.arrayBuffer().catch(() => undefined);
+	return res.status;
+});
+setJobRespawn((jobId) => void jobRunner.runJob(jobId));
+
 export async function handleChatRequest(req: Request, agent?: TeacherAgent): Promise<Response> {
 	let body: { chatId?: unknown; messages?: unknown };
 	try {
@@ -64,7 +89,12 @@ export async function handleChatRequest(req: Request, agent?: TeacherAgent): Pro
 			agent ??
 			createTeacherAgent(
 				undefined,
-				createTeacherTools({ chatId, chatStore: stores.chatStore }),
+				createTeacherTools({
+					chatId,
+					chatStore: stores.chatStore,
+					jobStore: stores.jobStore,
+					spawn: (job, input) => void jobRunner.runJob(job.id, input),
+				}),
 				buildTeacherContext(stores.graphStore, chatId),
 			),
 		uiMessages: body.messages as UIMessage[],
@@ -81,7 +111,6 @@ export async function handleChatRequest(req: Request, agent?: TeacherAgent): Pro
 		},
 			onFinish: ({ messages, isAborted }) => {
 				persistTurn(stores.chatStore, chatId, messages as UIMessage[], isAborted);
-				spawnTurnJobs(jobRunner, chatId, messages as UIMessage[]);
 				triggerExtraction(stores, extraction, chatId);
 				// LAST: a poller that sees not-in-flight must read an already-persisted
 				// record — endTurn only after persistTurn has done its job.