feat: custom message types for system turns — wake and verdict messages

The custom-message scheme (user-decided 2026-09-12): system-authored
user-role messages are NOT human messages — they carry marker data parts
only, the adapter owns their model-facing wording, and the UI renders
them under control. Nothing fake is ever persisted as human speech.

The inventory (all migrated):
- probe→teacher handoff wake: was a text-bearing user message rendering
  as a fake user bubble; now data-probe-handoff marker-only — the
  adapter flattens it to HANDOFF_TEXT (core/contracts/chat.ts), the UI
  renders a quiet 'Preparing your plan…' system line.
- plan accept/decline: was boilerplate text ('The plan is accepted…',
  'I'd like the plan revised…') masquerading as learner speech — the
  decline wasn't even marked; now data-verdict {accepted, at} on its own
  message, adapter flattens to verdictText(), UI renders the quiet
  verdict marker ('✓ Plan accepted' / '↻ Plan revision requested').
  sendVerdict sends TWO REAL MESSAGES when the learner typed a note
  (the note as a genuine user message, then the verdict) in ONE turn
  via setMessages + sendMessage() — no 409 dance, no double teacher turn.
- sub-agent steers: the abort steer gains its data-subagent-aborted
  marker part; the UI keys steer rendering off PARTS (artifact/aborted),
  not metadata — metadata stays as pump mechanics only.
- record-adapter: systemTextOf() flattens marker-only messages; steers
  keep their text (payload — briefs are content, not boilerplate).

phases.ts: plan→teach advances on data-verdict{accepted:true} only;
learner text alone can never sanction teaching (pinned). data-plan-
accepted retired, no back-compat (user-decided: wiped-data doctrine).

Pinned: record-adapter.test.ts (verdict/handoff flattening, note+verdict
order, steer payload kept, UI-only parts skipped), phases.test.ts
(verdict marker semantics, out-of-order, text-never-fakes), jobs.test.ts
(abort marker part), demos.test.tsx (badge renders off the part, not
metadata).

Live GLM smoke (disposable driver, deleted): probe→conclude→wake→plan→
decline-with-note (revised, still plan)→accept-with-note (teach) — ALL
CHECKS PASS, including marker-only handoff/verdict on the wire and zero
fake human speech in the transcript.

Gates: tsc, lint, build, 335/335.

src/core/contracts/chat.ts

@@ -123,16 +123,39 @@ export interface TurnUsage {
  * block renders current node + direct parents + direct children in its own
  * small container, the current node glowing — clearly a fragment, not the
  * whole plan. Clicking either opens the full plan in a popup. */
-/** The learner's plan-acceptance marker (docs/probe-teach-split.md §4): a
- *  data part riding the accept-click user message. It is THE plan→teach
- *  phase seam — phaseAt3 reads it from the transcript;
- *  convertToModelMessages drops data parts, so the teacher only sees the
- *  message's text; the marker is for derivation and the UI. */
-export interface PlanAcceptedData {
-	/** ISO timestamp of the accept click. */
+/** The learner's plan verdict (docs/probe-teach-split.md §4): a data part
+ *  riding its own user message — the ONLY thing on that message. It is THE
+ *  plan→teach phase seam (phaseAt3 reads accepted from the transcript), and
+ *  both verdicts are real transcript events: accept sanctions teaching,
+ *  decline asks for revision. The part is the message TYPE (the "custom
+ *  message" scheme, 2026-09-12): the message carries no human-authored text,
+ *  the model-facing wording is owned by the adapter (record-adapter.ts
+ *  flattens it to VERDICT_TEXT below), and the UI renders the verdict
+ *  marker — never a user bubble. A learner who also typed a note sends the
+ *  note as its own real user message first; the verdict message follows. */
+export interface PlanVerdictData {
+	/** true = accept (sanction to teach); false = decline (revise the plan). */
+	accepted: boolean;
+	/** ISO timestamp of the click. */
 	at: string;
 }
 
+/** The model-facing text of a verdict message — single-sourced here so the
+ *  adapter, the tests, and reality can't drift apart. */
+export function verdictText(accepted: boolean): string {
+	return accepted
+		? "The learner accepted the plan — begin teaching."
+		: "The learner would like the plan revised before teaching begins.";
+}
+
+/** The model-facing text of the probe→teach handoff wake (the custom-message
+ *  scheme): the wake message carries only the data-probe-handoff part, and
+ *  the adapter flattens it to THIS. Single-sourced so the prober's seam, the
+ *  tests, and reality can't drift apart. */
+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.";
+
 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

@@ -256,7 +256,10 @@ export interface SubagentSteerMessage extends UIMessage {
 export interface AbortSteerMessage extends UIMessage {
 	role: "user";
 	metadata: { subagentResult: SubagentResultMeta & { aborted: true } };
-	parts: [{ type: "text"; text: string }];
+	parts: [
+		{ type: "text"; text: string },
+		{ type: "data-subagent-aborted"; data: SubagentResultMeta & { aborted: true } },
+	];
 }
 
 /** Anything the wake pipeline may queue and deliver. */
@@ -324,13 +327,17 @@ export function buildSubagentSteer(
 export function buildAbortSteer(
 	job: Pick<JobRecord, "id" | "kind" | "toolCallId">,
 ): AbortSteerMessage {
+	const meta = { jobId: job.id, kind: job.kind, toolCallId: job.toolCallId, aborted: true } as const;
 	return {
 		id: `steer_${job.id}`,
 		role: "user",
-		metadata: {
-			subagentResult: { jobId: job.id, kind: job.kind, toolCallId: job.toolCallId, aborted: true },
-		},
-		parts: [{ type: "text", text: abortText(job.kind) }],
+		metadata: { subagentResult: meta },
+		parts: [
+			{ type: "text", text: abortText(job.kind) },
+			// The message-type marker (the custom-message scheme): the UI
+			// renders the abort badge off this part, not off metadata.
+			{ type: "data-subagent-aborted", data: meta },
+		],
 	};
 }
 
@@ -356,7 +363,12 @@ export interface ProbeHandoffSteerMessage extends UIMessage {
 	id: `steer_probe_${string}`;
 	role: "user";
 	metadata: { probeHandoff: { chatId: string } };
-	parts: [{ type: "text"; text: string }];
+	/** The custom-message scheme (2026-09-12): NO text part — the wake is
+	 *  scaffolding, not speech. The model-facing instruction is owned by the
+	 *  adapter (record-adapter.ts flattens this part to HANDOFF_TEXT in
+	 *  core/contracts/chat.ts); the UI renders the quiet system line off the
+	 *  part. Nothing human-looking is persisted, ever. */
+	parts: [{ type: "data-probe-handoff"; data: { chatId: string } }];
 }
 
 export function buildProbeHandoffSteer(chatId: string): ProbeHandoffSteerMessage {
@@ -364,12 +376,7 @@ export function buildProbeHandoffSteer(chatId: string): ProbeHandoffSteerMessage
 		id: `steer_probe_${chatId}`,
 		role: "user",
 		metadata: { probeHandoff: { chatId } },
-		parts: [
-			{
-				type: "text",
-				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.",
-			},
-		],
+		parts: [{ type: "data-probe-handoff", data: { chatId } }],
 	};
 }
 

src/core/phases.ts

@@ -6,9 +6,10 @@
  *   probe  — until the first message containing a `tool-probe_done` part
  *            (the prober concludes; the assessment rides the tool part)
  *   plan   — probe concluded, until the learner ACCEPTS the presented
- *            plan (a `data-plan-accepted` part on the accept button's
- *            user message — the explicit verdict gate; plan_init itself
- *            is only the PRESENTATION and moves no phase)
+ *            plan (a `data-verdict` part with accepted:true on the verdict
+ *            button's own user message — the explicit verdict gate;
+ *            plan_init itself is only the PRESENTATION and moves no
+ *            phase; a declined verdict stays in plan)
  *   teach  — teaching is sanctioned
  *
  * The former derived-occupancy seam (phase-of-tree via `currentNodeId`)
@@ -49,14 +50,18 @@ function advance(
 	if (!parts) return phase;
 	for (const part of parts) {
 		// STRICTLY SEQUENTIAL: probe → plan only via a concluded probe_done,
-		// plan → teach only via the learner's plan acceptance
-		// (data-plan-accepted). A marker out of order advances nothing — the
+		// plan → teach only via the learner's plan acceptance (data-verdict
+		// with accepted:true). A marker out of order advances nothing — the
 		// chain never skips. plan_init PRESENTS the map; only the verdict
-		// (the accept button's marker part) sanctions teaching.
+		// sanctions teaching (a decline stays in plan).
 		if (phase === "probe" && part.type === "tool-probe_done" && part.state === "output-available") {
 			phase = "plan";
 		}
-		if (phase === "plan" && part.type === "data-plan-accepted") {
+		if (
+			phase === "plan" &&
+			part.type === "data-verdict" &&
+			(part as { data?: { accepted?: unknown } }).data?.accepted === true
+		) {
 			phase = "teach";
 		}
 	}

src/core/ui-message.ts

@@ -1,12 +1,13 @@
 import type { UIMessage } from "ai";
 import type {
 	DemoToolInput,
-	PlanAcceptedData,
+	PlanVerdictData,
 	PlanBlockData,
 	ProbeDoneInput,
 	ProbeDoneResult,
 	ResearchToolInput,
 	SubagentArtifactData,
+	SubagentResultMeta,
 	VisualToolInput,
 } from "./contracts.ts";
 import type { AskToolInput, QuestionAnswerData, QuizToolInput } from "./question-core.ts";
@@ -38,9 +39,15 @@ export type TeacherUIDataParts = {
 	"subagent-artifact": SubagentArtifactData;
 	/** Plan blocks (wave 4): frozen plan snapshots rendered in the chat flow. */
 	"plan-block": PlanBlockData;
-	/** The plan-acceptance marker: the accept button's user message carries
-	 *  it — the plan→teach phase seam (docs/probe-teach-split.md §4). */
-	"plan-accepted": PlanAcceptedData;
+	/** The learner's plan verdict (accept/decline): its own user message,
+	 *  carrying ONLY this part — the plan→teach phase seam (docs/probe-
+	 *  teach-split.md §4, the custom-message scheme 2026-09-12). */
+	verdict: PlanVerdictData;
+	/** 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 abort steer's message-type marker (the abort badge renders off it). */
+	"subagent-aborted": SubagentResultMeta & { aborted: true };
 };
 
 export type TeacherUIMessage = UIMessage<unknown, TeacherUIDataParts, TeacherUITools>;

src/server/pi/record-adapter.ts

@@ -1,6 +1,7 @@
 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";
 
 /**
  * The record → pi-ai transcript adapter (docs/pi-engine-swap.md §4). The
@@ -8,9 +9,15 @@ import type { AssistantMessage, Message, ToolResultMessage } from "@earendil-wor
  * fresh agent from it (the stateless per-turn decision). This replaces the
  * SDK's convertToModelMessages with an owned, explicit mapping:
  *
- * - user text parts → UserMessage text content; data parts are dropped
- *   (the plan-accept seam rides its text twin — the client always sends
- *   "The plan is accepted — begin teaching." alongside the marker).
+ * - user text parts → UserMessage text content.
+ * - SYSTEM DATA PARTS (the custom-message scheme, 2026-09-12): the wake and
+ *   verdict messages carry ONLY a marker part — no human text exists to
+ *   drop, so the ADAPTER flattens them: data-verdict → verdictText(),
+ *   data-probe-handoff → HANDOFF_TEXT (core/contracts/chat.ts owns both —
+ *   single source, so the model-facing wording can't drift from the seam).
+ *   Other data parts (artifacts, plan blocks) are dropped as before: they
+ *   are UI history; the steer briefs ride their text twin (payload, not
+ *   boilerplate — those texts are content the sub-agent produced).
  * - assistant text/reasoning/tool parts → one AssistantMessage whose
  *   content blocks mirror the part order; tool parts become ToolCall
  *   blocks (output-error parts keep their rawInput).
@@ -46,6 +53,18 @@ 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) {
+		if (part.type === "data-verdict") {
+			return verdictText((part.data as { accepted?: unknown } | undefined)?.accepted === true);
+		}
+		if (part.type === "data-probe-handoff") return HANDOFF_TEXT;
+	}
+	return null;
+}
+
 export function recordToPiMessages(messages: UIMessage[]): Message[] {
 	const out: AgentMessage[] = [];
 
@@ -55,7 +74,15 @@ export function recordToPiMessages(messages: UIMessage[]): Message[] {
 				.filter((p) => p.type === "text")
 				.map((p) => textOf(p as { text?: string }))
 				.filter((t) => t.length > 0);
-			if (texts.length === 0) continue; // pure data-part marker, no text
+			// The custom-message scheme: a marker-only message (verdict,
+			// handoff) flattens to its canonical model-facing text — the
+			// 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);
+				if (flat === null) continue; // pure UI data part, no model face
+				texts.push(flat);
+			}
 			out.push({
 				role: "user",
 				content: texts.map((text) => ({ type: "text" as const, text })),