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/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
+	});
+});