pi-interactive-shell 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to the `pi-interactive-shell` extension will be documented in this file.
 
+## [0.4.2] - 2026-01-17
+
+### Added
+- **Query rate limiting** - Queries are limited to once every 60 seconds by default. If you query too soon, the tool automatically waits until the limit expires before returning (blocking behavior). Configurable via `minQueryIntervalSeconds` in settings (range: 5-300 seconds). Note: Rate limiting does not apply to completed sessions or kills - you can always query the final result immediately.
+
+### Changed
+- **autoExitOnQuiet now defaults to true** - In hands-free mode, sessions auto-kill when output stops (~5s of quiet). Set `handsFree: { autoExitOnQuiet: false }` to disable.
+- **Smaller default overlay** - Height reduced from 90% to 45%. Configurable via `overlayHeightPercent` in settings (range: 20-90%).
+
+### Fixed
+- **Rate limit wait now interruptible** - When waiting for rate limit, the wait is interrupted immediately if the session completes (user kills, process exits, etc.). Uses Promise.race with onComplete callback instead of blocking sleep.
+- **scrollbackLines NaN handling** - Config now uses `clampInt` like other numeric fields, preventing NaN from breaking xterm scrollback.
+- **autoExitOnQuiet status mismatch** - Now sends "killed" status (not "exited") to match `finishWithKill()` behavior.
+- **hasNewOutput semantics** - Renamed to `hasOutput` since we use tail-based output, not incremental tracking.
+- **dispose() orphaned sessions** - Now kills running processes before unregistering to prevent orphaned sessions.
+- **killAll() premature ID release** - IDs now released via natural cleanup after process exit, not immediately after kill() call.
+
+## [0.4.1] - 2026-01-17
+
+### Changed
+- **Rendered output for queries** - Status queries now return rendered terminal output (last 20 lines) instead of raw stream. This eliminates TUI animation noise (spinners, progress bars) and gives clean, readable content.
+- **Reduced output size** - Max 20 lines and 5KB per query (down from 100 lines and 10KB). Queries are for checking in, not dumping full output.
+
+### Fixed
+- **TUI noise in query output** - Raw stream captured all terminal animation (spinner text fragments like "Working", "orking", "rking"). Now uses xterm rendered buffer which shows clean final state.
+
 ## [0.4.0] - 2026-01-17
 
 ### Added

package/README.md

@@ -146,7 +146,7 @@ Project: `<cwd>/.pi/interactive-shell.json`
   "doubleEscapeThreshold": 300,
   "exitAutoCloseDelay": 10,
   "overlayWidthPercent": 95,
-  "overlayHeightPercent": 90,
+  "overlayHeightPercent": 45,
   "scrollbackLines": 5000,
   "ansiReemit": true,
   "handoffPreviewEnabled": true,

package/SKILL.md

@@ -110,9 +110,11 @@ interactive_shell({ sessionId: "calm-reef" })
 
 Returns:
 - `status`: "running" | "user-takeover" | "exited" | "killed" | "backgrounded"
-- `output`: New output since last check (incremental)
+- `output`: Last 20 lines of rendered terminal (clean, no TUI animation noise)
 - `runtime`: Time elapsed in ms
 
+**Rate limited:** Queries are limited to once every 60 seconds. If you query too soon, the tool will automatically wait until the limit expires before returning. The user is watching the overlay in real-time - you're just checking in periodically.
+
 ### Ending a Session
 ```typescript
 interactive_shell({ sessionId: "calm-reef", kill: true })
@@ -120,18 +122,20 @@ interactive_shell({ sessionId: "calm-reef", kill: true })
 
 Kill when you see the task is complete in the output. Returns final status and output.
 
+**Auto-exit:** In hands-free mode, sessions auto-kill when output stops (after ~5 seconds of quiet). This means when an agent finishes its task, the session closes automatically. You can disable this with `handsFree: { autoExitOnQuiet: false }`.
+
 ### Sending Input
 ```typescript
 interactive_shell({ sessionId: "calm-reef", input: "/help\n" })
 interactive_shell({ sessionId: "calm-reef", input: { keys: ["ctrl+c"] } })
 ```
 
-### Context Budget
+### Query Output
 
-Updates have a **total character budget** (default: 100KB) to prevent overwhelming your context window:
-- Each update includes only NEW output since the last update (not full tail)
-- Default: 1500 chars max per update, 100KB total budget
-- When budget is exhausted, updates continue but without content (status-only)
+Status queries return **rendered terminal output** (what's actually on screen), not raw stream:
+- Last 20 lines of the terminal, clean and readable
+- No TUI animation noise (spinners, progress bars, etc.)
+- Max 5KB per query to keep context manageable
 - Configure via `handsFree.maxTotalChars`
 
 ```typescript

package/config.ts

@@ -21,13 +21,15 @@ export interface InteractiveShellConfig {
 	handsFreeQuietThreshold: number;
 	handsFreeUpdateMaxChars: number;
 	handsFreeMaxTotalChars: number;
+	// Query rate limiting
+	minQueryIntervalSeconds: number;
 }
 
 const DEFAULT_CONFIG: InteractiveShellConfig = {
 	doubleEscapeThreshold: 300,
 	exitAutoCloseDelay: 10,
 	overlayWidthPercent: 95,
-	overlayHeightPercent: 90,
+	overlayHeightPercent: 45,
 	scrollbackLines: 5000,
 	ansiReemit: true,
 	handoffPreviewEnabled: true,
@@ -42,6 +44,8 @@ const DEFAULT_CONFIG: InteractiveShellConfig = {
 	handsFreeQuietThreshold: 5000,
 	handsFreeUpdateMaxChars: 1500,
 	handsFreeMaxTotalChars: 100000,
+	// Query rate limiting (default 60 seconds between queries)
+	minQueryIntervalSeconds: 60,
 };
 
 export function loadConfig(cwd: string): InteractiveShellConfig {
@@ -72,8 +76,9 @@ export function loadConfig(cwd: string): InteractiveShellConfig {
 	return {
 		...merged,
 		overlayWidthPercent: clampPercent(merged.overlayWidthPercent, DEFAULT_CONFIG.overlayWidthPercent),
-		overlayHeightPercent: clampPercent(merged.overlayHeightPercent, DEFAULT_CONFIG.overlayHeightPercent),
-		scrollbackLines: Math.max(200, merged.scrollbackLines ?? DEFAULT_CONFIG.scrollbackLines),
+		// Height: 20-90% range (default 45%)
+		overlayHeightPercent: clampInt(merged.overlayHeightPercent, DEFAULT_CONFIG.overlayHeightPercent, 20, 90),
+		scrollbackLines: clampInt(merged.scrollbackLines, DEFAULT_CONFIG.scrollbackLines, 200, 50000),
 		ansiReemit: merged.ansiReemit !== false,
 		handoffPreviewEnabled: merged.handoffPreviewEnabled !== false,
 		handoffPreviewLines: clampInt(merged.handoffPreviewLines, DEFAULT_CONFIG.handoffPreviewLines, 0, 500),
@@ -117,6 +122,13 @@ export function loadConfig(cwd: string): InteractiveShellConfig {
 			10000,
 			1000000,
 		),
+		// Query rate limiting (min 5 seconds, max 300 seconds)
+		minQueryIntervalSeconds: clampInt(
+			merged.minQueryIntervalSeconds,
+			DEFAULT_CONFIG.minQueryIntervalSeconds,
+			5,
+			300,
+		),
 	};
 }
 

package/index.ts

@@ -312,10 +312,17 @@ The user sees the overlay and can:
 - Kill/background via double-Escape
 
 QUERYING SESSION STATUS:
-- interactive_shell({ sessionId: "calm-reef" }) - get status + new output
+- interactive_shell({ sessionId: "calm-reef" }) - get status + rendered terminal output (last 20 lines)
 - interactive_shell({ sessionId: "calm-reef", kill: true }) - end session
 - interactive_shell({ sessionId: "calm-reef", input: "..." }) - send input
 
+IMPORTANT: Don't query too frequently! Wait 30-60 seconds between status checks.
+The user is watching the overlay in real-time - you're just checking in periodically.
+
+RATE LIMITING:
+Queries are limited to once every 60 seconds (configurable). If you query too soon,
+the tool will automatically wait until the limit expires before returning.
+
 SENDING INPUT:
 - interactive_shell({ sessionId: "calm-reef", input: "/help\\n" })
 - interactive_shell({ sessionId: "calm-reef", input: { keys: ["ctrl+c"] } })
@@ -434,7 +441,7 @@ Examples:
 					),
 					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.",
+							description: "Auto-kill session when output stops (after quietThreshold). Defaults to true in hands-free mode. Set to false to keep session alive indefinitely.",
 						}),
 					),
 				}),
@@ -513,7 +520,7 @@ Examples:
 
 				// Kill session if requested
 				if (kill) {
-					const { output, truncated, totalBytes } = session.getOutput();
+					const { output, truncated, totalBytes } = session.getOutput(true); // skipRateLimit=true for kill
 					const status = session.getStatus();
 					const runtime = session.getRuntime();
 					session.kill();
@@ -589,16 +596,17 @@ Examples:
 
 				// 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 session completed, always allow query (no rate limiting)
+					// Rate limiting only applies to "checking in" on running sessions
 					if (result) {
+						const { output, truncated, totalBytes } = session.getOutput(true); // skipRateLimit=true
+						const truncatedNote = truncated ? ` (${totalBytes} bytes total, truncated)` : "";
+						const hasOutput = output.length > 0;
+
 						sessionManager.unregisterActive(sessionId, true);
 						return {
 							content: [
@@ -621,11 +629,138 @@ Examples:
 						};
 					}
 
+					// Session still running - check rate limiting
+					const outputResult = session.getOutput();
+
+					// If rate limited, wait until allowed then return fresh result
+					// Use Promise.race to detect if session completes during wait
+					if (outputResult.rateLimited && outputResult.waitSeconds) {
+						const waitMs = outputResult.waitSeconds * 1000;
+						
+						// Race: rate limit timeout vs session completion
+						const completedEarly = await Promise.race([
+							new Promise<false>((resolve) => setTimeout(() => resolve(false), waitMs)),
+							new Promise<true>((resolve) => session.onComplete(() => resolve(true))),
+						]);
+						
+						// If session completed during wait, return result immediately
+						if (completedEarly) {
+							const earlySession = sessionManager.getActive(sessionId);
+							if (!earlySession) {
+								return {
+									content: [{ type: "text", text: `Session ${sessionId} ended` }],
+									details: { sessionId, status: "ended" },
+								};
+							}
+							const earlyResult = earlySession.getResult();
+							const { output, truncated, totalBytes } = earlySession.getOutput(true); // skipRateLimit
+							const earlyStatus = earlySession.getStatus();
+							const earlyRuntime = earlySession.getRuntime();
+							const truncatedNote = truncated ? ` (${totalBytes} bytes total, truncated)` : "";
+							const hasOutput = output.length > 0;
+							
+							if (earlyResult) {
+								sessionManager.unregisterActive(sessionId, true);
+								return {
+									content: [
+										{
+											type: "text",
+											text: `Session ${sessionId} ${earlyStatus} after ${formatDurationMs(earlyRuntime)}${hasOutput ? `\n\nOutput${truncatedNote}:\n${output}` : ""}`,
+										},
+									],
+									details: {
+										sessionId,
+										status: earlyStatus,
+										runtime: earlyRuntime,
+										output,
+										outputTruncated: truncated,
+										outputTotalBytes: totalBytes,
+										exitCode: earlyResult.exitCode,
+										signal: earlyResult.signal,
+										backgroundId: earlyResult.backgroundId,
+									},
+								};
+							}
+							// Edge case: onComplete fired but no result yet (shouldn't happen)
+							// Return current status without unregistering
+							return {
+								content: [
+									{
+										type: "text",
+										text: `Session ${sessionId} ${earlyStatus} (${formatDurationMs(earlyRuntime)})${hasOutput ? `\n\nOutput${truncatedNote}:\n${output}` : ""}`,
+									},
+								],
+								details: {
+									sessionId,
+									status: earlyStatus,
+									runtime: earlyRuntime,
+									output,
+									outputTruncated: truncated,
+									outputTotalBytes: totalBytes,
+									hasOutput,
+								},
+							};
+						}
+						// Get fresh output after waiting
+						const freshOutput = session.getOutput();
+						const truncatedNote = freshOutput.truncated ? ` (${freshOutput.totalBytes} bytes total, truncated)` : "";
+						const hasOutput = freshOutput.output.length > 0;
+						const freshStatus = session.getStatus();
+						const freshRuntime = session.getRuntime();
+						const freshResult = session.getResult();
+
+						if (freshResult) {
+							sessionManager.unregisterActive(sessionId, true);
+							return {
+								content: [
+									{
+										type: "text",
+										text: `Session ${sessionId} ${freshStatus} after ${formatDurationMs(freshRuntime)}${hasOutput ? `\n\nOutput${truncatedNote}:\n${freshOutput.output}` : ""}`,
+									},
+								],
+								details: {
+									sessionId,
+									status: freshStatus,
+									runtime: freshRuntime,
+									output: freshOutput.output,
+									outputTruncated: freshOutput.truncated,
+									outputTotalBytes: freshOutput.totalBytes,
+									exitCode: freshResult.exitCode,
+									signal: freshResult.signal,
+									backgroundId: freshResult.backgroundId,
+								},
+							};
+						}
+
+						return {
+							content: [
+								{
+									type: "text",
+									text: `Session ${sessionId} ${freshStatus} (${formatDurationMs(freshRuntime)})${hasOutput ? `\n\nOutput${truncatedNote}:\n${freshOutput.output}` : ""}`,
+								},
+							],
+							details: {
+								sessionId,
+								status: freshStatus,
+								runtime: freshRuntime,
+								output: freshOutput.output,
+								outputTruncated: freshOutput.truncated,
+								outputTotalBytes: freshOutput.totalBytes,
+								hasOutput,
+							},
+						};
+					}
+
+					const { output, truncated, totalBytes } = outputResult;
+
+					const truncatedNote = truncated ? ` (${totalBytes} bytes total, truncated)` : "";
+					const hasOutput = output.length > 0;
+
 					return {
 						content: [
 							{
 								type: "text",
-								text: `Session ${sessionId} ${status} (${formatDurationMs(runtime)})${hasOutput ? `\n\nNew output${truncatedNote}:\n${output}` : "\n\n(no new output)"}`,
+								text: `Session ${sessionId} ${status} (${formatDurationMs(runtime)})${hasOutput ? `\n\nOutput${truncatedNote}:\n${output}` : ""}`,
 							},
 						],
 						details: {
@@ -635,7 +770,7 @@ Examples:
 							output,
 							outputTruncated: truncated,
 							outputTotalBytes: totalBytes,
-							hasNewOutput: hasOutput,
+							hasOutput,
 						},
 					};
 				}
@@ -696,7 +831,8 @@ Examples:
 								handsFreeQuietThreshold: handsFree?.quietThreshold,
 								handsFreeUpdateMaxChars: handsFree?.updateMaxChars,
 								handsFreeMaxTotalChars: handsFree?.maxTotalChars,
-								autoExitOnQuiet: handsFree?.autoExitOnQuiet,
+								// Default autoExitOnQuiet to true in hands-free mode
+								autoExitOnQuiet: handsFree?.autoExitOnQuiet !== false,
 								// No onHandsFreeUpdate in non-blocking mode - agent queries directly
 								handoffPreviewEnabled: handoffPreview?.enabled,
 								handoffPreviewLines: handoffPreview?.lines,

package/overlay-component.ts

@@ -122,9 +122,12 @@ 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
+	// Non-blocking mode: track status for agent queries
 	private completionResult: InteractiveShellResult | undefined;
+	// Rate limiting for queries
+	private lastQueryTime = 0;
+	// Completion callbacks for waiters
+	private completeCallbacks: Array<() => void> = [];
 
 	constructor(
 		tui: TUI,
@@ -222,12 +225,13 @@ export class InteractiveShellOverlay implements Component, Focusable {
 				reason: options.reason,
 				write: (data) => this.session.write(data),
 				kill: () => this.killSession(),
-				getOutput: () => this.getOutputSinceLastCheck(),
+				getOutput: (skipRateLimit) => this.getOutputSinceLastCheck(skipRateLimit),
 				getStatus: () => this.getSessionStatus(),
 				getRuntime: () => this.getRuntime(),
 				getResult: () => this.getCompletionResult(),
 				setUpdateInterval: (intervalMs) => this.setUpdateInterval(intervalMs),
 				setQuietThreshold: (thresholdMs) => this.setQuietThreshold(thresholdMs),
+				onComplete: (callback) => this.registerCompleteCallback(callback),
 			});
 			this.startHandsFreeUpdates();
 		}
@@ -242,33 +246,47 @@ 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,
-			};
+	// Max output per status query (5KB) - prevents overwhelming agent context
+	private static readonly MAX_STATUS_OUTPUT = 5 * 1024;
+	// Max lines to return per query - keep small, we're just checking in
+	private static readonly MAX_STATUS_LINES = 20;
+
+	/** Get rendered terminal output (last N lines, truncated if too large) */
+	getOutputSinceLastCheck(skipRateLimit = false): { output: string; truncated: boolean; totalBytes: number; rateLimited?: boolean; waitSeconds?: number } {
+		// Check rate limiting (unless skipped, e.g., for completed sessions)
+		if (!skipRateLimit) {
+			const now = Date.now();
+			const minIntervalMs = this.config.minQueryIntervalSeconds * 1000;
+			const elapsed = now - this.lastQueryTime;
+
+			if (this.lastQueryTime > 0 && elapsed < minIntervalMs) {
+				const waitSeconds = Math.ceil((minIntervalMs - elapsed) / 1000);
+				return {
+					output: "",
+					truncated: false,
+					totalBytes: 0,
+					rateLimited: true,
+					waitSeconds,
+				};
+			}
+
+			// Update last query time
+			this.lastQueryTime = now;
 		}
 
-		return { output: newOutput, truncated: false, totalBytes };
+		// Use rendered terminal output instead of raw stream
+		// This gives clean, readable content without TUI animation garbage
+		const lines = this.session.getTailLines({
+			lines: InteractiveShellOverlay.MAX_STATUS_LINES,
+			ansi: false,
+			maxChars: InteractiveShellOverlay.MAX_STATUS_OUTPUT,
+		});
+
+		const output = lines.join("\n");
+		const totalBytes = output.length;
+		const truncated = lines.length >= InteractiveShellOverlay.MAX_STATUS_LINES;
+
+		return { output, truncated, totalBytes };
 	}
 
 	/** Get current session status */
@@ -294,6 +312,28 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		return this.completionResult;
 	}
 
+	/** Register a callback to be called when session completes */
+	registerCompleteCallback(callback: () => void): void {
+		// If already completed, call immediately
+		if (this.completionResult) {
+			callback();
+			return;
+		}
+		this.completeCallbacks.push(callback);
+	}
+
+	/** Trigger all completion callbacks */
+	private triggerCompleteCallbacks(): void {
+		for (const callback of this.completeCallbacks) {
+			try {
+				callback();
+			} catch {
+				// Ignore errors in callbacks
+			}
+		}
+		this.completeCallbacks = [];
+	}
+
 	/** Get the session ID */
 	getSessionId(): string | null {
 		return this.sessionId;
@@ -366,9 +406,10 @@ export class InteractiveShellOverlay implements Component, Focusable {
 						this.hasUnsentData = false;
 					}
 					// Send completion notification and auto-close
+					// Use "killed" status since we're forcibly terminating (matches finishWithKill's cancelled=true)
 					if (this.options.onHandsFreeUpdate && this.sessionId) {
 						this.options.onHandsFreeUpdate({
-							status: "exited",
+							status: "killed",
 							sessionId: this.sessionId,
 							runtime: Date.now() - this.startTime,
 							tail: [],
@@ -639,6 +680,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			handoff,
 		};
 		this.completionResult = result;
+		this.triggerCompleteCallbacks();
 
 		// In non-blocking mode (no onHandsFreeUpdate), keep session registered
 		// so agent can query completion result. Agent's query will unregister.
@@ -671,6 +713,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			handoff,
 		};
 		this.completionResult = result;
+		this.triggerCompleteCallbacks();
 
 		// In non-blocking mode (no onHandsFreeUpdate), keep session registered
 		// so agent can query completion result. Agent's query will unregister.
@@ -702,6 +745,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			handoff,
 		};
 		this.completionResult = result;
+		this.triggerCompleteCallbacks();
 
 		// In non-blocking mode (no onHandsFreeUpdate), keep session registered
 		// so agent can query completion result. Agent's query will unregister.
@@ -754,6 +798,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			handoff,
 		};
 		this.completionResult = result;
+		this.triggerCompleteCallbacks();
 
 		// In non-blocking mode (no onHandsFreeUpdate), keep session registered
 		// so agent can query completion result. Agent's query will unregister.
@@ -978,10 +1023,16 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.stopTimeout();
 		this.stopHandsFreeUpdates();
 		// Safety cleanup in case dispose() is called without going through finishWith*
-		// In non-blocking mode with completion result, keep session so agent can query
-		if (!this.completionResult || this.options.onHandsFreeUpdate) {
+		// If session hasn't completed yet, kill it to prevent orphaned processes
+		if (!this.completionResult) {
+			this.session.kill();
+			this.session.dispose();
+			this.unregisterActiveSession();
+		} else if (this.options.onHandsFreeUpdate) {
+			// Streaming mode already delivered result, safe to unregister
 			this.unregisterActiveSession();
 		}
+		// Non-blocking mode with completion: keep registered so agent can query
 	}
 }
 

package/package.json

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

package/session-manager.ts

@@ -24,6 +24,9 @@ export interface OutputResult {
 	output: string;
 	truncated: boolean;
 	totalBytes: number;
+	// Rate limiting
+	rateLimited?: boolean;
+	waitSeconds?: number;
 }
 
 export interface ActiveSession {
@@ -32,12 +35,13 @@ export interface ActiveSession {
 	reason?: string;
 	write: (data: string) => void;
 	kill: () => void;
-	getOutput: () => OutputResult; // Get output since last check (truncated if large)
+	getOutput: (skipRateLimit?: boolean) => 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;
+	onComplete: (callback: () => void) => void; // Register callback for when session completes
 	startedAt: Date;
 }
 
@@ -129,12 +133,13 @@ export class ShellSessionManager {
 		reason?: string;
 		write: (data: string) => void;
 		kill: () => void;
-		getOutput: () => OutputResult;
+		getOutput: (skipRateLimit?: boolean) => OutputResult;
 		getStatus: () => ActiveSessionStatus;
 		getRuntime: () => number;
 		getResult: () => ActiveSessionResult | undefined;
 		setUpdateInterval?: (intervalMs: number) => void;
 		setQuietThreshold?: (thresholdMs: number) => void;
+		onComplete: (callback: () => void) => void;
 	}): void {
 		this.activeSessions.set(session.id, {
 			...session,
@@ -259,13 +264,15 @@ export class ShellSessionManager {
 		for (const [id, session] of activeEntries) {
 			try {
 				session.kill();
+				// Only release ID if kill succeeded - let natural cleanup handle failures
+				// The session's exit handler will call unregisterActive() which releases the ID
 			} catch {
-				// Session may already be dead
+				// Session may already be dead - still safe to release since no process running
+				releaseSessionId(id);
 			}
-			// Release ID if not already released by kill()
-			releaseSessionId(id);
 		}
-		this.activeSessions.clear();
+		// Don't clear immediately - let unregisterActive() handle cleanup as sessions exit
+		// This prevents ID reuse while processes are still terminating
 	}
 }