feat: stop generation mid-turn (POST /conversations/:id/stop)

Add stopTurn to the orchestrator: aborts the in-flight turn's
AbortController without changing conversation status. The turn
seals normally (finishReason: 'aborted'), partial messages are
persisted, and the conversation transitions active → idle via the
normal settle path.

Distinct from closeConversation which marks the conversation closed.

- POST /conversations/:id/stop endpoint
- dispatch stop <id> CLI command
- FE handoff: frontend-stop-generation-handoff.md

9 files changed, 108 insertions, 0 deletions

diff --git a/packages/cli/src/args.ts b/packages/cli/src/args.ts
index ecf6e2e..ac5dd4a 100644
--- a/packages/cli/src/args.ts
+++ b/packages/cli/src/args.ts
@@ -47,6 +47,7 @@ export type ParsedCommand =
 			readonly cwd?: string;
 			readonly reasoningEffort?: ReasoningEffort;
 	  }
+	| { readonly kind: "stop"; readonly server: string; readonly conversationId: string }
 	| { readonly kind: "help" }
 	| { readonly kind: "error"; readonly message: string };
 
@@ -131,6 +132,28 @@ export function parseArgs(argv: readonly string[], opts: ParseOpts): ParsedComma
 		return { kind: "compact", server, conversationId };
 	}
 
+	if (first === "stop") {
+		let server = opts.defaultServer;
+		let conversationId: string | undefined;
+		for (let i = 1; i < argv.length; i++) {
+			const arg = argv[i] as string;
+			if (arg === "--server") {
+				if (i + 1 >= argv.length) return { kind: "error", message: "--server requires a value" };
+				server = argv[++i] as string;
+			} else if (arg.startsWith("--")) {
+				return { kind: "error", message: `Unknown flag: ${arg}` };
+			} else if (conversationId !== undefined) {
+				return { kind: "error", message: `Unexpected argument for 'stop': ${arg}` };
+			} else {
+				conversationId = arg;
+			}
+		}
+		if (conversationId === undefined) {
+			return { kind: "error", message: "'stop' requires a conversation id" };
+		}
+		return { kind: "stop", server, conversationId };
+	}
+
 	if (first === "read") {
 		let server = opts.defaultServer;
 		let conversationId: string | undefined;
diff --git a/packages/cli/src/http.ts b/packages/cli/src/http.ts
index 585c678..42fcfec 100644
--- a/packages/cli/src/http.ts
+++ b/packages/cli/src/http.ts
@@ -204,6 +204,26 @@ export async function compactConversation(
 	return (await res.json()) as CompactResponse;
 }
 
+interface StopTurnOpts {
+	readonly server: string;
+	readonly conversationId: string;
+}
+
+export async function stopTurn(
+	deps: FetchDeps,
+	opts: StopTurnOpts,
+): Promise<{ conversationId: string; abortedTurn: boolean }> {
+	const url = `${opts.server}/conversations/${encodeURIComponent(opts.conversationId)}/stop`;
+	const res = await deps.fetchImpl(url, { method: "POST" });
+
+	if (!res.ok) {
+		const body = await res.text();
+		throw new Error(`POST /conversations/:id/stop failed with status ${res.status}: ${body}`);
+	}
+
+	return (await res.json()) as { conversationId: string; abortedTurn: boolean };
+}
+
 /**
  * The outcome of short-ID resolution: either the full conversation id to use,
  * or a human-readable error describing why resolution failed.
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index 4e07da9..5935bab 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -16,6 +16,7 @@ import {
 	fetchModels,
 	openConversation,
 	resolveConversationId,
+	stopTurn,
 	streamChat,
 } from "./http.js";
 import { buildChatRequest, composeMessage } from "./message.js";
@@ -24,6 +25,7 @@ import { extractLastText, formatConversationList, renderEvent } from "./render.j
 const USAGE = `Usage:
   dispatch models [--server <url>]
   dispatch list [<prefix>] [--status <active|idle|closed>] [--all] [--server <url>]
+  dispatch stop <conversationId> [--server <url>]
   dispatch compact <conversationId> [--server <url>]
   dispatch read <conversationId> [--server <url>]
   dispatch open <conversationId> [--server <url>]
@@ -99,6 +101,26 @@ async function main(): Promise<void> {
 			);
 			break;
 		}
+		case "stop": {
+			const resolved = await resolveConversationId(
+				{ fetchImpl: globalThis.fetch },
+				{ server: parsed.server, shortId: parsed.conversationId },
+			);
+			if (typeof resolved !== "string") {
+				process.stderr.write(`${resolved.error}\n`);
+				process.exit(1);
+			}
+			const result = await stopTurn(
+				{ fetchImpl: globalThis.fetch },
+				{ server: parsed.server, conversationId: resolved },
+			);
+			process.stdout.write(
+				result.abortedTurn
+					? `Stopped generation for ${resolved}\n`
+					: `No active generation for ${resolved}\n`,
+			);
+			break;
+		}
 		case "open": {
 			const resolved = await resolveConversationId(
 				{ fetchImpl: globalThis.fetch },
diff --git a/packages/session-orchestrator/src/orchestrator.ts b/packages/session-orchestrator/src/orchestrator.ts
index b46ecc1..bc9e78b 100644
--- a/packages/session-orchestrator/src/orchestrator.ts
+++ b/packages/session-orchestrator/src/orchestrator.ts
@@ -218,6 +218,14 @@ export interface SessionOrchestrator {
 	 * Idempotent — closing an idle/unknown conversation just emits the hook.
 	 */
 	closeConversation(conversationId: string): { readonly abortedTurn: boolean };
+	/**
+	 * Stop an in-flight generation WITHOUT closing the conversation. Aborts
+	 * the turn's AbortController — the kernel finishes with
+	 * `finishReason: "aborted"`, partial messages are persisted, and the turn
+	 * seals normally (status transitions active → idle via the normal settle
+	 * path). Idempotent — stopping an idle/unknown conversation is a no-op.
+	 */
+	stopTurn(conversationId: string): { readonly abortedTurn: boolean };
 	handleMessage(input: {
 		conversationId: string;
 		text: string;
@@ -567,6 +575,15 @@ export function createSessionOrchestrator(
 			return { abortedTurn };
 		},
 
+		stopTurn(conversationId) {
+			const turn = activeTurns.get(conversationId);
+			const abortedTurn = turn !== undefined;
+			if (turn !== undefined) {
+				turn.controller.abort();
+			}
+			return { abortedTurn };
+		},
+
 		async handleMessage({ conversationId, text, onEvent, modelName, cwd, reasoningEffort }) {
 			const turnInput: StartTurnInput = {
 				conversationId,
diff --git a/packages/transport-http/src/app.test.ts b/packages/transport-http/src/app.test.ts
index b265f5e..674fd94 100644
--- a/packages/transport-http/src/app.test.ts
+++ b/packages/transport-http/src/app.test.ts
@@ -165,6 +165,9 @@ function createFakeOrchestrator(events: AgentEvent[]): SessionOrchestrator {
 		closeConversation() {
 			return { abortedTurn: false };
 		},
+		stopTurn() {
+			return { abortedTurn: false };
+		},
 		async handleMessage(input) {
 			for (const event of events) {
 				input.onEvent(event);
@@ -198,6 +201,9 @@ function createCapturingOrchestrator(): SessionOrchestrator & {
 		closeConversation() {
 			return { abortedTurn: false };
 		},
+		stopTurn() {
+			return { abortedTurn: false };
+		},
 		async handleMessage(input) {
 			state.received = input;
 		},
@@ -221,6 +227,9 @@ function createThrowingOrchestrator(error: Error): SessionOrchestrator {
 		closeConversation() {
 			return { abortedTurn: false };
 		},
+		stopTurn() {
+			return { abortedTurn: false };
+		},
 		async handleMessage() {
 			throw error;
 		},
diff --git a/packages/transport-http/src/app.ts b/packages/transport-http/src/app.ts
index 64e46fd..a2ee18c 100644
--- a/packages/transport-http/src/app.ts
+++ b/packages/transport-http/src/app.ts
@@ -396,6 +396,13 @@ export function createApp(opts: CreateServerOptions): Hono {
 		return c.json(body, 200);
 	});
 
+	app.post("/conversations/:id/stop", (c) => {
+		const conversationId = c.req.param("id");
+		const { abortedTurn } = opts.orchestrator.stopTurn(conversationId);
+		log.info("conversations: stop", { conversationId, abortedTurn });
+		return c.json({ conversationId, abortedTurn }, 200);
+	});
+
 	app.post("/conversations/:id/queue", async (c) => {
 		const conversationId = c.req.param("id");
 
diff --git a/packages/transport-http/src/extension.ts b/packages/transport-http/src/extension.ts
index 351dd4a..f7af615 100644
--- a/packages/transport-http/src/extension.ts
+++ b/packages/transport-http/src/extension.ts
@@ -39,6 +39,7 @@ export const manifest: Manifest = {
 			"/conversations/:id/open",
 			"/conversations/:id/queue",
 			"/conversations/:id/reasoning-effort",
+			"/conversations/:id/stop",
 			"/conversations/:id/title",
 			"/health",
 			"/models",
diff --git a/packages/transport-http/src/server.bun.test.ts b/packages/transport-http/src/server.bun.test.ts
index 3b7700e..fa519af 100644
--- a/packages/transport-http/src/server.bun.test.ts
+++ b/packages/transport-http/src/server.bun.test.ts
@@ -92,6 +92,9 @@ function fakeOrchestrator(): SessionOrchestrator {
 		closeConversation() {
 			return { abortedTurn: false };
 		},
+		stopTurn() {
+			return { abortedTurn: false };
+		},
 		async handleMessage() {},
 	};
 }
diff --git a/packages/transport-ws/src/server.bun.test.ts b/packages/transport-ws/src/server.bun.test.ts
index e723766..6d5db96 100644
--- a/packages/transport-ws/src/server.bun.test.ts
+++ b/packages/transport-ws/src/server.bun.test.ts
@@ -169,6 +169,9 @@ function fakeOrchestrator(opts?: FakeOrchestratorOpts): SessionOrchestrator & {
 		closeConversation() {
 			return { abortedTurn: false };
 		},
+		stopTurn() {
+			return { abortedTurn: false };
+		},
 		async handleMessage(_input) {
 			// Not used by the new transport-ws, but kept for interface compat.
 		},
@@ -219,6 +222,9 @@ function fakeOrchestratorWithBroadcast(): SessionOrchestrator & {
 		closeConversation() {
 			return { abortedTurn: false };
 		},
+		stopTurn() {
+			return { abortedTurn: false };
+		},
 		async handleMessage(_input) {},
 	};
 }