feat: draft settings persistence — shared model/thinking/context record for the new-session surfaces

Both new-session pages (the home graph view's topic dock and /chat/new)
held their model + thinking + knowledge-context choices in plain
useState(undefined) — every navigation reset them to config defaults.

Now both surfaces read/write ONE server-side record
(data/draft-settings.json via GET/PUT /api/settings/draft, the
render-settings pattern): whatever the learner last left the controls on
is what every later visit shows. useDraftSettings loads on mount with a
touch-guard (a slow GET never clobbers a fast choice), saves
optimistically. Session creation still carries the choice into the new
chat exactly as before; per-session settings are untouched.

The PUT validation is the exact per-chat contract — parseSettingsBody
extracted verbatim from app/api/chats/[id]/settings and shared by both
routes (unknown model/level → 400 with the supported list, never a
silent clamp). 400s on garbage, {} = the clear-overrides write.

Live-verified: Cmd+K+Enter model pick, Shift+Tab thinking cycle, context
slider — all held across home → session → home → /chat/new, and carried
into a created session's record.

src/server/index.ts

@@ -11,6 +11,8 @@ export * from "./commit-positions.ts";
 export * from "./jobs.ts";
 export * from "./stores.ts";
 export { readRenderSettings, writeRenderSettings } from "../store/render-settings.ts";
+export { readDraftSettings, writeDraftSettings } from "../store/draft-settings.ts";
+export * from "./settings-body.ts";
 export * from "./turn-liveness.ts";
 export * from "./observability.ts";
 export * from "./model-catalog.ts";

src/server/settings-body.ts

@@ -0,0 +1,65 @@
+/**
+ * The shared settings-PUT body parser — the one seam both settings routes
+ * use (per-chat: app/api/chats/[id]/settings; pre-session draft:
+ * app/api/settings/draft). Extracted verbatim from the per-chat route
+ * (draft-settings wave, 2026-09-18): identical parse, identical errors.
+ *
+ * Replace-whole semantics: the client sends the complete desired object;
+ * absent fields are absent overrides ({} clears everything). No merges, so
+ * a stale client can never resurrect a cleared override.
+ */
+
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { GRAPH_CONTEXT_TOKENS_MAX, type ChatSettings } from "../core";
+
+/** Parsed-or-rejected — `ok: false` carries the 400's error message. */
+export type SettingsBodyResult =
+	| { ok: true; settings: ChatSettings }
+	| { ok: false; error: string };
+
+export function parseSettingsBody(body: unknown): SettingsBodyResult {
+	if (!body || typeof body !== "object" || Array.isArray(body)) {
+		return { ok: false, error: "Invalid JSON body" };
+	}
+	const raw = body as {
+		model?: { provider?: unknown; id?: unknown };
+		thinkingLevel?: unknown;
+		graphContextTokens?: unknown;
+	};
+	const settings: ChatSettings = {};
+	if (raw.model !== undefined) {
+		if (
+			typeof raw.model !== "object" ||
+			raw.model === null ||
+			typeof raw.model.provider !== "string" ||
+			typeof raw.model.id !== "string"
+		) {
+			return { ok: false, error: "model must be {provider, id}" };
+		}
+		settings.model = { provider: raw.model.provider, id: raw.model.id };
+	}
+	if (raw.thinkingLevel !== undefined) {
+		if (typeof raw.thinkingLevel !== "string") {
+			return { ok: false, error: "thinkingLevel must be a string" };
+		}
+		settings.thinkingLevel = raw.thinkingLevel as ThinkingLevel;
+	}
+	// Graph context injection budget (vision-context-injection.md): integer
+	// tokens, 0 (off) to GRAPH_CONTEXT_TOKENS_MAX, no silent clamping — the
+	// slider is the only writer, and it only ever sends multiples of the step.
+	if (raw.graphContextTokens !== undefined) {
+		if (
+			typeof raw.graphContextTokens !== "number" ||
+			!Number.isInteger(raw.graphContextTokens) ||
+			raw.graphContextTokens < 0 ||
+			raw.graphContextTokens > GRAPH_CONTEXT_TOKENS_MAX
+		) {
+			return {
+				ok: false,
+				error: `graphContextTokens must be an integer between 0 and ${GRAPH_CONTEXT_TOKENS_MAX}`,
+			};
+		}
+		settings.graphContextTokens = raw.graphContextTokens;
+	}
+	return { ok: true, settings };
+}

src/store/draft-settings.ts

@@ -0,0 +1,45 @@
+/**
+ * Server-side persistence for the DRAFT (pre-session) settings — the
+ * model + thinking-level + knowledge-context choices made on the
+ * new-session surfaces (the home graph view's topic dock and /chat/new).
+ * One small JSON blob: data/draft-settings.json, read-modify-write.
+ *
+ * Both surfaces share ONE record (owner, draft-settings wave 2026-09-18):
+ * whatever the learner last left the controls on is what the next visit
+ * shows — navigating away and back must not reset the feel. Per-session
+ * settings live in the chat record (PUT /api/chats/:id/settings) and are
+ * untouched by this.
+ *
+ * This module only moves bytes: the file is written exclusively through the
+ * validated route (app/api/settings/draft — parseSettingsBody +
+ * validateChatSettings gate every write), so no sanitizer runs here. On
+ * read, anything unreadable/corrupt is null = first boot = config defaults.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { DRAFT_SETTINGS_FILE } from "../../config.ts";
+import type { ChatSettings } from "../core";
+
+/** The persisted draft settings, or null when never saved / unreadable. */
+export function readDraftSettings(): ChatSettings | null {
+	let raw: string;
+	try {
+		raw = fs.readFileSync(DRAFT_SETTINGS_FILE, "utf-8");
+	} catch {
+		return null; // never saved / unreadable → the surfaces use config defaults
+	}
+	try {
+		const parsed: unknown = JSON.parse(raw);
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+		return parsed as ChatSettings;
+	} catch {
+		return null; // corrupt → defaults, never crash the surfaces
+	}
+}
+
+/** Persist the validated settings verbatim. */
+export function writeDraftSettings(settings: ChatSettings): void {
+	fs.mkdirSync(path.dirname(DRAFT_SETTINGS_FILE), { recursive: true });
+	fs.writeFileSync(DRAFT_SETTINGS_FILE, JSON.stringify(settings, null, "\t"), "utf-8");
+}