feat(sdk): expose terminal agent lifecycle status

apps/docs/content/docs/cli/cli-reference.mdx

@@ -947,12 +947,23 @@ superset terminals create --workspace ws_…
 		{ flag: "--workspace <id>", required: true, description: "Workspace UUID." },
 		{ flag: "--host <id>", description: "Host the workspace lives on (default: this machine)." },
 	]}
-	output={`{
-  sessions: Array<TerminalSession>;
+output={`{
+  sessions: Array<TerminalSession & {
+    agentStatus?: {
+      agentId: string;
+      sessionId?: string;
+      definitionId?: string;
+      startedAt: number;
+      lastEventType: "Start" | "Stop" | "PermissionRequest" | "Failed" | "Attached" | "Detached";
+      lastEventAt: number;
+    };
+  }>;
 }`}
 >
 List the live terminal sessions in a workspace. Presence in the list means the
-PTY exists, not that an agent inside it is working or idle.
+PTY exists. When Superset has identified a live agent inside it, `agentStatus`
+reports the same normalized lifecycle state used by the workspace board;
+`PermissionRequest` means the agent needs attention.
 </Command>
 
 <Command

apps/docs/content/docs/sdk/reference.mdx

@@ -265,6 +265,26 @@ const { terminalId } = await client.terminals.create({
 });
 ```
 
+### `terminals.list({ hostId, workspaceId })`
+
+List the live terminal sessions in a workspace. When Superset has identified
+an agent in a terminal, its row includes `agentStatus` with the agent and
+session identity and the latest normalized lifecycle event. A
+`PermissionRequest` event means the agent is waiting for input or approval.
+
+```ts
+const { sessions } = await client.terminals.list({
+  hostId: '<machineId>',
+  workspaceId: '<uuid>',
+});
+
+for (const terminal of sessions) {
+  if (terminal.agentStatus?.lastEventType === 'PermissionRequest') {
+    console.log(`${terminal.agentStatus.agentId} needs attention`);
+  }
+}
+```
+
 ---
 
 ## automations

packages/host-service/src/trpc/router/terminal/terminal.ts

@@ -133,11 +133,39 @@ export const terminalRouter = router({
 				})
 				.optional(),
 		)
-		.query(async ({ ctx, input }) => ({
-			sessions: await listLiveTerminalSessions(ctx.db, {
+		.query(async ({ ctx, input }) => {
+			const sessions = await listLiveTerminalSessions(ctx.db, {
 				workspaceId: input?.workspaceId,
-			}),
-		})),
+			});
+			const agentsByTerminal = new Map(
+				(input?.workspaceId
+					? ctx.terminalAgentStore.listByWorkspace(input.workspaceId)
+					: []
+				).map((binding) => [binding.terminalId, binding] as const),
+			);
+
+			return {
+				sessions: sessions.map((session) => {
+					const binding = agentsByTerminal.get(session.terminalId);
+					if (!binding) return session;
+					return {
+						...session,
+						agentStatus: {
+							agentId: binding.agentId,
+							...(binding.agentSessionId
+								? { sessionId: binding.agentSessionId }
+								: {}),
+							...(binding.definitionId
+								? { definitionId: binding.definitionId }
+								: {}),
+							startedAt: binding.startedAt,
+							lastEventAt: binding.lastEventAt,
+							lastEventType: binding.lastEventType,
+						},
+					};
+				}),
+			};
+		}),
 
 	hasRunningProcess: protectedProcedure
 		.input(

packages/host-service/test/integration/terminal.integration.test.ts

@@ -92,7 +92,7 @@ describe("terminal router integration", () => {
 		).rejects.toBeInstanceOf(TRPCClientError);
 	});
 
-	test("createSession sends the configured shell to the daemon instead of inherited bash", async () => {
+	test("createSession uses the configured shell and list includes live agent status", async () => {
 		const tmp = mkdtempSync(join(tmpdir(), "host-service-terminal-shell-"));
 		const socketPath = join(tmp, "pty-daemon.sock");
 		const fakeFishPath = join(tmp, "fish");
@@ -145,6 +145,25 @@ describe("terminal router integration", () => {
 			expect(meta.argv[1]).toBe("--init-command");
 			expect(meta.env?.SHELL).toBe(fakeFishPath);
 			expect(meta.env?.SUPERSET_TERMINAL_ID).toBe(terminalId);
+
+			await scenario.host.unauthenticatedTrpc.notifications.hook.mutate({
+				terminalId,
+				eventType: "request_user_input",
+				agent: { agentId: "codex", sessionId: "thread-123" },
+			});
+			const listedWithAgent = await scenario.host.trpc.terminal.list.query({
+				workspaceId: scenario.workspaceId,
+			});
+			const terminal = listedWithAgent.sessions.find(
+				(session) => session.terminalId === terminalId,
+			);
+			expect(terminal?.agentStatus).toMatchObject({
+				agentId: "codex",
+				sessionId: "thread-123",
+				lastEventType: "PermissionRequest",
+			});
+			expect(terminal?.agentStatus?.startedAt).toBeNumber();
+			expect(terminal?.agentStatus?.lastEventAt).toBeNumber();
 		} finally {
 			await scenario.host.trpc.terminal.killSession
 				.mutate({

packages/sdk/src/client.ts

@@ -94,6 +94,8 @@ import {
 	TaskUpdateParams,
 } from "./resources/tasks";
 import {
+	TerminalAgentLifecycleEventType,
+	TerminalAgentStatus,
 	TerminalCloseParams,
 	TerminalCloseResult,
 	TerminalCreateParams,
@@ -1282,6 +1284,8 @@ export declare namespace Superset {
 
 	export {
 		Terminals,
+		TerminalAgentLifecycleEventType,
+		TerminalAgentStatus,
 		TerminalCreateParams,
 		TerminalCreateResult,
 		TerminalListParams,

packages/sdk/src/index.ts

@@ -55,6 +55,8 @@ export {
 	Tasks,
 	type TaskUpdateParams,
 	type TerminalCloseParams,
+	type TerminalAgentLifecycleEventType,
+	type TerminalAgentStatus,
 	type TerminalCloseResult,
 	type TerminalCreateParams,
 	type TerminalCreateResult,

packages/sdk/src/resources/index.ts

@@ -30,6 +30,8 @@ export {
 } from "./organization";
 export { type Project, type ProjectListResponse, Projects } from "./projects";
 export {
+	type TerminalAgentLifecycleEventType,
+	type TerminalAgentStatus,
 	type TerminalCloseParams,
 	type TerminalCloseResult,
 	type TerminalCreateParams,

packages/sdk/src/resources/terminals.ts

@@ -121,6 +121,25 @@ export interface TerminalSummary {
 	exitCode: number;
 	attached: boolean;
 	title: string | null;
+	/** Present when Superset has identified a live agent in this terminal. */
+	agentStatus?: TerminalAgentStatus;
+}
+
+export type TerminalAgentLifecycleEventType =
+	| "Start"
+	| "Stop"
+	| "PermissionRequest"
+	| "Failed"
+	| "Attached"
+	| "Detached";
+
+export interface TerminalAgentStatus {
+	agentId: string;
+	sessionId?: string;
+	definitionId?: string;
+	startedAt: number;
+	lastEventAt: number;
+	lastEventType: TerminalAgentLifecycleEventType;
 }
 
 export interface TerminalListResult {
@@ -185,6 +204,8 @@ export declare namespace Terminals {
 		TerminalListParams,
 		TerminalListResult,
 		TerminalSummary,
+		TerminalAgentStatus,
+		TerminalAgentLifecycleEventType,
 		TerminalSendParams,
 		TerminalSendResult,
 		TerminalReadParams,