composer steering: the general steering machinery (owner arc 2026-10-03)

STEERING, NOT FOLLOW-UPS — pi-agent-core's two rails, used deliberately:
agent.steer() injects at the next response boundary INSIDE the live run
(one logical turn, the model changes course); followUp() would only extend
an ended run — not built. The same rail job markers already ride
(steeringMode 'all', the 2026-09-26 doctrine).

- POST /api/chats/[id]/steer: 404/400 honest guards; no live turn → 409
  and the client silently falls back to a plain text send (the settle
  race); live → steerLiveChat hands the message to the live agent's
  steering queue AND parks it in the userSteers registry — the stranding
  safety net. A steer stranded behind a question termination or abort
  stays parked and rides the chat's NEXT run (handOffEligible), the same
  deliver-or-requeue lifecycle as job markers. Reconciliation at settle:
  delivered ids drop (reconcileUserSteers).
- Client: steer(text) queues + POSTs without flipping any turn state;
  the drain's verbatim message events upsert the real user card by the
  client-minted id (steer_<localid>) and the indicator fold drops the
  line. canSend no longer gates on turnInFlight — Enter mid-turn steers;
  Enter with an empty composer still stops; the square button stays Stop.
- The queued-steer indicator (owner spec): quiet one-liners above the
  composer shell — right-aligned to where its corner rounding starts,
  truncated with an ellipsis, fixed max width, ~half opacity, no
  background, no container. Tunable later.
- Verified from pi-agent-core source: steering drains per completed turn
  inside the loop; injected messages emit message_start/end verbatim;
  finishTurn {action:'end'} (our question stopper) exits BEFORE the
  steering poll — hence the registry.

tests/chat-flow.test.ts

@@ -45,6 +45,7 @@ import type { LhMessage } from "../src/core/native-messages.ts";
 // handler, driven directly. Env is the runner's (the same the static
 // store imports already resolved under).
 const dismissRoute = await import("../app/api/chats/[id]/dismiss/route.ts");
+const steerRoute = await import("../app/api/chats/[id]/steer/route.ts");
 import { PATHS } from "../config.ts";
 
 // The key-presence turn gate (provider-key interlude, 2026-09-25): scripted
@@ -1387,3 +1388,80 @@ describe("parallel rounds: the LAST resolution decides the wake (owner ruling 20
 		assert.match(prompt2, /dismissed/, "the dismissal rode the wake too");
 	});
 });
+
+// ─── composer steering (owner arc 2026-10-03): the route + the live rail ────
+
+describe("composer steering: POST /api/chats/[id]/steer", () => {
+	const steerPost = (chatId: string, body: unknown): Promise<Response> =>
+		steerRoute.POST(
+			new Request(`http://test/api/chats/${chatId}/steer`, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(body),
+			}),
+			{ params: Promise.resolve({ id: chatId }) },
+		);
+
+	it("honest rejections: 404 unknown chat, 400 bad input, 409 when no turn is live", async () => {
+		const chat = createConfiguredChat("Test: steer rejections");
+		createdChats.push(chat.id);
+		assert.equal((await steerPost("chat_nope", { input: { type: "steer", id: "steer_1", text: "hi" } })).status, 404);
+		assert.equal((await steerPost(chat.id, { input: { type: "steer", id: "", text: "hi" } })).status, 400);
+		assert.equal((await steerPost(chat.id, { input: { type: "text", text: "hi" } })).status, 400);
+		assert.equal((await steerPost(chat.id, { input: { type: "steer", id: "steer_1", text: "  " } })).status, 400);
+		assert.equal((await steerPost(chat.id, { input: { type: "steer", id: "steer_1", text: "hi" } })).status, 409);
+	});
+
+	it("200 + the live steering queue when a turn runs; the drain lands the card and the model sees it", async () => {
+		// A GATED engine (the scriptedTeacher seam): the first factory
+		// awaits our release, holding the turn open mid-generation so the
+		// steer POST lands while the run is genuinely live.
+		const calls: string[][] = [];
+		let release!: () => void;
+		const gate = new Promise<void>((res) => {
+			release = res;
+		});
+		const faux = createFauxCore({});
+		faux.setResponses([
+			async (context: { messages: unknown[] }) => {
+				calls.push(context.messages.map((m) => JSON.stringify((m as { content: unknown }).content)));
+				await gate;
+				return fauxAssistantMessage([fauxText("Teaching the solar system…")]);
+			},
+			(context: { messages: unknown[] }) => {
+				calls.push(context.messages.map((m) => JSON.stringify((m as { content: unknown }).content)));
+				return fauxAssistantMessage([fauxText("Steered — covering Venus too.")]);
+			},
+		]);
+		const engine = { model: faux.getModel(), streamFn: faux.streamSimple };
+
+		const chat = createConfiguredChat("Test: steer live");
+		createdChats.push(chat.id);
+
+		// The turn starts and holds at the first model call.
+		const turnRes = await handleChatRequest(post(chat.id, { type: "text", text: "teach me" }), agentFactory(engine as never));
+		await waitFor(() => calls.length === 1, 8000, "first model call started");
+
+		// The steer lands mid-turn: 200, handed to the live agent.
+		const res = await steerPost(chat.id, { input: { type: "steer", id: "steer_live1", text: "also cover Venus" } });
+		assert.equal(res.status, 200);
+		assert.equal((await res.json() as { ok: boolean }).ok, true);
+
+		release(); // the first response completes → the drain → the second call
+		const body = await drain(turnRes);
+		assert.match(body, /also cover Venus/, "the drained steer rode the live stream verbatim");
+
+		// ONE turn: the second model call's context contains the steer
+		// BETWEEN the user message and the continuing assistant text.
+		assert.equal(calls.length, 2, "still one run — the steer continued it, not a new turn");
+		assert.match(calls[1]!.join("\n"), /also cover Venus/, "the model saw the steer in its context");
+
+		// The record persists the user steer in its true position.
+		const saved = chatStore.getChat(chat.id)!;
+		const roles = saved.messages.map((m) => (m as { role?: string }).role);
+		assert.deepEqual(roles, ["user", "assistant", "user", "assistant"], "text → teaching → STEER → steered reply");
+		const steerMsg = saved.messages[2] as { id?: string; content?: unknown };
+		assert.equal(steerMsg.id, "steer_live1", "the client-minted id survived to the record");
+		assert.equal(steerMsg.content, "also cover Venus");
+	});
+});

tests/jobs.test.ts

@@ -51,11 +51,13 @@ import {
 	abortJob,
 	deliverJobResult,
 	noteSteerVisible,
+	reconcileUserSteers,
 	recoverStaleJobs,
 	registerLiveAgent,
 	setJobRespawn,
 	setTurnRunner,
 	settleSteers,
+	steerLiveChat,
 	unregisterLiveAgent,
 } from "../src/server/jobs.ts";
 import { registerJobAbort, unregisterJobAbort } from "../src/agent/subagents/aborts.ts";
@@ -1642,3 +1644,59 @@ describe("provider-key job refusal (key-presence interlude)", () => {
 		assert.equal(result.sources.length, 0, "the failure result matches the research convention");
 	});
 });
+
+// ─── composer steering (owner arc 2026-10-03): the user-steer registry ──────
+
+describe("composer steering: steerLiveChat + the deliver-or-requeue lifecycle", () => {
+	/** A minimal stand-in for pi's Agent — only steer() is touched. */
+	function fakeAgent(): { handed: unknown[]; agent: unknown } {
+		const handed: unknown[] = [];
+		return { handed, agent: { steer: (m: unknown) => handed.push(m) } };
+	}
+
+	it("no live turn → false, nothing parked (the client falls back to a plain send)", () => {
+		const chatId = chatStore.createChat("steer: idle").id;
+		const msg = { id: "steer_x1", role: "user", content: "hold on", timestamp: 1 };
+		assert.equal(steerLiveChat(chatId, msg as never), false);
+		const { handed, agent } = fakeAgent();
+		registerLiveAgent(chatId, agent as never); // a later run hands NOTHING
+		assert.equal(handed.length, 0, "nothing was parked by the refused steer");
+		unregisterLiveAgent(chatId);
+	});
+
+	it("live agent → steered AND parked (the stranding safety net)", () => {
+		const chatId = chatStore.createChat("steer: live").id;
+		const msg = { id: "steer_x2", role: "user", content: "also cover Venus", timestamp: 1 };
+		const { handed, agent } = fakeAgent();
+		registerLiveAgent(chatId, agent as never);
+		assert.equal(steerLiveChat(chatId, msg as never), true);
+		assert.equal(handed.length, 1, "handed to the live agent's steering queue");
+		// Re-registering the SAME agent never re-hands (double-handoff guard).
+		registerLiveAgent(chatId, agent as never);
+		assert.equal(handed.length, 1);
+		unregisterLiveAgent(chatId);
+	});
+
+	it("settlement reconciliation: delivered ids drop, stranded ones ride the NEXT run", () => {
+		const chatId = chatStore.createChat("steer: reconcile").id;
+		const delivered = { id: "steer_d1", role: "user", content: "delivered", timestamp: 1 };
+		const stranded = { id: "steer_s1", role: "user", content: "stranded behind a question", timestamp: 2 };
+		const { handed, agent } = fakeAgent();
+		registerLiveAgent(chatId, agent as never);
+		assert.equal(steerLiveChat(chatId, delivered as never), true);
+		assert.equal(steerLiveChat(chatId, stranded as never), true);
+
+		// Settlement: the run persisted ONLY the delivered one (the stranded
+		// copy died with the agent — question termination / abort).
+		unregisterLiveAgent(chatId);
+		reconcileUserSteers(chatId, [delivered] as never);
+
+		// The chat's next run (the answer turn) picks up the stranded steer.
+		const next = fakeAgent();
+		registerLiveAgent(chatId, next.agent as never);
+		assert.equal(next.handed.length, 1, "exactly the stranded steer rides the next run");
+		assert.deepEqual((next.handed[0] as { id: string }).id, "steer_s1");
+		unregisterLiveAgent(chatId);
+		reconcileUserSteers(chatId, [stranded, delivered] as never); // cleanup
+	});
+});

tests/render-composer.test.tsx

@@ -57,13 +57,19 @@ describe("Composer", () => {
 	});
 });
 
-// The Enter decision: stop a busy stream, otherwise send. (The plan-verdict
-// accept branch died 2026-09-26 with the verdict itself — the post-plan
-// reply is a natural text message.) Pure function so the static-render
-// harness can pin it (key events can't be simulated in renderToStaticMarkup).
+// The Enter decision (composer steering, 2026-10-03): while a turn runs,
+// typed text makes Enter a STEER; Enter with an empty composer stays the
+// stop shortcut. (The plan-verdict accept branch died 2026-09-26 with the
+// verdict itself — the post-plan reply is a natural text message.) Pure
+// function so the static-render harness can pin it (key events can't be
+// simulated in renderToStaticMarkup).
 describe("enterAction", () => {
-	it("busy stream: Enter stops", () => {
-		assert.equal(enterAction({ busy: true, canSend: true }), "stop");
+	it("busy stream with text: Enter steers (the queued send)", () => {
+		assert.equal(enterAction({ busy: true, canSend: true }), "send");
+	});
+
+	it("busy stream, empty composer: Enter stops", () => {
+		assert.equal(enterAction({ busy: true, canSend: false }), "stop");
 	});
 
 	it("idle: send when there is text, nothing when there is not", () => {

tests/render-queued-steers.test.tsx

@@ -0,0 +1,51 @@
+/**
+ * The queued-steer indicator's pins (composer steering, owner arc
+ * 2026-10-03): the quiet one-liners above the composer shell, and the
+ * visibleQueuedSteers fold that decides which queued steers still show.
+ */
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { renderToStaticMarkup } from "react-dom/server";
+import { QueuedSteersBody } from "../components/queued-steers.tsx";
+import { visibleQueuedSteers } from "../components/session-core.ts";
+
+describe("QueuedSteersBody (the quiet queue above the composer)", () => {
+	it("renders one truncated right-aligned line per queued steer — no background, no container chrome", () => {
+		const html = renderToStaticMarkup(
+			<QueuedSteersBody
+				steers={[
+					{ id: "steer_a", text: "also cover Venus while you are at it, please and thank you" },
+					{ id: "steer_b", text: "short one" },
+				]}
+			/>,
+		);
+		assert.match(html, /data-testid="queued-steers"/);
+		assert.equal(html.match(/<span/g)?.length, 2, "one span per steer");
+		assert.match(html, /truncate/, "single-line truncation with ellipsis");
+		assert.match(html, /items-end/, "right-aligned stack");
+		assert.match(html, /max-w-\[240px\]/, "fixed-width stash");
+		assert.match(html, /muted-foreground\/60/, "quiet, roughly half opacity");
+		assert.doesNotMatch(html, /bg-|border|rounded/, "no background, no container");
+		assert.match(html, /also cover Venus/, "the text rides the line");
+	});
+
+	it("empty queue renders nothing", () => {
+		assert.equal(renderToStaticMarkup(<QueuedSteersBody steers={[]} />), "");
+	});
+});
+
+describe("visibleQueuedSteers (the fold: a line dies when its card lands)", () => {
+	it("a queued steer stays visible until its id lands in the messages", () => {
+		const queue = [
+			{ id: "steer_a", text: "a" },
+			{ id: "steer_b", text: "b" },
+		];
+		const before = visibleQueuedSteers(queue, [{ id: "msg_1" } as never]);
+		assert.equal(before.length, 2, "nothing landed yet — both lines show");
+		const after = visibleQueuedSteers(queue, [
+			{ id: "msg_1" } as never,
+			{ id: "steer_a", role: "user", content: "a" } as never,
+		]);
+		assert.deepEqual(after.map((s) => s.id), ["steer_b"], "the drained steer's line dropped");
+	});
+});