feat: graph context injection — the session's prior knowledge, steered in at session start (vision-context-injection.md)

One shot per chat, fired at the first turn's onFinish: the session's
topic (its only typed message) is embedded as an EmbeddingGemma retrieval
query; the semantically closest graph propositions are selected under the
session's token budget (pure budget, no similarity threshold — the
decided doctrine) and delivered as a marker-only steer through the wake
pipeline, queuing behind pending questions like every sub-agent result.

- contracts: ChatSettings.graphContextTokens (default 1024, max 4096,
  step 128, 0 = off); GraphContextData + graphContextText; the
  graph-context JobKind + buildGraphContextSteer (id steer_ctx_<chatId>)
- core/graph-context.ts: brute-force cosine top-K, greedy chars/4 fill
  under budget, most-recent UnderstandingLevel fold, count cap 64,
  parse-don't-cast at the marker seam
- server: embedQuery (role-asymmetric query format, same warm singleton
  — vector-space parity by construction); the runner (startGraphContext-
  Injection one-shot gates; runGraphContextJob validates ledger parity);
  wake branches (chatIdOf/jobIdOf, finalizeJob done, recoverStaleJobs
  re-deliver or contextRespawn); abortJob kills context jobs SILENTLY
  (nothing was promised in the lesson); turn-service trigger seam
- adapter: data-graph-context flattens to the canonical block (malformed
  parts have no model face)
- UI: the budget slider (home dock + /chat/new draft, the session-data
  strip); the quiet SystemLine "~537 · 10 propositions"; dock kind
  "Knowledge context"; model-picker PUT now spreads settings (a model
  pick can no longer clear the sibling override)

Live-smoked end to end on the real embedder + real GLM: seeded ledger
(10 propositions), session on "modal logic: possible worlds and the
necessity box" — job in the dock, queued behind the prober's question,
delivered on the answer, SystemLine in the transcript, wake turn reads
the block and continues the probe. Gates: tsc, lint, 459/459, build.

src/agent/subagents/graph-context.ts

@@ -0,0 +1,186 @@
+/**
+ * Graph context injection — the background runner
+ * (docs/vision-context-injection.md, settled 2026-09-14).
+ *
+ * One shot per chat, at session start: the first learner message is the
+ * session's TOPIC; it is embedded as a retrieval QUERY (the embedder's
+ * model-card format), the semantically closest graph propositions are
+ * selected under the session's token budget (pure core: selectGraphContext),
+ * and delivered as a marker-only STEER through the wake pipeline — the same
+ * gates as sub-agent results: it queues behind a pending quiz and rides the
+ * turn after the learner's answer. The prober typically opens with a run of
+ * quiz/ask calls, so delivery lands mid-probing, before plan_init — where
+ * prior knowledge matters most.
+ *
+ * No model call, no usage: the job's only cost is one embedding pass over
+ * the warm singleton (tens–~200ms) plus a brute-force cosine scan. It still
+ * carries a JobRecord (kind "graph-context") so the dock shows it, and it
+ * registers its AbortController so the dock's END kills it — but an abort
+ * steers NOTHING: nothing was ever promised in the lesson (the injection is
+ * server-initiated scaffolding, unlike a teacher-dispatched sub-agent).
+ *
+ * The topic gate is structural: injection fires only while the session has
+ * EXACTLY ONE text-bearing user message — the topic. Old in-flight sessions
+ * (several typed messages) never inject (no retroactive injection), and a
+ * session whose first turn happened with injection off stays off even if
+ * the budget is raised later (set per-session, before the session starts).
+ */
+
+import {
+	buildGraphContextSteer,
+	steerDelivered,
+	type JobRecord,
+	type SteerMessage,
+} from "../../core/contracts.ts";
+import {
+	GRAPH_CONTEXT_TOKENS_DEFAULT,
+	type ChatSettings,
+} from "../../core/contracts/chat.ts";
+import { hasContext, selectGraphContext } from "../../core/graph-context.ts";
+import type { UIMessage } from "ai";
+import { registerJobAbort, unregisterJobAbort } from "./aborts.ts";
+import type { ChatStore, GraphStore, JobStore } from "../../core/ports.ts";
+
+/** The embedder as the runner needs it: the model/dim the ledger must
+ *  match (parity: one vector space) + the query seam. Injected so tests
+ *  run without the transformer model. */
+export interface GraphContextEmbedder {
+	model: string;
+	dim: number;
+	embedQuery: (text: string) => Promise<number[]>;
+}
+
+export interface GraphContextDeps {
+	chatStore: Pick<ChatStore, "getChat">;
+	jobStore: Pick<JobStore, "createJob" | "getJob" | "updateJob" | "findJobByToolCallId">;
+	graphStore: Pick<GraphStore, "readNodes" | "readEvents" | "readEmbeddings">;
+	embedder: GraphContextEmbedder;
+	/** The wake seam — jobs.ts deliverJobResult (resolves on delivery). */
+	deliver: (steer: SteerMessage) => Promise<void>;
+}
+
+/** The injection job's synthetic toolCallId — no tool part exists; the id
+ *  is deterministic per chat so findJobByToolCallId doubles as the one-shot
+ *  guard, mirroring the spawn-dedup the tool jobs get for free. */
+export function contextToolCallId(chatId: string): string {
+	return `ctx_${chatId}`;
+}
+
+/** The session's effective budget: settings override, else the default.
+ *  Absent ≠ 0 — the decided default is ON (1024 tokens). */
+export function effectiveContextBudget(settings: ChatSettings | undefined): number {
+	return settings?.graphContextTokens ?? GRAPH_CONTEXT_TOKENS_DEFAULT;
+}
+
+/** The session's topic: its ONLY text-bearing user message, if exactly one
+ *  exists. Steers (verdicts, handoffs, answers) carry no text part, so
+ *  quiz rounds during probing never break the gate. */
+export function topicOf(messages: UIMessage[]): string | null {
+	let topic: string | null = null;
+	let count = 0;
+	for (const m of messages) {
+		if (m.role !== "user") continue;
+		const text = m.parts
+			.filter((p) => p.type === "text")
+			.map((p) => (p as { text?: unknown }).text)
+			.filter((t): t is string => typeof t === "string" && t.trim().length > 0)
+			.join("\n");
+		if (text.length === 0) continue;
+		count++;
+		topic = text;
+	}
+	return count === 1 ? topic : null;
+}
+
+/**
+ * The one-shot trigger (fire-and-forget, called from turn-service at every
+ * turn's onFinish): starts the injection job if and only if the session is
+ * at its start (exactly one typed message — the topic), the budget is on,
+ * and nothing was injected before (delivered steer OR any prior context
+ * job — success or failure: one shot means one shot). Returns the created
+ * job for tests; null when nothing was started.
+ */
+export function startGraphContextInjection(deps: GraphContextDeps, chatId: string): JobRecord | null {
+	const { chatStore, jobStore } = deps;
+	const chat = chatStore.getChat(chatId);
+	if (!chat) return null;
+	if (effectiveContextBudget(chat.settings) <= 0) return null;
+	if (topicOf(chat.messages) === null) return null;
+	// One per chat, ever: a delivered steer OR a prior job (any status).
+	if (steerDelivered(chat.messages, `steer_ctx_${chatId}`)) return null;
+	if (jobStore.findJobByToolCallId(chatId, contextToolCallId(chatId))) return null;
+
+	const job = jobStore.createJob({
+		kind: "graph-context",
+		chatId,
+		toolCallId: contextToolCallId(chatId),
+		activity: "searching knowledge graph",
+	});
+	void runGraphContextJob(deps, job.id).catch((err: unknown) => {
+		console.error(`[chat ${chatId}] graph-context injection crashed:`, err);
+	});
+	return job;
+}
+
+/** Run one injection job to completion (background; never throws). Also the
+ *  crash-recovery respawn seam: a job record orphaned "running" by a
+ *  process crash re-runs from here (the record is the only input needed). */
+export async function runGraphContextJob(deps: GraphContextDeps, jobId: string): Promise<void> {
+	const { chatStore, jobStore, graphStore, embedder, deliver } = deps;
+	const job = jobStore.getJob(jobId);
+	if (!job || job.status !== "running") return;
+
+	const fail = (reason: string) => {
+		jobStore.updateJob(jobId, { status: "error", error: reason, activity: "failed" });
+	};
+	const chat = chatStore.getChat(job.chatId);
+	if (!chat) return fail(`chat not found: ${job.chatId}`);
+	const topic = topicOf(chat.messages);
+	if (topic === null) return fail("no injectable topic (session past its start)");
+	const budget = effectiveContextBudget(chat.settings);
+
+	// Real-kill wiring: the dock's END fires this controller; the runner
+	// checks it before every phase transition and unwinds silently.
+	const controller = new AbortController();
+	registerJobAbort(jobId, controller);
+	try {
+		jobStore.updateJob(jobId, { activity: "embedding topic" });
+		const ledger = graphStore.readEmbeddings();
+		if (ledger.model !== embedder.model || ledger.dim !== embedder.dim) {
+			return fail("embeddings ledger is stale (model/dim mismatch) — injection skipped");
+		}
+		if (Object.keys(ledger.vectors).length === 0) {
+			return fail("the knowledge graph has no embeddings yet — nothing to inject");
+		}
+		const query = await embedder.embedQuery(topic);
+		if (controller.signal.aborted) return;
+
+		jobStore.updateJob(jobId, { activity: "selecting propositions" });
+		const data = selectGraphContext({
+			chatId: job.chatId,
+			query,
+			vectors: ledger.vectors,
+			nodes: graphStore.readNodes(),
+			events: graphStore.readEvents(),
+			budget,
+		});
+		if (!hasContext(data)) return fail("nothing relevant fit the budget");
+		if (controller.signal.aborted) return;
+
+		// The result rides the record (crash recovery re-delivers it); the
+		// wake pipeline flips the job done when the lesson has resumed.
+		jobStore.updateJob(jobId, { result: data, activity: "delivering context" });
+		try {
+			await deliver(buildGraphContextSteer({ chatId: job.chatId, jobId }, data));
+		} catch (err) {
+			console.error(`[chat ${job.chatId}] graph-context steer delivery failed:`, err);
+			fail("context delivery failed");
+		}
+	} catch (err) {
+		if (controller.signal.aborted) return; // the abort path owns the record
+		console.error(`[chat ${job.chatId}] graph-context injection failed:`, err);
+		fail(err instanceof Error ? err.message : String(err));
+	} finally {
+		unregisterJobAbort(jobId);
+	}
+}

src/agent/subagents/runner.ts

@@ -89,11 +89,14 @@ interface LoopContext {
  * table mirrors MODELS in config.ts (research→researcher, demo→demoBuilder,
  * visual→visualMaker); the id is taken from config so a price-table sync
  * re-prices jobs for free. Model overrides (tests) still bill under the
- * configured model — usage is what is being captured, not which instance. */
+ * configured model — usage is what is being captured, not which instance.
+ * Context-injection jobs make NO model call ("" — onUsage never fires for
+ * them; the kind is deliberately absent from the runners below). */
 const KIND_MODEL: Record<JobKind, string> = {
 	research: MODELS.researcher.model,
 	demo: MODELS.demoBuilder.model,
 	visual: MODELS.visualMaker.model,
+	"graph-context": "",
 };
 
 export function createJobRunner(deps: JobRunnerDeps): JobRunner {
@@ -128,11 +131,15 @@ export function createJobRunner(deps: JobRunnerDeps): JobRunner {
 		return jobStore.getJob(jobId)?.status === "running";
 	}
 
-	/** The kind→runner map: one sub-agent loop per job kind. */
+	/** The kind→runner map: one sub-agent loop per SUB-AGENT kind.
+	 *  graph-context is deliberately absent: injection jobs are not
+	 *  sub-agent loops (no model, graph deps instead) — their spawn and
+	 *  crash-respawn seam is subagents/graph-context.ts, and runJob refuses
+	 *  them below rather than guessing wrong. */
 	// Each kind's runner narrows the union input itself (dispatch-time inputs
 	// are kind-correct by construction; transcript fallbacks are cast after).
 	const KIND_RUNNERS: Record<
-		JobKind,
+		Exclude<JobKind, "graph-context">,
 		(jobId: string, input: JobToolInput | undefined, loop: LoopContext) => Promise<void>
 	> = {
 		research: (jobId, input, loop) => runResearchJob(jobId, researchModelOverride.current, input, loop),
@@ -147,6 +154,12 @@ export function createJobRunner(deps: JobRunnerDeps): JobRunner {
 			return;
 		}
 		if (job.status !== "running") return; // already finished / re-run after crash recovery
+		if (job.kind === "graph-context") {
+			// Not a sub-agent: the injection's own respawn seam
+			// (setContextRespawn → runGraphContextJob) owns these records.
+			console.error(`[job ${jobId}] graph-context job reached the sub-agent runner — wrong seam`);
+			return;
+		}
 		const run = KIND_RUNNERS[job.kind];
 		if (!run) {
 			console.error(`[job ${jobId}] unknown kind: ${job.kind}`);

src/core/contracts/chat.ts

@@ -10,7 +10,7 @@ import type { UIMessage } from "ai";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Phase3 } from "../phases.ts";
 import type { PlanNodeStatus, PlanTree } from "./plan.ts";
-import type { EmissionStats } from "./graph.ts";
+import type { EmissionStats, UnderstandingLevel } from "./graph.ts";
 
 // ─── Chat records (the session store's on-disk format) ───────────────────────
 
@@ -58,8 +58,23 @@ export interface ChatSettings {
 	/** pi thinking level — must be in the chosen model's supported list
 	 *  (getSupportedThinkingLevels; enforced by the settings route). */
 	thinkingLevel?: ThinkingLevel;
+	/** Graph context injection (vision-context-injection.md): the session's
+	 *  token budget for the prior-knowledge block — the top semantically
+	 *  closest propositions from the knowledge graph, injected once, at
+	 *  session start, as a steer. Absent = the default (on); 0 = off. The
+	 *  settings route enforces the range; the trigger (turn-service →
+	 *  subagents/graph-context.ts) is one-shot, so a mid-session change
+	 *  affects only sessions that haven't injected yet. */
+	graphContextTokens?: number;
 }
 
+/** The injection budget's decided knobs (2026-09-14): default 1024 (a
+ *  meaningful, modest slice of prior knowledge), hard max 4096, slider
+ *  step 128, 0 = off. */
+export const GRAPH_CONTEXT_TOKENS_DEFAULT = 1024;
+export const GRAPH_CONTEXT_TOKENS_MAX = 4096;
+export const GRAPH_CONTEXT_TOKENS_STEP = 128;
+
 // ─── Background-extraction usage (the money channel, extraction side) ────────
 
 /** One pipeline stage's model usage — the stage's model + every step it
@@ -176,6 +191,54 @@ export const HANDOFF_TEXT =
 	"The probe is concluded — the learner assessment is recorded. " +
 	"Author the session's plan map now (call plan_init) and present it, then begin teaching.";
 
+// ─── Graph context injection (vision-context-injection.md, 2026-09-14) ────────
+
+/** One selected prior-knowledge proposition: similarity-ranked, annotated
+ *  with the learner's CURRENT understanding level — the fold is MOST
+ *  RECENT extraction instance (levels are per-instance, tied to moments in
+ *  time; the latest evidence is the best estimate of current understanding).
+ *  null = the node has no observation event at all. */
+export interface GraphContextProposition {
+	id: string;
+	statement: string;
+	level: UnderstandingLevel | null;
+}
+
+/** The data-graph-context part payload: what the UI renders (the counts)
+ *  AND the audit trail (the full block content — the transcript shows
+ *  exactly what was injected, and when). The model-facing text is derived
+ *  from this by graphContextText below — the adapter flattens the marker
+ *  part to it (the custom-message scheme: no authored human speech). */
+export interface GraphContextData {
+	chatId: string;
+	/** The session's budget at injection time (for the card's readout). */
+	budget: number;
+	/** Estimated tokens of the injected block — chars/4 heuristic. */
+	tokens: number;
+	/** The selected propositions, similarity-descending. */
+	propositions: GraphContextProposition[];
+}
+
+/** The model-facing block text — single-sourced (the adapter, the tests,
+ *  and reality can't drift). The level word travels with each line: the
+ *  closing gloss tells the agent what to do with each. */
+export function graphContextText(data: GraphContextData): string {
+	const n = data.propositions.length;
+	if (n === 0) return "";
+	const lines = data.propositions.map(
+		(p) => `- ${p.level ? `[${p.level}] ` : ""}${p.statement}`,
+	);
+	return [
+		`Prior-knowledge context — what this learner already knows (from their knowledge graph, ` +
+			`${n} proposition${n === 1 ? "" : "s"}, ~${data.tokens} tokens):`,
+		"",
+		...lines,
+		"",
+		"Treat this as reliable prior knowledge: build on what is solid, firm up what is shaky, " +
+			"and teach around anything resisted. Do not re-teach solid ground.",
+	].join("\n");
+}
+
 export interface PlanBlockData {
 	/** Only "full" survives (the 2026-09-11 pivot): the plan renders IN
 	 *  FLOW once, at authoring. The neighborhood fragments are retired —

src/core/contracts/jobs.ts

@@ -7,11 +7,11 @@
  * of "ai" (safe everywhere: server, client, tests). See docs/vision.md.
  */
 import type { UIMessage } from "ai";
-import type { CallUsage } from "./chat.ts";
+import type { CallUsage, GraphContextData } from "./chat.ts";
 
 // ─── Async sub-agent jobs (vision §2.5; plan.md Wave 0 protocol) ────────────
 
-export type JobKind = "research" | "demo" | "visual";
+export type JobKind = "research" | "demo" | "visual" | "graph-context";
 export type JobStatus = "running" | "done" | "error";
 
 export interface JobRecord {
@@ -263,7 +263,11 @@ export interface AbortSteerMessage extends UIMessage {
 }
 
 /** Anything the wake pipeline may queue and deliver. */
-export type SteerMessage = SubagentSteerMessage | AbortSteerMessage | ProbeHandoffSteerMessage;
+export type SteerMessage =
+	| SubagentSteerMessage
+	| AbortSteerMessage
+	| ProbeHandoffSteerMessage
+	| GraphContextSteerMessage;
 
 /** Whether a result is the failure shape (html/svg empty, failure brief). */
 export function isSubagentFailure(kind: JobKind, result: ResearchResult | DemoResult | VisualResult): boolean {
@@ -380,6 +384,34 @@ export function buildProbeHandoffSteer(chatId: string): ProbeHandoffSteerMessage
 	};
 }
 
+// ─── the graph-context steer (vision-context-injection.md) ───────────────────
+//
+// The injection's delivery: same wake pipeline, same gates — it queues
+// behind a pending quiz and rides the turn after the learner's answer, or
+// fires in the pump's idle window. Marker-only (the custom-message scheme):
+// no text part; the adapter flattens data-graph-context to graphContextText
+// (core/contracts/chat.ts owns the wording). One per chat, ever — the id is
+// deterministic per chat, so re-delivery is idempotent.
+
+export interface GraphContextSteerMessage extends UIMessage {
+	id: `steer_ctx_${string}`;
+	role: "user";
+	metadata: { graphContext: { chatId: string; jobId: string } };
+	parts: [{ type: "data-graph-context"; data: GraphContextData }];
+}
+
+export function buildGraphContextSteer(
+	meta: { chatId: string; jobId: string },
+	data: GraphContextData,
+): GraphContextSteerMessage {
+	return {
+		id: `steer_ctx_${meta.chatId}`,
+		role: "user",
+		metadata: { graphContext: meta },
+		parts: [{ type: "data-graph-context", data }],
+	};
+}
+
 /** True when the transcript already carries this steer — idempotent
  *  delivery for ANY steer kind: every steer id is deterministic per its
  *  event (steer_<jobId> for jobs, steer_probe_<chatId> for the handoff). */

src/core/graph-context.ts

@@ -0,0 +1,184 @@
+/**
+ * Graph context injection — the pure selection core
+ * (docs/vision-context-injection.md, settled 2026-09-14).
+ *
+ * The heavy lifting is deliberately tiny: embedding the topic is the only
+ * slow step (the embedder singleton), and SEARCH IS BRUTE-FORCE COSINE —
+ * ~1M multiply-adds at 2k propositions, exact top-K from the in-memory
+ * ledger, no ANN index until ~10⁶ scale (far away).
+ *
+ * Selection doctrine (owner-decided): the token budget is the ONLY control
+ * on amount — there is NO similarity threshold. Similarity decides ORDER
+ * (which propositions fill the budget first); irrelevant-but-cheap content
+ * rides along harmlessly. Levels fold MOST RECENT: UnderstandingLevel lives
+ * per extraction instance (tied to moments in time), and the latest evidence
+ * is the best estimate of current understanding — an optimistic fold risks
+ * stale claims, a pessimistic fold wastes covered ground.
+ */
+
+
+import {
+	GRAPH_CONTEXT_TOKENS_MAX,
+	type GraphContextData,
+	type GraphContextProposition,
+	graphContextText,
+} from "./contracts/chat.ts";
+import type { UnderstandingLevel } from "./contracts/graph.ts";
+import type { GraphNode, LedgerEvent } from "./contracts/graph.ts";
+
+/** Belt-and-braces count cap — the budget is the primary control; a huge
+ *  budget still can't pour hundreds of lines into the block. */
+export const GRAPH_CONTEXT_MAX_PROPOSITIONS = 64;
+
+/** The block's framing (header + gloss) in estimated tokens — reserved so
+ *  the composed block, not just the proposition lines, stays under budget. */
+const FRAMING_TOKENS = 55;
+
+const LEVELS: ReadonlySet<string> = new Set([
+	"solid",
+	"shaky",
+	"accepted",
+	"resisted",
+	"not yet engaged",
+]);
+
+export function isUnderstandingLevel(word: unknown): word is UnderstandingLevel {
+	return typeof word === "string" && LEVELS.has(word);
+}
+
+/**
+ * Fold each node's CURRENT understanding level: the level word of its most
+ * recent observation event (latest `at`; ledger order breaks ties — the
+ * same rule the snapshot's nodeObservations uses, but across ALL sessions,
+ * not per chat). Malformed notes (not on the scale) never count.
+ */
+export function currentUnderstanding(events: LedgerEvent[]): Map<string, UnderstandingLevel> {
+	const latest = new Map<string, { at: string; level: UnderstandingLevel; index: number }>();
+	events.forEach((event, index) => {
+		if (event.kind !== "observation" || event.nodeId === null) return;
+		if (!isUnderstandingLevel(event.note)) return;
+		const current = latest.get(event.nodeId);
+		if (!current || event.at > current.at || (event.at === current.at && index > current.index)) {
+			latest.set(event.nodeId, { at: event.at, level: event.note, index });
+		}
+	});
+	const levels = new Map<string, UnderstandingLevel>();
+	for (const [nodeId, { level }] of latest) levels.set(nodeId, level);
+	return levels;
+}
+
+/** Estimated tokens for one proposition line: chars/4 (the agreed
+ *  heuristic — no server-side tokenizer) + one for the level tag. */
+function lineTokens(p: GraphContextProposition): number {
+	return Math.ceil(p.statement.length / 4) + (p.level ? 1 : 0);
+}
+
+export interface SelectGraphContextInput {
+	chatId: string;
+	/** The topic's query embedding (same model + dim as the ledger — the
+	 *  caller asserts parity; dimension-mismatched vectors are skipped). */
+	query: number[];
+	/** The embeddings ledger's vectors: nodeId → truncated, L2-normalized
+	 *  (cosine = dot product). */
+	vectors: Record<string, number[]>;
+	/** Raw node lines (append order; first line per id defines — the
+	 *  ledger merge rule, mirrored from core/graph.ts). */
+	nodes: GraphNode[];
+	/** The event ledger — for the most-recent level fold. */
+	events: LedgerEvent[];
+	/** The session's token budget (estimated tokens, chars/4). */
+	budget: number;
+}
+
+/**
+ * Select the prior-knowledge block: similarity-descending greedy fill under
+ * the token budget, capped by count, each line annotated with its folded
+ * current level. Pure — server composes it with the embedder; tests drive
+ * it with hand-made vectors.
+ */
+export function selectGraphContext(input: SelectGraphContextInput): GraphContextData {
+	const { chatId, query, vectors, nodes, events, budget } = input;
+	const levels = currentUnderstanding(events);
+
+	// Score every embedded node: dot product (vectors are normalized). A
+	// dimension mismatch (a stale ledger, a foreign query) never scores.
+	const scored: Array<{ id: string; statement: string; score: number }> = [];
+	const seen = new Set<string>();
+	for (const node of nodes) {
+		if (seen.has(node.id)) continue; // first line defines (merge rule)
+		seen.add(node.id);
+		const vec = vectors[node.id];
+		if (!vec || vec.length !== query.length) continue;
+		let dot = 0;
+		for (let i = 0; i < query.length; i++) dot += query[i]! * vec[i]!;
+		scored.push({ id: node.id, statement: node.statement, score: dot });
+	}
+	scored.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+
+	// Greedy fill: similarity order decides WHICH propositions enter; the
+	// budget decides WHEN to stop. No similarity threshold, by design.
+	const propositions: GraphContextProposition[] = [];
+	let used = FRAMING_TOKENS;
+	for (const { id, statement } of scored) {
+		if (propositions.length >= GRAPH_CONTEXT_MAX_PROPOSITIONS) break;
+		const p: GraphContextProposition = {
+			id,
+			statement,
+			level: levels.get(id) ?? null,
+		};
+		const cost = lineTokens(p);
+		if (used + cost > budget) continue; // too big for the budget — a later, smaller one may still fit
+		used += cost;
+		propositions.push(p);
+	}
+	return { chatId, budget, tokens: used, propositions };
+}
+
+/** True when the selection would inject anything (guards the runner: an
+ *  empty block is never delivered — no steer, the job errors instead). */
+export function hasContext(data: GraphContextData): boolean {
+	return data.propositions.length > 0 && graphContextText(data).length > 0;
+}
+
+// ─── The marker-part parser (parse-don't-cast — tool-parts doctrine) ──────────
+
+function parseProposition(raw: unknown): GraphContextProposition | null {
+	if (typeof raw !== "object" || raw === null) return null;
+	const { id, statement, level } = raw as Record<string, unknown>;
+	if (typeof id !== "string" || typeof statement !== "string") return null;
+	if (level !== null && level !== undefined && !isUnderstandingLevel(level)) return null;
+	return { id, statement, level: (level as UnderstandingLevel | null | undefined) ?? null };
+}
+
+function parseGraphContextData(raw: unknown): GraphContextData | null {
+	if (typeof raw !== "object" || raw === null) return null;
+	const { chatId, budget, tokens, propositions } = raw as Record<string, unknown>;
+	if (typeof chatId !== "string") return null;
+	if (typeof budget !== "number" || budget < 0 || budget > GRAPH_CONTEXT_TOKENS_MAX) return null;
+	if (typeof tokens !== "number" || tokens < 0) return null;
+	if (!Array.isArray(propositions)) return null;
+	const parsed: GraphContextProposition[] = [];
+	for (const item of propositions) {
+		const p = parseProposition(item);
+		if (!p) return null; // malformed content: the whole part is untrusted
+		parsed.push(p);
+	}
+	return { chatId, budget, tokens, propositions: parsed };
+}
+
+/**
+ * The data-graph-context part of a message, validated — or null when the
+ * part is absent or malformed. The seam the adapter and the chat view read
+ * the marker through (never a raw cast: the part's data crossed a
+ * serialization boundary).
+ */
+export function graphContextOfMessage(
+	message: { parts: ReadonlyArray<{ type: string; data?: unknown }> },
+): GraphContextData | null {
+	for (const part of message.parts) {
+		if (part.type === "data-graph-context") {
+			return parseGraphContextData((part as { data?: unknown }).data);
+		}
+	}
+	return null;
+}

src/core/index.ts

@@ -34,3 +34,4 @@ export * from "./ui-message.ts";
 export * from "./tool-parts.ts";
 export * from "./prices.ts";
 export * from "./fuzzy.ts";
+export * from "./graph-context.ts";

src/core/ui-message.ts

@@ -1,6 +1,7 @@
 import type { UIMessage } from "ai";
 import type {
 	DemoToolInput,
+	GraphContextData,
 	PlanVerdictData,
 	PlanBlockData,
 	ProbeDoneInput,
@@ -46,6 +47,10 @@ export type TeacherUIDataParts = {
 	/** The probe→teach handoff wake: the wake pipeline's steer message,
 	 *  carrying ONLY this part (the model-facing text lives in the adapter). */
 	"probe-handoff": { chatId: string };
+	/** The prior-knowledge injection's delivery (vision-context-injection.md):
+	 *  the marker-only steer — the counts for the UI, the full block content
+	 *  for the audit trail; the adapter flattens it to graphContextText. */
+	"graph-context": GraphContextData;
 	/** The abort steer's message-type marker (the abort badge renders off it). */
 	"subagent-aborted": SubagentResultMeta & { aborted: true };
 };

src/server/chat-handler.ts

@@ -4,14 +4,15 @@ import { createProberAgent, createTeacherAgent, type TeachingAgent } from "../ag
 import { piEngineFor } from "../agent/models.ts";
 import { createJobRunner } from "../agent/subagents/runner.ts";
 import { createExtractionPipeline } from "../agent/subagents/extraction.ts";
-import { embedNewNodes } from "./embeddings.ts";
+import { runGraphContextJob, type GraphContextDeps } from "../agent/subagents/graph-context.ts";
+import { EMBEDDING_DIM, EMBEDDING_MODEL, embedNewNodes, embedQuery } from "./embeddings.ts";
 import type { ModelRole } from "../../config.ts";
-import { claimSteers, deliverJobResult, setJobRespawn, setTurnRunner } from "./jobs.ts";
+import { claimSteers, deliverJobResult, setContextRespawn, setJobRespawn, setTurnRunner } from "./jobs.ts";
 import { recordToPiMessages } from "./pi/record-adapter.ts";
 import { createPiTurnResponse } from "./pi/ui-stream.ts";
 import { stores } from "./stores.ts";
 import { beginTurn, endTurn } from "./turn-liveness.ts";
-import { persistTurn, triggerExtraction, withMessageIds } from "./turn-service.ts";
+import { persistTurn, triggerExtraction, triggerGraphContext, withMessageIds } from "./turn-service.ts";
 import type { CallUsage } from "../core/contracts.ts";
 
 /**
@@ -48,6 +49,18 @@ export const extraction = createExtractionPipeline({
 	embedder: embedNewNodes,
 });
 
+/** Graph context injection (vision-context-injection.md): the runner's
+ *  deps — same storage ports, the REAL embedder as the query seam (same
+ *  warm singleton as extraction, so vector-space parity holds by
+ *  construction), and the wake pipeline as the delivery seam. */
+export const graphContext: GraphContextDeps = {
+	chatStore: stores.chatStore,
+	jobStore: stores.jobStore,
+	graphStore: stores.graphStore,
+	embedder: { model: EMBEDDING_MODEL, dim: EMBEDDING_DIM, embedQuery },
+	deliver: deliverJobResult,
+};
+
 // 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.
@@ -65,6 +78,7 @@ setTurnRunner(async (chatId, messages) => {
 	return res.status;
 });
 setJobRespawn((jobId) => void jobRunner.runJob(jobId));
+setContextRespawn((jobId) => void runGraphContextJob(graphContext, jobId));
 
 /** The message-shape gate the SDK's UIMessageValidator owned: a malformed
  *  body must fail BEFORE the stream exists — the path where no onFinish will
@@ -223,6 +237,9 @@ export async function handleChatRequest(
 					});
 				}
 				triggerExtraction(stores, extraction, chatId);
+				// The graph READ channel: one-shot prior-knowledge injection at
+				// session start — a no-op for every session past its start.
+				triggerGraphContext(graphContext, chatId);
 				// LAST: a poller that sees not-in-flight must read an already-persisted
 				// record — endTurn only after persistTurn has done its job.
 				endTurn(chatId);

src/server/embeddings.ts

@@ -42,6 +42,24 @@ function embedInput(statement: string): string {
 	return `title: none | text: ${statement}`;
 }
 
+/** EmbeddingGemma's retrieval-QUERY format (model card) — the topic side of
+ *  graph context injection (vision-context-injection.md). Role-asymmetric
+ *  BY DESIGN: queries and documents use different trained templates; the
+ *  requirement is same model + same truncation (one vector space), each
+ *  side in the format the model was trained for. */
+function queryInput(text: string): string {
+	return `task: search result | query: ${text}`;
+}
+
+/** Embed one retrieval query (the session's topic) — same warm singleton,
+ *  same 512-dim MRL truncation as the ledger. The one embedding call the
+ *  injection job makes; tens–~200ms warm. */
+export async function embedQuery(text: string): Promise<number[]> {
+	const extractor = await getPipeline();
+	const output = await extractor([queryInput(text)], { pooling: "mean", normalize: true });
+	return truncateNormalize((output.tolist() as number[][])[0]!);
+}
+
 /** Truncate an L2-normalized vector to EMBEDDING_DIM (MRL: leading dims
  *  carry most of the signal) and re-normalize so cosine = dot product. */
 function truncateNormalize(vec: readonly number[]): number[] {

src/server/jobs.ts

@@ -34,6 +34,7 @@
 import type { UIMessage } from "ai";
 import {
 	buildAbortSteer,
+	buildGraphContextSteer,
 	buildSubagentSteer,
 	isSubagentFailure,
 	steerDelivered,
@@ -60,6 +61,9 @@ interface QueuedSteer {
 interface WakeState {
 	turnRunner?: TurnRunner;
 	respawn?: JobRespawn;
+	/** Crash recovery for context-injection jobs (they are not sub-agent
+	 *  loops — their runner takes the graph deps; chat-handler wires it). */
+	contextRespawn?: (jobId: string) => void;
 	/** chatId → steers awaiting delivery, in arrival order. */
 	queues: Map<string, QueuedSteer[]>;
 	/** Chats whose pump loop is currently active (serialization per chat). */
@@ -87,6 +91,13 @@ export function setJobRespawn(respawn: JobRespawn): void {
 	state().respawn = respawn;
 }
 
+/** chat-handler wires this at module init: the graph-context runner
+ *  (subagents/graph-context.ts runGraphContextJob — re-runnable from the
+ *  job record alone, which is all crash recovery has). */
+export function setContextRespawn(respawn: (jobId: string) => void): void {
+	state().contextRespawn = respawn;
+}
+
 const POLL_MS = 400;
 /** After the gates open, wait a beat before firing — a client that just
  *  answered a question is about to send its continuation; don't 409 it.
@@ -110,11 +121,14 @@ function delay(ms: number): Promise<void> {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-/** The job a steer belongs to, if it is a job steer (result/abort);
+/** The job a steer belongs to, if it is a job steer (result/abort/context);
  *  probe-handoff steers have no job — null. */
 function jobIdOf(steer: SteerMessage): string | null {
-	const meta = steer.metadata as { subagentResult?: { jobId: string } };
-	return meta.subagentResult?.jobId ?? null;
+	const meta = steer.metadata as {
+		subagentResult?: { jobId: string };
+		graphContext?: { jobId: string };
+	};
+	return meta.subagentResult?.jobId ?? meta.graphContext?.jobId ?? null;
 }
 
 /** Finalize a delivered steer's job bookkeeping — job steers only. */
@@ -220,6 +234,12 @@ export function abortJob(jobId: string): AbortOutcome {
 	if (!job) return { ok: false, reason: "not_found" };
 	if (job.status !== "running") return { ok: false, reason: "not_running" };
 
+	// Context-injection jobs abort SILENTLY: nothing was ever promised in the
+	// lesson (server-initiated scaffolding, unlike a teacher-dispatched
+	// sub-agent), so no abort steer — flipping the record and killing the
+	// run is the whole story. Steps 1–3 below are shared; step 4 is skipped.
+	const isContext = job.kind === "graph-context";
+
 	fireJobAbort(jobId); // no-op when the loop already returned (delivering)
 
 	// Drop any queued steers for this job (their deliver() resolves unfired).
@@ -234,16 +254,22 @@ export function abortJob(jobId: string): AbortOutcome {
 	}
 
 	stores.jobStore.updateJob(jobId, { status: "error", error: "Aborted by learner", activity: "aborted" });
-	void deliverJobResult(buildAbortSteer(job)).catch(() => {
-			/* deliverJobResult marks the job error on unrecoverable failure */
-	});
+	if (!isContext) {
+		void deliverJobResult(buildAbortSteer(job)).catch(() => {
+				/* deliverJobResult marks the job error on unrecoverable failure */
+		});
+	}
 	return { ok: true };
 }
 
 function chatIdOf(steer: SteerMessage): string {
-	// The probe handoff carries its chat directly (no job record exists).
+	// The probe handoff and the context injection carry their chat directly
+	// (the context steer's job record would say it too, but the metadata is
+	// the cheap path — same rule as the handoff).
 	const handoff = (steer.metadata as { probeHandoff?: { chatId: string } }).probeHandoff;
 	if (handoff) return handoff.chatId;
+	const injected = (steer.metadata as { graphContext?: { chatId: string } }).graphContext;
+	if (injected) return injected.chatId;
 	// The chat is resolvable from the job record; the steer's metadata
 	// carries jobId, which indexes the store.
 	const jobId = jobIdOf(steer);
@@ -352,6 +378,12 @@ async function pump(chatId: string): Promise<void> {
 function finalizeJob(jobId: string): void {
 	const job = stores.jobStore.getJob(jobId);
 	if (!job || job.status !== "running") return;
+	// Context-injection jobs have no sub-agent result shape — a delivered
+	// block is a success, full stop (isSubagentFailure would misread it).
+	if (job.kind === "graph-context") {
+		stores.jobStore.updateJob(jobId, { status: "done", activity: "delivered" });
+		return;
+	}
 	const result = job.result;
 	const failed = result ? isSubagentFailure(job.kind, result as never) : true;
 	stores.jobStore.updateJob(jobId, {
@@ -418,6 +450,23 @@ function recoverStaleJobs(): void {
 				if (now - Date.parse(job.updatedAt) < STALE_JOB_MS) continue;
 				if (!stores.chatStore.getChat(job.chatId)) continue;
 				if (isTurnRunning(job.chatId)) continue; // a wake turn may be delivering it right now
+				if (job.kind === "graph-context") {
+					// Context-injection orphans: a stored block re-delivers in its own
+					// steer shape; a job that died before selecting re-runs from the
+					// record (the graph runner — not the sub-agent respawn seam).
+					if (job.result) {
+						stores.jobStore.updateJob(job.id, { activity: "recovering: re-delivering" });
+						void deliverJobResult(
+							buildGraphContextSteer({ chatId: job.chatId, jobId: job.id }, job.result as never),
+						).catch(() => {
+							/* deliverJobResult marks the job error on failure */
+						});
+					} else if (s.contextRespawn) {
+						stores.jobStore.updateJob(job.id, { activity: "recovering: re-running" });
+						s.contextRespawn(job.id);
+					}
+					continue;
+				}
 				if (job.result) {
 					// The wake never fired (or crashed mid-flight): re-deliver.
 					const steer = buildSubagentSteer(job, job.result as never);

src/server/pi/record-adapter.ts

@@ -1,7 +1,8 @@
 import type { UIMessage } from "ai";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { AssistantMessage, Message, ToolResultMessage } from "@earendil-works/pi-ai";
-import { HANDOFF_TEXT, verdictText } from "../../core/contracts/chat.ts";
+import { graphContextOfMessage } from "../../core/graph-context.ts";
+import { graphContextText, HANDOFF_TEXT, verdictText } from "../../core/contracts/chat.ts";
 
 /**
  * The record → pi-ai transcript adapter (docs/pi-engine-swap.md §4). The
@@ -55,12 +56,19 @@ function zeroUsage() {
 
 /** The model-facing text of a marker-only user message, or null when the
  *  message has no model face at all (UI-only data parts). */
-function systemTextOf(parts: ReadonlyArray<{ type: string; data?: unknown }>): string | null {
-	for (const part of parts) {
+function systemTextOf(message: { parts: ReadonlyArray<{ type: string; data?: unknown }> }): string | null {
+	for (const part of message.parts) {
 		if (part.type === "data-verdict") {
 			return verdictText((part.data as { accepted?: unknown } | undefined)?.accepted === true);
 		}
 		if (part.type === "data-probe-handoff") return HANDOFF_TEXT;
+		// Graph context injection: the block text derives from the part's
+		// validated data (parse-don't-cast — a malformed part has no model
+		// face, and the message then never reaches the provider).
+		if (part.type === "data-graph-context") {
+			const data = graphContextOfMessage({ parts: message.parts });
+			return data ? graphContextText(data) : null;
+		}
 	}
 	return null;
 }
@@ -79,7 +87,7 @@ export function recordToPiMessages(messages: UIMessage[]): Message[] {
 			// wording lives in the adapter's reach (core contracts), never
 			// authored as fake human speech in the transcript.
 			if (texts.length === 0) {
-				const flat = systemTextOf(message.parts);
+				const flat = systemTextOf(message);
 				if (flat === null) continue; // pure UI data part, no model face
 				texts.push(flat);
 			}

src/server/turn-service.ts

@@ -21,6 +21,7 @@ import { pendingQuizAnswers } from "../core/graph.ts";
 import type { ChatStore, GraphStore } from "../core/ports.ts";
 import { EXTRACTION } from "../../config.ts";
 import type { ExtractionPipeline } from "../agent/subagents/extraction.ts";
+import { startGraphContextInjection, type GraphContextDeps } from "../agent/subagents/graph-context.ts";
 
 /**
  * The canonical state write: the client owns the message list between turns
@@ -98,3 +99,22 @@ export function triggerExtraction(
 		console.error(`[chat ${chatId}] extraction trigger failed:`, err);
 	}
 }
+
+/**
+ * The graph READ channel (vision-context-injection.md): one shot per chat,
+ * at session start — the first typed message is the session's topic; the
+ * semantically closest propositions are selected under the session's token
+ * budget and steered in through the wake pipeline. Fire-and-forget like
+ * triggerExtraction; the one-shot gates (topic, budget, prior injection)
+ * live in the runner module, not here — this seam only decides WHEN to ask.
+ * Skipped under tests, same doctrine: the runner is tested directly with a
+ * scripted embedder.
+ */
+export function triggerGraphContext(deps: GraphContextDeps, chatId: string): void {
+	if (process.env.NODE_ENV === "test") return;
+	try {
+		startGraphContextInjection(deps, chatId);
+	} catch (err) {
+		console.error(`[chat ${chatId}] graph-context trigger failed:`, err);
+	}
+}