Three-phase session status: derived summaries for the picker

- core/phases.ts: Phase3 (probe/plan/teach) + pure derivations —
  phaseOfTree (point-in-time, from the stored plan tree: no nodes → probe,
  no occupied node → plan, occupied → teach) and phaseAt3 (monotonic
  transcript fold for the dividers: failed plan_init never marks a seam;
  phase only advances).
- contracts.ts: ChatSummary gains record-derived phase + pendingQuestion;
  ChatListItem adds liveness-merged busy.
- store/chats.ts listChats computes the record-derived fields (tree +
  pending question scan).
- api/chats route merges busy = turn running || running background job.

Lane crossing granted by master: contracts/store/api (schema arbitration).
Data-only inference: pre-plan planning reads as probe until the plan lands.

app/api/chats/route.ts

@@ -1,7 +1,16 @@
-import { createChat, listChats, titleFromPrompt } from "@/src/server";
+import { createChat, isTurnRunning, listChats, listJobs, titleFromPrompt } from "@/src/server";
+import type { ChatListItem } from "@/src/core";
 
+/** The session picker's list: record-derived summaries (phase, pending
+ *  question) + live liveness — a running turn OR a background job marks
+ *  the session busy (contracts.ts ChatListItem; the store can't see
+ *  liveness, the route is the merge point). */
 export async function GET() {
-	return Response.json({ chats: listChats() });
+	const chats: ChatListItem[] = listChats().map((c) => ({
+		...c,
+		busy: isTurnRunning(c.id) || listJobs(c.id).some((j) => j.status === "running"),
+	}));
+	return Response.json({ chats });
 }
 
 export async function POST(req: Request) {

src/core/contracts.ts

@@ -5,6 +5,7 @@
  */
 
 import type { UIMessage } from "ai";
+import type { Phase3 } from "./phases.ts";
 
 // ─── Plan tree (vision §2 "formal plan tree") ────────────────────────────────
 // A session-scoped dependency tree authored by the teacher via plan tools.
@@ -257,13 +258,35 @@ export interface ChatRecord {
 	tree?: PlanTree;
 }
 
-/** The list view's shape (messageCount instead of full messages). */
+/** The list view's shape (messageCount instead of full messages) + the
+ *  per-session status the picker renders. `phase` and `pendingQuestion`
+ *  derive from the stored record (tree + messages); the store computes
+ *  them in listChats. Liveness (`busy`) is NOT record-derived — the API
+ *  route merges it in (see ChatListItem).
+ *
+ *  Phase semantics (three phases, data-only): probe = no plan yet, plan =
+ *  tree exists but no node occupied, teach = a node is occupied
+ *  (core/phases.ts phaseOfTree).
+ */
 export interface ChatSummary {
 	id: string;
 	title: string;
 	createdAt: string;
 	updatedAt: string;
 	messageCount: number;
+	/** The session's current phase, derived from the stored plan tree. */
+	phase: Phase3;
+	/** An unanswered quiz/ask question is waiting for the learner. */
+	pendingQuestion: boolean;
+}
+
+/** The sidebar's session row: a summary + live liveness. The chats list
+ *  route attaches `busy` from the turn-liveness registry and the job store
+ *  (a running turn OR a background job = the session is working). The store
+ *  itself can't see liveness (import law: store never imports server),
+ *  hence the split at exactly the record/liveness seam. */
+export interface ChatListItem extends ChatSummary {
+	busy: boolean;
 }
 
 // ─── Async sub-agent jobs (vision §2.5; plan.md Wave 0 protocol) ────────────

src/core/phases.ts

@@ -45,3 +45,85 @@ export function phaseAt(messages: readonly PhaseMessage[], upToIndex?: number):
 	}
 	return "probe";
 }
+
+// ─── The three-phase view (probe / plan / teach) ──────────────────────────────
+//
+// The session picker's color strips, the header chip, and the transcript
+// dividers all speak THREE phases, derived data-only from the plan tree:
+//
+//   probe — no plan output yet (the tree is empty or absent);
+//   plan  — a tree exists but no node is occupied (plan_set_current not fired);
+//   teach — a node is occupied.
+//
+// The teacher's invisible PRE-plan planning (reasoning before plan_init
+// fires) reads as probe until the plan lands — an accepted limitation: no
+// observable signal marks "I'm now planning" (a teacher-side marker would be
+// an agent change; see phases.md discussion in the transcript divider work).
+
+/** The three phases of a session, as the picker / header / dividers see it. */
+export type Phase3 = "probe" | "plan" | "teach";
+
+/** The advance-only order of phases: a session never visibly regresses. */
+const PHASE3_RANK: Record<Phase3, number> = { probe: 0, plan: 1, teach: 2 };
+
+/** Structural slice of a plan tree — anything with nodes + a current node. */
+export interface PhaseTree {
+	nodes: ReadonlyArray<unknown>;
+	currentNodeId: string | null;
+}
+
+/**
+ * The phase of a tree, point-in-time: no nodes → probe, no current node →
+ * plan, an occupied node → teach. Used for the chats summary (the stored
+ * tree IS the session state there). Empty trees (emptyTree(), a failed
+ * plan_init) read as probe — a seam only counts once a plan exists.
+ */
+export function phaseOfTree(tree: PhaseTree | null | undefined): Phase3 {
+	if (!tree || tree.nodes.length === 0) return "probe";
+	return tree.currentNodeId === null ? "plan" : "teach";
+}
+
+/**
+ * Minimal structural slice of a UI message for the three-phase scan: parts
+ * with a state and (when a plan op completed) its output.
+ */
+export interface Phase3Message {
+	parts: ReadonlyArray<{ type: string; state?: string; output?: unknown }>;
+}
+
+/** A successful plan-op output as it appears on the part (`PlanToolResult`). */
+interface PlanOutput {
+	tree?: { nodes?: unknown };
+}
+
+/**
+ * The three-phase boundary semantics over the TRANSCRIPT (the same data the
+ * tree panel reads): scanning forward from 0 to `upToIndex` (default: the
+ * last message), the phase advances probe → plan at the first plan part
+ * with a NON-EMPTY tree available (a failed plan_init carries an empty tree
+ * and never marks the seam), and plan → teach at the first tree output with
+ * an occupied node. MONOTONIC by design: the phase only ever advances — a
+ * node removal mid-teaching (currentNodeId → null) is an edit, not a phase
+ * regression, so no "Plan" divider ever appears below teaching content.
+ *
+ * `phaseAt` (two-phase) stays as-is: the plan_init call is its seam and the
+ * question dock's reveal logic leans on it. The two views differ only in
+ * the window between plan_init and the first plan_set_current, where
+ * three-phase reads "plan".
+ */
+export function phaseAt3(messages: readonly Phase3Message[], upToIndex?: number): Phase3 {
+	let phase: Phase3 = "probe";
+	const last = Math.min(upToIndex ?? messages.length - 1, messages.length - 1);
+	for (let i = 0; i <= last; i++) {
+		const parts = messages[i]?.parts;
+		if (!parts) continue;
+		for (const part of parts) {
+			if (!part.type.startsWith("tool-plan_") || part.state !== "output-available") continue;
+			const tree = (part.output as PlanOutput | undefined)?.tree as PhaseTree | undefined;
+			if (!tree || !Array.isArray(tree.nodes)) continue;
+			const candidate = phaseOfTree(tree);
+			if (PHASE3_RANK[candidate] > PHASE3_RANK[phase]) phase = candidate;
+		}
+	}
+	return phase;
+}

src/store/chats.ts

@@ -13,6 +13,8 @@ import { PATHS } from "../../config.ts";
 import type { ChatStore } from "../core/ports.ts";
 import type { ChatRecord, ChatSummary, PlanTree } from "../core/contracts.ts";
 import type { UIMessage } from "ai";
+import { findPendingToolCall } from "../core/pending.ts";
+import { phaseOfTree } from "../core/phases.ts";
 
 function chatFile(id: string): string {
 	if (!/^[A-Za-z0-9_-]+$/.test(id)) throw new Error(`Invalid chat id: ${id}`);
@@ -49,7 +51,16 @@ function listChats(): ChatSummary[] {
 			.filter((f) => f.endsWith(".json"))
 			.map((f) => getChat(f.slice(0, -5)))
 			.filter((r): r is ChatRecord => r !== null)
-			.map(({ messages, ...summary }) => ({ ...summary, messageCount: messages.length }))
+			.map(({ messages, tree, ...summary }) => ({
+				...summary,
+				messageCount: messages.length,
+				// Record-derived status for the session picker: phase from the
+				// stored plan tree, pending question from the transcript's last
+			// unanswered quiz/ask part. Liveness (busy) is NOT record-derived —
+				// the API route merges it (contracts.ts ChatListItem).
+				phase: phaseOfTree(tree),
+				pendingQuestion: findPendingToolCall(messages) !== null,
+			}))
 			.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
 	} catch {
 		return [];

tests/phases.test.ts

@@ -8,7 +8,13 @@
  */
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
-import { phaseAt, type PhaseMessage } from "../src/core/phases.ts";
+import {
+	phaseAt,
+	phaseAt3,
+	phaseOfTree,
+	type Phase3Message,
+	type PhaseMessage,
+} from "../src/core/phases.ts";
 
 /** A minimal message: just typed parts, exactly the structural slice phaseAt reads. */
 function msg(...partTypes: string[]): PhaseMessage {
@@ -83,3 +89,108 @@ describe("phaseAt", () => {
 		assert.equal(phaseAt([]), "probe");
 	});
 });
+
+// ─── The three-phase view (picker strips, header chip, transcript dividers) ────
+
+/** A minimal tree: nodes as opaque ids is all phaseOfTree reads. */
+function tree(nodes: string[], currentNodeId: string | null): { nodes: unknown[]; currentNodeId: string | null } {
+	return { nodes: nodes.map((id) => ({ id })), currentNodeId };
+}
+
+/** A message whose parts are full plan-op tool parts with outputs. */
+function planMsg(
+	...ops: { tool: string; ok: boolean; tree: ReturnType<typeof tree> }[]
+): Phase3Message {
+	return {
+		parts: ops.map((op, i) => ({
+			type: `tool-plan_${op.tool}`,
+			state: "output-available",
+			toolCallId: `p${i}`,
+			output: { ok: op.ok, tree: op.tree },
+		})),
+	};
+}
+
+describe("phaseOfTree", () => {
+	it("no tree / empty tree → probe", () => {
+		assert.equal(phaseOfTree(undefined), "probe");
+		assert.equal(phaseOfTree(null), "probe");
+		assert.equal(phaseOfTree(tree([], null)), "probe", "emptyTree() (a failed init) reads probe");
+	});
+
+	it("tree with no current node → plan", () => {
+		assert.equal(phaseOfTree(tree(["a", "b"], null)), "plan");
+	});
+
+	it("occupied node → teach", () => {
+		assert.equal(phaseOfTree(tree(["a", "b"], "a")), "teach");
+	});
+});
+
+describe("phaseAt3", () => {
+	it("no plan parts anywhere → probe at every index", () => {
+		const messages: Phase3Message[] = [msg("text"), msg("tool-quiz"), msg("text")];
+		for (let i = 0; i < messages.length; i++) {
+			assert.equal(phaseAt3(messages, i), "probe", `index ${i}`);
+		}
+		assert.equal(phaseAt3([]), "probe");
+	});
+
+	it("the probe→plan seam: the first plan output with a non-empty tree", () => {
+		const messages: Phase3Message[] = [
+			msg("text"), // probe chatter
+			planMsg({ tool: "plan_init", ok: false, tree: tree([], null) }), // failed init: NOT a seam
+			msg("text"),
+			planMsg({ tool: "plan_init", ok: true, tree: tree(["a", "b"], null) }), // ← the seam
+			msg("text"),
+		];
+		assert.equal(phaseAt3(messages, 0), "probe");
+		assert.equal(phaseAt3(messages, 1), "probe", "a failed init carries an empty tree — no seam");
+		assert.equal(phaseAt3(messages, 2), "probe");
+		assert.equal(phaseAt3(messages, 3), "plan");
+		assert.equal(phaseAt3(messages, 4), "plan");
+		assert.equal(phaseAt3(messages), "plan", "default = current phase");
+	});
+
+	it("the plan→teach seam: the first tree output with an occupied node", () => {
+		const messages: Phase3Message[] = [
+			msg("text"),
+			planMsg({ tool: "plan_init", ok: true, tree: tree(["a", "b"], null) }),
+			msg("text"),
+			planMsg({ tool: "plan_set_current", ok: true, tree: tree(["a", "b"], "a") }), // ← the seam
+			msg("text"),
+		];
+		assert.equal(phaseAt3(messages, 2), "plan");
+		assert.equal(phaseAt3(messages, 3), "teach");
+		assert.equal(phaseAt3(messages, 4), "teach");
+	});
+
+	it("collapsed seams: init and set_current in one message → straight to teach", () => {
+		const messages: Phase3Message[] = [
+			msg("text"),
+			planMsg(
+				{ tool: "plan_init", ok: true, tree: tree(["a"], null) },
+				{ tool: "plan_set_current", ok: true, tree: tree(["a"], "a") },
+			),
+		];
+		assert.equal(phaseAt3(messages, 0), "probe");
+		assert.equal(phaseAt3(messages, 1), "teach");
+	});
+
+	it("monotonic: a mid-teach node removal (current → null) never regresses the phase", () => {
+		const messages: Phase3Message[] = [
+			planMsg({ tool: "plan_init", ok: true, tree: tree(["a", "b"], null) }),
+			planMsg({ tool: "plan_set_current", ok: true, tree: tree(["a", "b"], "a") }),
+			msg("text"),
+			planMsg({ tool: "plan_remove_node", ok: true, tree: tree(["b"], null) }), // edit, not a regression
+		];
+		assert.equal(phaseAt3(messages, 2), "teach");
+		assert.equal(phaseAt3(messages, 3), "teach", "phase only ever advances");
+	});
+
+	it("upToIndex past the end / negative → clamped, never throws", () => {
+		const messages: Phase3Message[] = [planMsg({ tool: "plan_init", ok: true, tree: tree(["a"], null) })];
+		assert.equal(phaseAt3(messages, 99), "plan");
+		assert.equal(phaseAt3(messages, -1), "probe", "empty scan range → probe");
+	});
+});