pi-interactive-shell 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to the `pi-interactive-shell` extension will be documented in this file.
 
+## [0.4.0] - 2026-01-17
+
+### Added
+- **Non-blocking hands-free mode** - Major change: `mode: "hands-free"` now returns immediately with a sessionId. The overlay opens for the user but the agent gets control back right away. Use `interactive_shell({ sessionId })` to query status/output and `interactive_shell({ sessionId, kill: true })` to end the session when done.
+- **Session status queries** - Query active session with just `sessionId` to get current status and any new output since last check.
+- **Kill option** - `interactive_shell({ sessionId, kill: true })` to programmatically end a session.
+- **autoExitOnQuiet** option - Auto-kill session when output stops (after quietThreshold). Use `handsFree: { autoExitOnQuiet: true }` for sessions that should end when the nested agent goes quiet.
+- **Output truncation** - Status queries now truncate output to 10KB (keeping the most recent content) to prevent overwhelming agent context. Truncation is indicated in the response.
+
+### Fixed
+- **Non-blocking mode session lifecycle** - Sessions now stay registered after completion so agent can query final status. Previously, sessions were unregistered before agent could query completion result.
+- **User takeover in non-blocking mode** - Agent can now see "user-takeover" status when querying. Previously, session was immediately unregistered when user took over.
+- **Type mismatch in registerActive** - Fixed `getOutput` return type to match `OutputResult` interface.
+- **Agent output position after buffer trim** - Fixed `agentOutputPosition` becoming stale when raw buffer is trimmed. When the 1MB buffer limit is exceeded and old content discarded, the agent query position is now clamped to prevent returning empty output or missing data.
+- **killAll() map iteration** - Fixed modifying maps during iteration in `killAll()`. Now collects IDs/entries first to avoid unpredictable behavior when killing sessions triggers unregistration callbacks.
+- **ActiveSessionResult type** - Fixed type mismatch where `output` field was required but never populated. Updated interface to match actual return type from `getResult()`.
+- **Unbounded raw output growth** - rawOutput buffer now capped at 1MB, trimming old content to prevent memory growth in long-running sessions
+- **Session ID reuse** - IDs are only released when session fully terminates, preventing reuse while session still running after takeover
+- **DSR cursor responses** - Fixed stale cursor position when DSR appears mid-chunk; now processes chunks in order, writing to xterm before responding
+- **Active sessions on shutdown** - Hands-free sessions are now killed on `session_shutdown`, preventing orphan processes
+- **Quiet threshold timer** - Changing threshold now restarts any active quiet timer with the new value
+- **Empty string input** - Now shows "(empty)" instead of blank in success message
+- **Hands-free auto-close on exit** - Overlay now closes immediately when process exits in hands-free mode, returning control to the agent instead of waiting for countdown
+- Handoff preview now uses raw output stream instead of xterm buffer. TUI apps using alternate screen buffer (like Codex, Claude, etc.) would show misleading/stale content in the preview.
+
 ## [0.3.0] - 2026-01-17
 
 ### Added

package/SKILL.md

@@ -66,48 +66,64 @@ Agent starts working immediately, user supervises.
 interactive_shell({ command: 'pi "Review this codebase for security issues"' })
 ```
 
-### Hands-Free (Foreground Subagent)
-Agent works autonomously, you receive periodic updates, user can take over anytime.
+### Hands-Free (Foreground Subagent) - NON-BLOCKING
+Agent works autonomously, **returns immediately** with sessionId. You query for status/output and kill when done.
+
 ```typescript
+// 1. Start session - returns immediately
 interactive_shell({
   command: 'pi "Fix all TypeScript errors in src/"',
   mode: "hands-free",
   reason: "Fixing TS errors"
 })
-```
+// Returns: { sessionId: "calm-reef", status: "running" }
 
-This is the primary pattern for **foreground subagents** - you delegate to pi (or another agent if user specifies) while monitoring progress.
+// 2. Check status and get new output
+interactive_shell({ sessionId: "calm-reef" })
+// Returns: { status: "running", output: "...", runtime: 30000 }
 
-## Hands-Free Status Updates
+// 3. When you see task is complete, kill session
+interactive_shell({ sessionId: "calm-reef", kill: true })
+// Returns: { status: "killed", output: "final output..." }
+```
 
-When running in hands-free mode, `sessionId` is available immediately in the first update (before the overlay opens). Subsequent updates include:
-- `status: "running"` - update with **incremental output** (only new content since last update)
-- `status: "user-takeover"` - user typed something and took control
-- `status: "exited"` - process exited (final update before tool returns)
+This is the primary pattern for **foreground subagents** - you delegate to pi (or another agent), query for progress, and decide when the task is done.
 
-Updates include budget tracking: `totalCharsSent` and `budgetExhausted` fields.
+## Hands-Free Workflow
 
-After takeover or exit, the tool continues blocking until the session closes.
+### Starting a Session
+```typescript
+const result = interactive_shell({
+  command: 'codex "Review this codebase"',
+  mode: "hands-free"
+})
+// result.sessionId = "calm-reef"
+// result.status = "running"
+```
 
-### Update Modes
+The user sees the overlay immediately. You get control back to continue working.
 
-**on-quiet (default)**: Updates emit after 5 seconds of output silence. Perfect for agent-to-agent delegation - you receive complete "thoughts" rather than fragments mid-stream.
+### Querying Status
+```typescript
+interactive_shell({ sessionId: "calm-reef" })
+```
 
-**interval**: Updates emit on a fixed schedule (every 60s). Use when continuous output is expected.
+Returns:
+- `status`: "running" | "user-takeover" | "exited" | "killed" | "backgrounded"
+- `output`: New output since last check (incremental)
+- `runtime`: Time elapsed in ms
 
+### Ending a Session
 ```typescript
-// Default: on-quiet mode (recommended for agent delegation)
-interactive_shell({
-  command: 'pi "Fix all TypeScript errors"',
-  mode: "hands-free"
-})
+interactive_shell({ sessionId: "calm-reef", kill: true })
+```
 
-// Force interval mode for continuous output
-interactive_shell({
-  command: 'tail -f /var/log/app.log',
-  mode: "hands-free",
-  handsFree: { updateMode: "interval", updateInterval: 10000 }
-})
+Kill when you see the task is complete in the output. Returns final status and output.
+
+### Sending Input
+```typescript
+interactive_shell({ sessionId: "calm-reef", input: "/help\n" })
+interactive_shell({ sessionId: "calm-reef", input: { keys: ["ctrl+c"] } })
 ```
 
 ### Context Budget

package/index.ts

@@ -294,31 +294,31 @@ The user will see the process in an overlay. They can:
 - Detach (double-Escape) to kill or run in background
 - In hands-free mode: type anything to take over control
 
-HANDS-FREE MODE:
-When mode="hands-free", you get updates when output stops (default: 5s of quiet).
-Updates only include NEW output since the last update, not the full tail.
-The user sees the overlay but you control the session. If user types anything,
-they automatically take over and you'll be notified.
-
-UPDATE MODES:
-- on-quiet (default): Emit update after 5s of no output. Perfect for agent-to-agent delegation.
-- interval: Emit on fixed schedule (every 60s). Use when continuous output is expected.
-
-Max interval (60s) acts as fallback in on-quiet mode for long continuous output.
-
-CONTEXT BUDGET:
-Updates have a total budget (default: 100KB). Once exhausted, updates still arrive
-but without content. You can adjust via handsFree.maxTotalChars.
-
-Use hands-free when you want to monitor a long-running agent without blocking.
+HANDS-FREE MODE (NON-BLOCKING):
+When mode="hands-free", the tool returns IMMEDIATELY with a sessionId.
+The overlay opens for the user to watch, but you (the agent) get control back right away.
+
+Workflow:
+1. Start session: interactive_shell({ command: 'pi "Fix bugs"', mode: "hands-free" })
+   -> Returns immediately with sessionId
+2. Check status/output: interactive_shell({ sessionId: "calm-reef" })
+   -> Returns current status and any new output since last check
+3. When task is done: interactive_shell({ sessionId: "calm-reef", kill: true })
+   -> Kills session and returns final output
+
+The user sees the overlay and can:
+- Watch output in real-time
+- Take over by typing (you'll see "user-takeover" status on next query)
+- Kill/background via double-Escape
 
-SENDING INPUT AND CHANGING SETTINGS:
-In hands-free mode, you receive a sessionId in updates. Use this to send input:
-- interactive_shell({ sessionId: "calm-reef", input: "/model\\n" })
-- interactive_shell({ sessionId: "calm-reef", input: { text: "sonnet", keys: ["down", "enter"] } })
+QUERYING SESSION STATUS:
+- interactive_shell({ sessionId: "calm-reef" }) - get status + new output
+- interactive_shell({ sessionId: "calm-reef", kill: true }) - end session
+- interactive_shell({ sessionId: "calm-reef", input: "..." }) - send input
 
-Change update frequency dynamically:
-- interactive_shell({ sessionId: "calm-reef", settings: { updateInterval: 60000 } })
+SENDING INPUT:
+- interactive_shell({ sessionId: "calm-reef", input: "/help\\n" })
+- interactive_shell({ sessionId: "calm-reef", input: { keys: ["ctrl+c"] } })
 
 Named keys: up, down, left, right, enter, escape, tab, backspace, ctrl+c, ctrl+d, etc.
 Modifiers: ctrl+x, alt+x, shift+tab, ctrl+alt+delete (or c-x, m-x, s-tab syntax)
@@ -347,7 +347,12 @@ Examples:
 			),
 			sessionId: Type.Optional(
 				Type.String({
-					description: "Session ID to send input to an existing hands-free session",
+					description: "Session ID to interact with an existing hands-free session",
+				}),
+			),
+			kill: Type.Optional(
+				Type.Boolean({
+					description: "Kill the session (requires sessionId). Use when task appears complete.",
 				}),
 			),
 			settings: Type.Optional(
@@ -427,6 +432,11 @@ Examples:
 					maxTotalChars: Type.Optional(
 						Type.Number({ description: "Total char budget for all updates (default: 100000). Updates stop including content when exhausted." }),
 					),
+					autoExitOnQuiet: Type.Optional(
+						Type.Boolean({
+							description: "Auto-kill session when output stops (after quietThreshold). Use for agents that don't exit on their own after completing a task.",
+						}),
+					),
 				}),
 			),
 			handoffPreview: Type.Optional(
@@ -456,6 +466,7 @@ Examples:
 			const {
 				command,
 				sessionId,
+				kill,
 				settings,
 				input,
 				cwd,
@@ -469,6 +480,7 @@ Examples:
 			} = params as {
 				command?: string;
 				sessionId?: string;
+				kill?: boolean;
 				settings?: { updateInterval?: number; quietThreshold?: number };
 				input?: string | { text?: string; keys?: string[]; hex?: string[]; paste?: string };
 				cwd?: string;
@@ -481,14 +493,15 @@ Examples:
 					quietThreshold?: number;
 					updateMaxChars?: number;
 					maxTotalChars?: number;
+					autoExitOnQuiet?: boolean;
 				};
 				handoffPreview?: { enabled?: boolean; lines?: number; maxChars?: number };
 				handoffSnapshot?: { enabled?: boolean; lines?: number; maxChars?: number };
 				timeout?: number;
 			};
 
-			// Mode 1: Interact with existing session (send input and/or change settings)
-			if (sessionId && (input !== undefined || settings)) {
+			// Mode 1: Interact with existing session (query status, send input, kill, or change settings)
+			if (sessionId) {
 				const session = sessionManager.getActive(sessionId);
 				if (!session) {
 					return {
@@ -498,6 +511,34 @@ Examples:
 					};
 				}
 
+				// Kill session if requested
+				if (kill) {
+					const { output, truncated, totalBytes } = session.getOutput();
+					const status = session.getStatus();
+					const runtime = session.getRuntime();
+					session.kill();
+					sessionManager.unregisterActive(sessionId, true);
+
+					const truncatedNote = truncated ? ` (${totalBytes} bytes total, truncated)` : "";
+					return {
+						content: [
+							{
+								type: "text",
+								text: `Session ${sessionId} killed after ${formatDurationMs(runtime)}${output ? `\n\nFinal output${truncatedNote}:\n${output}` : ""}`,
+							},
+						],
+						details: {
+							sessionId,
+							status: "killed",
+							runtime,
+							output,
+							outputTruncated: truncated,
+							outputTotalBytes: totalBytes,
+							previousStatus: status,
+						},
+					};
+				}
+
 				const actions: string[] = [];
 
 				// Apply settings changes
@@ -529,9 +570,11 @@ Examples:
 
 					const inputDesc =
 						typeof input === "string"
-							? input.length > 50
-								? `${input.slice(0, 50)}...`
-								: input
+							? input.length === 0
+								? "(empty)"
+								: input.length > 50
+									? `${input.slice(0, 50)}...`
+									: input
 							: [
 									input.text ?? "",
 									input.keys ? `keys:[${input.keys.join(",")}]` : "",
@@ -544,6 +587,59 @@ Examples:
 					actions.push(`sent: ${inputDesc}`);
 				}
 
+				// If only querying status (no input, no settings, no kill)
+				if (actions.length === 0) {
+					const { output, truncated, totalBytes } = session.getOutput();
+					const status = session.getStatus();
+					const runtime = session.getRuntime();
+					const result = session.getResult();
+
+					const truncatedNote = truncated ? ` (${totalBytes} bytes total, truncated to last 10KB)` : "";
+					const hasOutput = output.length > 0;
+
+					// Check if session completed
+					if (result) {
+						sessionManager.unregisterActive(sessionId, true);
+						return {
+							content: [
+								{
+									type: "text",
+									text: `Session ${sessionId} ${status} after ${formatDurationMs(runtime)}${hasOutput ? `\n\nOutput${truncatedNote}:\n${output}` : ""}`,
+								},
+							],
+							details: {
+								sessionId,
+								status,
+								runtime,
+								output,
+								outputTruncated: truncated,
+								outputTotalBytes: totalBytes,
+								exitCode: result.exitCode,
+								signal: result.signal,
+								backgroundId: result.backgroundId,
+							},
+						};
+					}
+
+					return {
+						content: [
+							{
+								type: "text",
+								text: `Session ${sessionId} ${status} (${formatDurationMs(runtime)})${hasOutput ? `\n\nNew output${truncatedNote}:\n${output}` : "\n\n(no new output)"}`,
+							},
+						],
+						details: {
+							sessionId,
+							status,
+							runtime,
+							output,
+							outputTruncated: truncated,
+							outputTotalBytes: totalBytes,
+							hasNewOutput: hasOutput,
+						},
+					};
+				}
+
 				return {
 					content: [{ type: "text", text: `Session ${sessionId}: ${actions.join(", ")}` }],
 					details: { sessionId, actions },
@@ -556,7 +652,7 @@ Examples:
 					content: [
 						{
 							type: "text",
-							text: "Either 'command' (to start a session) or 'sessionId' + 'input' (to send input) is required",
+							text: "Either 'command' (to start a session) or 'sessionId' (to query/interact with existing session) is required",
 						},
 					],
 					isError: true,
@@ -576,16 +672,89 @@ Examples:
 			const config = loadConfig(effectiveCwd);
 			const isHandsFree = mode === "hands-free";
 
-			// Generate sessionId early so it's available in the first update
+			// Generate sessionId early so it's available immediately
 			const generatedSessionId = isHandsFree ? generateSessionId(name) : undefined;
 
+			// For hands-free mode: non-blocking - return immediately with sessionId
+			// Agent can then query status/output via sessionId and kill when done
+			if (isHandsFree && generatedSessionId) {
+				// Start overlay but don't await - it runs in background
+				const overlayPromise = ctx.ui.custom<InteractiveShellResult>(
+					(tui, theme, _kb, done) =>
+						new InteractiveShellOverlay(
+							tui,
+							theme,
+							{
+								command,
+								cwd: effectiveCwd,
+								name,
+								reason,
+								mode,
+								sessionId: generatedSessionId,
+								handsFreeUpdateMode: handsFree?.updateMode,
+								handsFreeUpdateInterval: handsFree?.updateInterval,
+								handsFreeQuietThreshold: handsFree?.quietThreshold,
+								handsFreeUpdateMaxChars: handsFree?.updateMaxChars,
+								handsFreeMaxTotalChars: handsFree?.maxTotalChars,
+								autoExitOnQuiet: handsFree?.autoExitOnQuiet,
+								// No onHandsFreeUpdate in non-blocking mode - agent queries directly
+								handoffPreviewEnabled: handoffPreview?.enabled,
+								handoffPreviewLines: handoffPreview?.lines,
+								handoffPreviewMaxChars: handoffPreview?.maxChars,
+								handoffSnapshotEnabled: handoffSnapshot?.enabled,
+								handoffSnapshotLines: handoffSnapshot?.lines,
+								handoffSnapshotMaxChars: handoffSnapshot?.maxChars,
+								timeout,
+							},
+							config,
+							done,
+						),
+					{
+						overlay: true,
+						overlayOptions: {
+							width: `${config.overlayWidthPercent}%`,
+							maxHeight: `${config.overlayHeightPercent}%`,
+							anchor: "center",
+							margin: 1,
+						},
+					},
+				);
+
+				// Handle overlay completion in background (cleanup when user closes)
+				overlayPromise.then((result) => {
+					// Session already handles cleanup via finishWith* methods
+					// This just ensures the promise doesn't cause unhandled rejection
+					if (result.userTookOver) {
+						// User took over - session continues interactively
+					}
+				}).catch(() => {
+					// Ignore errors - session cleanup handles this
+				});
+
+				// Return immediately - agent can query via sessionId
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Session started: ${generatedSessionId}\nCommand: ${command}\n\nUse interactive_shell({ sessionId: "${generatedSessionId}" }) to check status/output.\nUse interactive_shell({ sessionId: "${generatedSessionId}", kill: true }) to end when done.`,
+						},
+					],
+					details: {
+						sessionId: generatedSessionId,
+						status: "running",
+						command,
+						reason,
+					},
+				};
+			}
+
+			// Interactive mode: blocking - wait for overlay to close
 			onUpdate?.({
-				content: [{ type: "text", text: `Opening${isHandsFree ? " (hands-free)" : ""}: ${command}` }],
+				content: [{ type: "text", text: `Opening: ${command}` }],
 				details: {
 					exitCode: null,
 					backgrounded: false,
 					cancelled: false,
-					sessionId: generatedSessionId,
 				},
 			});
 
@@ -606,6 +775,7 @@ Examples:
 							handsFreeQuietThreshold: handsFree?.quietThreshold,
 							handsFreeUpdateMaxChars: handsFree?.updateMaxChars,
 							handsFreeMaxTotalChars: handsFree?.maxTotalChars,
+							autoExitOnQuiet: handsFree?.autoExitOnQuiet,
 							onHandsFreeUpdate: isHandsFree
 								? (update) => {
 										let statusText: string;

package/overlay-component.ts

@@ -62,6 +62,8 @@ export interface InteractiveShellOptions {
 	handsFreeUpdateMaxChars?: number;
 	handsFreeMaxTotalChars?: number;
 	onHandsFreeUpdate?: (update: HandsFreeUpdate) => void;
+	// Auto-exit when output stops (for agents that don't exit on their own)
+	autoExitOnQuiet?: boolean;
 	// Auto-kill timeout
 	timeout?: number;
 }
@@ -120,6 +122,9 @@ export class InteractiveShellOverlay implements Component, Focusable {
 	private lastDataTime = 0;
 	private quietTimer: ReturnType<typeof setTimeout> | null = null;
 	private hasUnsentData = false;
+	// Non-blocking mode: track status and output for agent queries
+	private agentOutputPosition = 0; // Track last read position for incremental output
+	private completionResult: InteractiveShellResult | undefined;
 
 	constructor(
 		tui: TUI,
@@ -169,7 +174,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 					// Stop timeout to prevent double done() call
 					this.stopTimeout();
 
-					// Send final update with any unsent data, then "exited" notification
+					// In hands-free mode (user hasn't taken over): send exited notification and auto-close immediately
 					if (this.state === "hands-free" && this.options.onHandsFreeUpdate && this.sessionId) {
 						// Flush any pending output before sending exited notification
 						if (this.hasUnsentData || this.updateMode === "interval") {
@@ -186,8 +191,12 @@ export class InteractiveShellOverlay implements Component, Focusable {
 							totalCharsSent: this.totalCharsSent,
 							budgetExhausted: this.budgetExhausted,
 						});
-						this.unregisterActiveSession();
+						// Auto-close immediately in hands-free mode - agent should get control back
+						this.finishWithExit();
+						return;
 					}
+
+					// Interactive mode (or user took over): show exit state with countdown
 					this.stopHandsFreeUpdates();
 					this.state = "exited";
 					this.exitCountdown = this.config.exitAutoCloseDelay;
@@ -207,13 +216,19 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			this.state = "hands-free";
 			// Use provided sessionId or generate one
 			this.sessionId = options.sessionId ?? generateSessionId(options.name);
-			sessionManager.registerActive(
-				this.sessionId,
-				options.command,
-				(data) => this.session.write(data),
-				(intervalMs) => this.setUpdateInterval(intervalMs),
-				(thresholdMs) => this.setQuietThreshold(thresholdMs),
-			);
+			sessionManager.registerActive({
+				id: this.sessionId,
+				command: options.command,
+				reason: options.reason,
+				write: (data) => this.session.write(data),
+				kill: () => this.killSession(),
+				getOutput: () => this.getOutputSinceLastCheck(),
+				getStatus: () => this.getSessionStatus(),
+				getRuntime: () => this.getRuntime(),
+				getResult: () => this.getCompletionResult(),
+				setUpdateInterval: (intervalMs) => this.setUpdateInterval(intervalMs),
+				setQuietThreshold: (thresholdMs) => this.setQuietThreshold(thresholdMs),
+			});
 			this.startHandsFreeUpdates();
 		}
 
@@ -225,6 +240,72 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		}
 	}
 
+	// Public methods for non-blocking mode (agent queries)
+
+	// Max output per status query (10KB) - prevents overwhelming agent context
+	private static readonly MAX_STATUS_OUTPUT = 10 * 1024;
+
+	/** Get output since last check (incremental, truncated if too large) */
+	getOutputSinceLastCheck(): { output: string; truncated: boolean; totalBytes: number } {
+		const fullOutput = this.session.getRawStream({ stripAnsi: true });
+
+		// Handle case where buffer was trimmed and our position is now past the end
+		// This happens when rawOutput exceeds 1MB and older content is discarded
+		const clampedPosition = Math.min(this.agentOutputPosition, fullOutput.length);
+		const newOutput = fullOutput.substring(clampedPosition);
+		const totalBytes = newOutput.length;
+
+		// Always advance position (even if truncated, we don't want to re-send old data)
+		this.agentOutputPosition = fullOutput.length;
+
+		// Truncate if too large (keep the END, which is most recent/relevant)
+		if (newOutput.length > InteractiveShellOverlay.MAX_STATUS_OUTPUT) {
+			const truncated = newOutput.slice(-InteractiveShellOverlay.MAX_STATUS_OUTPUT);
+			return {
+				output: `[...${totalBytes - InteractiveShellOverlay.MAX_STATUS_OUTPUT} bytes truncated...]\n${truncated}`,
+				truncated: true,
+				totalBytes,
+			};
+		}
+
+		return { output: newOutput, truncated: false, totalBytes };
+	}
+
+	/** Get current session status */
+	getSessionStatus(): "running" | "user-takeover" | "exited" | "killed" | "backgrounded" {
+		if (this.completionResult) {
+			if (this.completionResult.cancelled) return "killed";
+			if (this.completionResult.backgrounded) return "backgrounded";
+			if (this.userTookOver) return "user-takeover";
+			return "exited";
+		}
+		if (this.userTookOver) return "user-takeover";
+		if (this.state === "exited") return "exited";
+		return "running";
+	}
+
+	/** Get runtime in milliseconds */
+	getRuntime(): number {
+		return Date.now() - this.startTime;
+	}
+
+	/** Get completion result (if session has ended) */
+	getCompletionResult(): InteractiveShellResult | undefined {
+		return this.completionResult;
+	}
+
+	/** Get the session ID */
+	getSessionId(): string | null {
+		return this.sessionId;
+	}
+
+	/** Kill the session programmatically */
+	killSession(): void {
+		if (!this.finished) {
+			this.finishWithKill();
+		}
+	}
+
 	private startExitCountdown(): void {
 		this.stopCountdown();
 		this.countdownInterval = setInterval(() => {
@@ -276,9 +357,34 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.stopQuietTimer();
 		this.quietTimer = setTimeout(() => {
 			this.quietTimer = null;
-			if (this.state === "hands-free" && this.hasUnsentData) {
-				this.emitHandsFreeUpdate();
-				this.hasUnsentData = false;
+			if (this.state === "hands-free") {
+				// Auto-exit on quiet: kill session when output stops (agent likely finished task)
+				if (this.options.autoExitOnQuiet) {
+					// Emit final update with any pending output
+					if (this.hasUnsentData) {
+						this.emitHandsFreeUpdate();
+						this.hasUnsentData = false;
+					}
+					// Send completion notification and auto-close
+					if (this.options.onHandsFreeUpdate && this.sessionId) {
+						this.options.onHandsFreeUpdate({
+							status: "exited",
+							sessionId: this.sessionId,
+							runtime: Date.now() - this.startTime,
+							tail: [],
+							tailTruncated: false,
+							totalCharsSent: this.totalCharsSent,
+							budgetExhausted: this.budgetExhausted,
+						});
+					}
+					this.finishWithKill();
+					return;
+				}
+				// Normal behavior: just emit update
+				if (this.hasUnsentData) {
+					this.emitHandsFreeUpdate();
+					this.hasUnsentData = false;
+				}
 			}
 		}, this.currentQuietThreshold);
 	}
@@ -320,6 +426,18 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		const clamped = Math.max(1000, Math.min(30000, thresholdMs));
 		if (clamped === this.currentQuietThreshold) return;
 		this.currentQuietThreshold = clamped;
+
+		// If a quiet timer is active, restart it with the new threshold
+		if (this.quietTimer && this.updateMode === "on-quiet") {
+			this.stopQuietTimer();
+			this.quietTimer = setTimeout(() => {
+				this.quietTimer = null;
+				if (this.hasUnsentData && !this.budgetExhausted) {
+					this.emitHandsFreeUpdate();
+					this.hasUnsentData = false;
+				}
+			}, this.currentQuietThreshold);
+		}
 	}
 
 	private stopHandsFreeUpdates(): void {
@@ -341,9 +459,9 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		}
 	}
 
-	private unregisterActiveSession(): void {
+	private unregisterActiveSession(releaseId = false): void {
 		if (this.sessionId && !this.sessionUnregistered) {
-			sessionManager.unregisterActive(this.sessionId);
+			sessionManager.unregisterActive(this.sessionId, releaseId);
 			this.sessionUnregistered = true;
 		}
 	}
@@ -410,22 +528,27 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		}
 
 		this.stopHandsFreeUpdates();
-		// Unregister from active sessions since user took over
-		this.unregisterActiveSession();
 		this.state = "running";
 		this.userTookOver = true;
 
-		// Notify agent that user took over
-		this.options.onHandsFreeUpdate?.({
-			status: "user-takeover",
-			sessionId: this.sessionId,
-			runtime: Date.now() - this.startTime,
-			tail: [],
-			tailTruncated: false,
-			userTookOver: true,
-			totalCharsSent: this.totalCharsSent,
-			budgetExhausted: this.budgetExhausted,
-		});
+		// Notify agent that user took over (streaming mode)
+		// In non-blocking mode, keep session registered so agent can query status
+		if (this.options.onHandsFreeUpdate) {
+			this.options.onHandsFreeUpdate({
+				status: "user-takeover",
+				sessionId: this.sessionId,
+				runtime: Date.now() - this.startTime,
+				tail: [],
+				tailTruncated: false,
+				userTookOver: true,
+				totalCharsSent: this.totalCharsSent,
+				budgetExhausted: this.budgetExhausted,
+			});
+			// Unregister after notification in streaming mode
+			this.unregisterActiveSession();
+		}
+		// In non-blocking mode (no onHandsFreeUpdate), keep session registered
+		// so agent can query and see "user-takeover" status
 
 		this.tui.requestRender();
 	}
@@ -438,11 +561,20 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		const maxChars = this.options.handoffPreviewMaxChars ?? this.config.handoffPreviewMaxChars;
 		if (lines <= 0 || maxChars <= 0) return undefined;
 
-		const tail = this.session.getTailLines({
-			lines,
-			ansi: false,
-			maxChars,
-		});
+		// Use raw output stream instead of xterm buffer - TUI apps using alternate
+		// screen buffer can have misleading content in getTailLines()
+		const rawOutput = this.session.getRawStream({ stripAnsi: true });
+		const outputLines = rawOutput.split("\n");
+
+		// Get last N lines, respecting maxChars
+		let tail: string[] = [];
+		let charCount = 0;
+		for (let i = outputLines.length - 1; i >= 0 && tail.length < lines; i--) {
+			const line = outputLines[i];
+			if (charCount + line.length > maxChars && tail.length > 0) break;
+			tail.unshift(line);
+			charCount += line.length + 1; // +1 for newline
+		}
 
 		return { type: "tail", when, lines: tail };
 	}
@@ -492,11 +624,11 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.stopCountdown();
 		this.stopTimeout();
 		this.stopHandsFreeUpdates();
-		this.unregisterActiveSession();
+
 		const handoffPreview = this.maybeBuildHandoffPreview("exit");
 		const handoff = this.maybeWriteHandoffSnapshot("exit");
 		this.session.dispose();
-		this.done({
+		const result: InteractiveShellResult = {
 			exitCode: this.session.exitCode,
 			signal: this.session.signal,
 			backgrounded: false,
@@ -505,7 +637,17 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			userTookOver: this.userTookOver,
 			handoffPreview,
 			handoff,
-		});
+		};
+		this.completionResult = result;
+
+		// In non-blocking mode (no onHandsFreeUpdate), keep session registered
+		// so agent can query completion result. Agent's query will unregister.
+		// In streaming mode, unregister now since agent got final update.
+		if (this.options.onHandsFreeUpdate) {
+			this.unregisterActiveSession(true);
+		}
+
+		this.done(result);
 	}
 
 	private finishWithBackground(): void {
@@ -514,11 +656,11 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.stopCountdown();
 		this.stopTimeout();
 		this.stopHandsFreeUpdates();
-		this.unregisterActiveSession();
+
 		const handoffPreview = this.maybeBuildHandoffPreview("detach");
 		const handoff = this.maybeWriteHandoffSnapshot("detach");
 		const id = sessionManager.add(this.options.command, this.session, this.options.name, this.options.reason);
-		this.done({
+		const result: InteractiveShellResult = {
 			exitCode: null,
 			backgrounded: true,
 			backgroundId: id,
@@ -527,7 +669,16 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			userTookOver: this.userTookOver,
 			handoffPreview,
 			handoff,
-		});
+		};
+		this.completionResult = result;
+
+		// In non-blocking mode (no onHandsFreeUpdate), keep session registered
+		// so agent can query completion result. Agent's query will unregister.
+		if (this.options.onHandsFreeUpdate) {
+			this.unregisterActiveSession(true);
+		}
+
+		this.done(result);
 	}
 
 	private finishWithKill(): void {
@@ -536,12 +687,12 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.stopCountdown();
 		this.stopTimeout();
 		this.stopHandsFreeUpdates();
-		this.unregisterActiveSession();
+
 		const handoffPreview = this.maybeBuildHandoffPreview("kill");
 		const handoff = this.maybeWriteHandoffSnapshot("kill");
 		this.session.kill();
 		this.session.dispose();
-		this.done({
+		const result: InteractiveShellResult = {
 			exitCode: null,
 			backgrounded: false,
 			cancelled: true,
@@ -549,7 +700,16 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			userTookOver: this.userTookOver,
 			handoffPreview,
 			handoff,
-		});
+		};
+		this.completionResult = result;
+
+		// In non-blocking mode (no onHandsFreeUpdate), keep session registered
+		// so agent can query completion result. Agent's query will unregister.
+		if (this.options.onHandsFreeUpdate) {
+			this.unregisterActiveSession(true);
+		}
+
+		this.done(result);
 	}
 
 	private finishWithTimeout(): void {
@@ -578,13 +738,12 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		}
 
 		this.stopHandsFreeUpdates();
-		this.unregisterActiveSession();
 		this.timedOut = true;
 		const handoffPreview = this.maybeBuildHandoffPreview("timeout");
 		const handoff = this.maybeWriteHandoffSnapshot("timeout");
 		this.session.kill();
 		this.session.dispose();
-		this.done({
+		const result: InteractiveShellResult = {
 			exitCode: null,
 			backgrounded: false,
 			cancelled: false,
@@ -593,7 +752,16 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			userTookOver: this.userTookOver,
 			handoffPreview,
 			handoff,
-		});
+		};
+		this.completionResult = result;
+
+		// In non-blocking mode (no onHandsFreeUpdate), keep session registered
+		// so agent can query completion result. Agent's query will unregister.
+		if (this.options.onHandsFreeUpdate) {
+			this.unregisterActiveSession(true);
+		}
+
+		this.done(result);
 	}
 
 	private handleDoubleEscape(): boolean {
@@ -810,7 +978,10 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.stopTimeout();
 		this.stopHandsFreeUpdates();
 		// Safety cleanup in case dispose() is called without going through finishWith*
-		this.unregisterActiveSession();
+		// In non-blocking mode with completion result, keep session so agent can query
+		if (!this.completionResult || this.options.onHandsFreeUpdate) {
+			this.unregisterActiveSession();
+		}
 	}
 }
 
@@ -907,11 +1078,20 @@ export class ReattachOverlay implements Component, Focusable {
 		const maxChars = this.config.handoffPreviewMaxChars;
 		if (lines <= 0 || maxChars <= 0) return undefined;
 
-		const tail = this.session.getTailLines({
-			lines,
-			ansi: false,
-			maxChars,
-		});
+		// Use raw output stream instead of xterm buffer - TUI apps using alternate
+		// screen buffer can have misleading content in getTailLines()
+		const rawOutput = this.session.getRawStream({ stripAnsi: true });
+		const outputLines = rawOutput.split("\n");
+
+		// Get last N lines, respecting maxChars
+		let tail: string[] = [];
+		let charCount = 0;
+		for (let i = outputLines.length - 1; i >= 0 && tail.length < lines; i--) {
+			const line = outputLines[i];
+			if (charCount + line.length > maxChars && tail.length > 0) break;
+			tail.unshift(line);
+			charCount += line.length + 1; // +1 for newline
+		}
 
 		return { type: "tail", when, lines: tail };
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-interactive-shell",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Run AI coding agents as foreground subagents in pi TUI overlays with hands-free monitoring",
   "type": "module",
   "bin": {

package/pty-session.ts

@@ -22,13 +22,40 @@ const CONTROL_REGEX = /[\x00-\x08\x0B\x0C\x0E-\x1A\x1C-\x1F\x7F]/g;
 // DSR (Device Status Report) - cursor position query: ESC[6n or ESC[?6n
 const DSR_PATTERN = /\x1b\[\??6n/g;
 
-function stripDsrRequests(input: string): { cleaned: string; requests: number } {
-	let requests = 0;
-	const cleaned = input.replace(DSR_PATTERN, () => {
-		requests += 1;
-		return "";
-	});
-	return { cleaned, requests };
+// Maximum raw output buffer size (1MB) - prevents unbounded memory growth
+const MAX_RAW_OUTPUT_SIZE = 1024 * 1024;
+
+interface DsrSplit {
+	segments: Array<{ text: string; dsrAfter: boolean }>;
+	hasDsr: boolean;
+}
+
+function splitAroundDsr(input: string): DsrSplit {
+	const segments: Array<{ text: string; dsrAfter: boolean }> = [];
+	let lastIndex = 0;
+	let hasDsr = false;
+
+	// Find all DSR requests and split around them
+	const regex = new RegExp(DSR_PATTERN.source, "g");
+	let match;
+	while ((match = regex.exec(input)) !== null) {
+		hasDsr = true;
+		// Text before this DSR
+		if (match.index > lastIndex) {
+			segments.push({ text: input.slice(lastIndex, match.index), dsrAfter: true });
+		} else {
+			// DSR at start or consecutive DSRs - add empty segment to trigger response
+			segments.push({ text: "", dsrAfter: true });
+		}
+		lastIndex = match.index + match[0].length;
+	}
+
+	// Remaining text after last DSR (or entire string if no DSR)
+	if (lastIndex < input.length) {
+		segments.push({ text: input.slice(lastIndex), dsrAfter: false });
+	}
+
+	return { segments, hasDsr };
 }
 
 function buildCursorPositionResponse(row = 1, col = 1): string {
@@ -202,6 +229,17 @@ export class PtyTerminalSession {
 	private dataHandler: ((data: string) => void) | undefined;
 	private exitHandler: ((exitCode: number, signal?: number) => void) | undefined;
 
+	// Trim raw output buffer if it exceeds max size
+	private trimRawOutputIfNeeded(): void {
+		if (this.rawOutput.length > MAX_RAW_OUTPUT_SIZE) {
+			const keepSize = Math.floor(MAX_RAW_OUTPUT_SIZE / 2);
+			const trimAmount = this.rawOutput.length - keepSize;
+			this.rawOutput = this.rawOutput.substring(trimAmount);
+			// Adjust stream position to account for trimmed content
+			this.lastStreamPosition = Math.max(0, this.lastStreamPosition - trimAmount);
+		}
+	}
+
 	constructor(options: PtySessionOptions, events: PtySessionEvents = {}) {
 		const {
 			command,
@@ -245,29 +283,40 @@ export class PtyTerminalSession {
 		this.ptyProcess.onData((data) => {
 			// Handle DSR (Device Status Report) cursor position queries
 			// TUI apps send ESC[6n or ESC[?6n expecting ESC[row;colR response
-			const { cleaned, requests } = stripDsrRequests(data);
-			if (requests > 0) {
-				// Respond with cursor position (use xterm's actual cursor position)
-				const buffer = this.xterm.buffer.active;
-				const response = buildCursorPositionResponse(buffer.cursorY + 1, buffer.cursorX + 1);
-				for (let i = 0; i < requests; i++) {
-					this.ptyProcess.write(response);
+			// We must process in order: write text to xterm, THEN respond to DSR
+			const { segments, hasDsr } = splitAroundDsr(data);
+
+			if (!hasDsr) {
+				// Fast path: no DSR in data
+				this.writeQueue.enqueue(async () => {
+					this.rawOutput += data;
+					this.trimRawOutputIfNeeded();
+					await new Promise<void>((resolve) => {
+						this.xterm.write(data, () => resolve());
+					});
+					this.dataHandler?.(data);
+				});
+			} else {
+				// Process each segment in order, responding to DSR after writing preceding text
+				for (const segment of segments) {
+					this.writeQueue.enqueue(async () => {
+						if (segment.text) {
+							this.rawOutput += segment.text;
+							this.trimRawOutputIfNeeded();
+							await new Promise<void>((resolve) => {
+								this.xterm.write(segment.text, () => resolve());
+							});
+							this.dataHandler?.(segment.text);
+						}
+						// If there was a DSR after this segment, respond with current cursor position
+						if (segment.dsrAfter) {
+							const buffer = this.xterm.buffer.active;
+							const response = buildCursorPositionResponse(buffer.cursorY + 1, buffer.cursorX + 1);
+							this.ptyProcess.write(response);
+						}
+					});
 				}
 			}
-
-			// Write cleaned data to xterm (without DSR sequences)
-			const dataToProcess = requests > 0 ? cleaned : data;
-
-			// Use write queue for ordered writes
-			this.writeQueue.enqueue(async () => {
-				// Track raw output for incremental streaming
-				this.rawOutput += dataToProcess;
-
-				await new Promise<void>((resolve) => {
-					this.xterm.write(dataToProcess, () => resolve());
-				});
-				this.dataHandler?.(dataToProcess);
-			});
 		});
 
 		this.ptyProcess.onExit(({ exitCode, signal }) => {

package/session-manager.ts

@@ -9,10 +9,33 @@ export interface BackgroundSession {
 	startedAt: Date;
 }
 
+export type ActiveSessionStatus = "running" | "user-takeover" | "exited" | "killed" | "backgrounded";
+
+export interface ActiveSessionResult {
+	exitCode: number | null;
+	signal?: number;
+	backgrounded?: boolean;
+	backgroundId?: string;
+	cancelled?: boolean;
+	timedOut?: boolean;
+}
+
+export interface OutputResult {
+	output: string;
+	truncated: boolean;
+	totalBytes: number;
+}
+
 export interface ActiveSession {
 	id: string;
 	command: string;
+	reason?: string;
 	write: (data: string) => void;
+	kill: () => void;
+	getOutput: () => OutputResult; // Get output since last check (truncated if large)
+	getStatus: () => ActiveSessionStatus;
+	getRuntime: () => number;
+	getResult: () => ActiveSessionResult | undefined; // Available when completed
 	setUpdateInterval?: (intervalMs: number) => void;
 	setQuietThreshold?: (thresholdMs: number) => void;
 	startedAt: Date;
@@ -100,26 +123,32 @@ export class ShellSessionManager {
 	private activeSessions = new Map<string, ActiveSession>();
 
 	// Active hands-free session management
-	registerActive(
-		id: string,
-		command: string,
-		write: (data: string) => void,
-		setUpdateInterval?: (intervalMs: number) => void,
-		setQuietThreshold?: (thresholdMs: number) => void,
-	): void {
-		this.activeSessions.set(id, {
-			id,
-			command,
-			write,
-			setUpdateInterval,
-			setQuietThreshold,
+	registerActive(session: {
+		id: string;
+		command: string;
+		reason?: string;
+		write: (data: string) => void;
+		kill: () => void;
+		getOutput: () => OutputResult;
+		getStatus: () => ActiveSessionStatus;
+		getRuntime: () => number;
+		getResult: () => ActiveSessionResult | undefined;
+		setUpdateInterval?: (intervalMs: number) => void;
+		setQuietThreshold?: (thresholdMs: number) => void;
+	}): void {
+		this.activeSessions.set(session.id, {
+			...session,
 			startedAt: new Date(),
 		});
 	}
 
-	unregisterActive(id: string): void {
+	unregisterActive(id: string, releaseId = false): void {
 		this.activeSessions.delete(id);
-		releaseSessionId(id);
+		// Only release the ID if explicitly requested (when session fully terminates)
+		// This prevents ID reuse while session is still running after takeover
+		if (releaseId) {
+			releaseSessionId(id);
+		}
 	}
 
 	getActive(id: string): ActiveSession | undefined {
@@ -217,9 +246,26 @@ export class ShellSessionManager {
 	}
 
 	killAll(): void {
-		for (const [id] of this.sessions) {
+		// Kill all background sessions
+		// Collect IDs first to avoid modifying map during iteration
+		const bgIds = Array.from(this.sessions.keys());
+		for (const id of bgIds) {
 			this.remove(id);
 		}
+
+		// Kill all active hands-free sessions
+		// Collect entries first since kill() may trigger unregisterActive()
+		const activeEntries = Array.from(this.activeSessions.entries());
+		for (const [id, session] of activeEntries) {
+			try {
+				session.kill();
+			} catch {
+				// Session may already be dead
+			}
+			// Release ID if not already released by kill()
+			releaseSessionId(id);
+		}
+		this.activeSessions.clear();
 	}
 }