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.

app/api/chats/[id]/steer/route.ts

@@ -0,0 +1,32 @@
+// POST /api/chats/[id]/steer — the composer's mid-turn steering rail
+// (owner arc 2026-10-03). The learner's message for a RUNNING turn rides
+// pi's steering queue: drained at the next response boundary INSIDE the
+// same run (agent.steer + steeringMode "all"), forwarded verbatim on the
+// live stream (the client upserts the card by the client-minted id), and
+// persisted by the turn's own settlement.
+//
+// This is steering, NOT follow-ups: the route never starts a turn and
+// never extends an ended one. No live turn → 409 and the client falls
+// back to a plain text send (the settle race). Stranding safety: the
+// registry copy survives a question termination or abort and rides the
+// chat's next run.
+import { ChatInputError, newUserSteer, parseUserSteerInput } from "@/src/core";
+import { getChat, steerLiveChat } from "@/src/server";
+
+export async function POST(request: Request, ctx: { params: Promise<{ id: string }> }): Promise<Response> {
+	const { id } = await ctx.params;
+	if (!getChat(id)) return Response.json({ error: "unknown chat" }, { status: 404 });
+	let input;
+	try {
+		const body = (await request.json()) as { input?: unknown };
+		input = parseUserSteerInput(body?.input);
+	} catch (err) {
+		if (err instanceof ChatInputError) return Response.json({ error: err.message }, { status: 400 });
+		throw err;
+	}
+	const message = newUserSteer(input.text, input.id);
+	if (!steerLiveChat(id, message)) {
+		return Response.json({ error: "no live turn to steer" }, { status: 409 });
+	}
+	return Response.json({ ok: true });
+}