pi-interactive-shell 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to the `pi-interactive-shell` extension will be documented in this file.
 
+## [0.4.3] - 2026-01-18
+
+### Added
+- **Configurable output limits** - New `outputLines` and `outputMaxChars` parameters when querying sessions:
+  - `outputLines`: Request more lines (default: 20, max: 200)
+  - `outputMaxChars`: Request more content (default: 5KB, max: 50KB)
+  - Example: `interactive_shell({ sessionId: "calm-reef", outputLines: 50 })`
+- **Escape hint feedback** - After pressing first Escape, shows "Press Escape again to detach..." in footer for 300ms
+
+### Fixed
+- **Escape hint not showing** - Fixed bug where `clearEscapeHint()` was immediately resetting `showEscapeHint` to false after setting it to true
+- **Negative output limits** - Added clamping to ensure `outputLines` and `outputMaxChars` are at least 1
+- **Reduced flickering during rapid output** - Three improvements:
+  1. Scroll position calculated at render time via `followBottom` flag (not on each data event)
+  2. Debounced render requests (16ms) to batch rapid updates before drawing
+  3. Explicit scroll-to-bottom after resize to prevent flash to top during dimension changes
+
+## [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

package/README.md

@@ -55,6 +55,12 @@ This installs the extension to `~/.pi/agent/extensions/interactive-shell/`, runs
 - `sessionId` (string, required): session ID
 - `settings` (object): `{ updateInterval?, quietThreshold? }`
 
+**Query session status:**
+- `sessionId` (string, required): session ID
+- `outputLines` (number): lines to return (default: 20, max: 200)
+- `outputMaxChars` (number): max chars to return (default: 5KB, max: 50KB)
+- `kill` (boolean): kill the session and return final output
+
 ### Command: `/attach`
 
 Reattach to background sessions:
@@ -146,7 +152,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

@@ -5,7 +5,7 @@ description: Cheat sheet + workflow for launching interactive coding-agent CLIs
 
 # Interactive Shell (Skill)
 
-Last verified: 2026-01-17
+Last verified: 2026-01-18
 
 ## Foreground vs Background Subagents
 
@@ -113,7 +113,7 @@ Returns:
 - `output`: Last 20 lines of rendered terminal (clean, no TUI animation noise)
 - `runtime`: Time elapsed in ms
 
-**Don't query too frequently!** Wait 30-60 seconds between checks. The user is watching the overlay in real-time - you're just checking in periodically to see progress.
+**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
@@ -122,6 +122,22 @@ 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 (default: enabled):** In hands-free mode, sessions auto-kill when output stops (after ~5 seconds of quiet). This means when an agent finishes its task and returns to its prompt, the session closes automatically.
+
+Since sessions auto-close, **always instruct the subagent to save results to a file** so you can read them:
+
+```typescript
+interactive_shell({
+  command: 'pi "Review this codebase for security issues. Save your findings to /tmp/security-review.md"',
+  mode: "hands-free",
+  reason: "Security review"
+})
+// After session ends, read the results:
+// read("/tmp/security-review.md")
+```
+
+To disable auto-exit (for long-running tasks or when you need to review output): `handsFree: { autoExitOnQuiet: false }`
+
 ### Sending Input
 ```typescript
 interactive_shell({ sessionId: "calm-reef", input: "/help\n" })
@@ -131,18 +147,38 @@ interactive_shell({ sessionId: "calm-reef", input: { keys: ["ctrl+c"] } })
 ### Query Output
 
 Status queries return **rendered terminal output** (what's actually on screen), not raw stream:
-- Last 20 lines of the terminal, clean and readable
+- Default: 20 lines, 5KB max per query
 - No TUI animation noise (spinners, progress bars, etc.)
-- Max 5KB per query to keep context manageable
-- Configure via `handsFree.maxTotalChars`
+- Configurable via `outputLines` (max: 200) and `outputMaxChars` (max: 50KB)
+
+```typescript
+// Get more output when reviewing a session
+interactive_shell({ sessionId: "calm-reef", outputLines: 50 })
+
+// Get even more for detailed review
+interactive_shell({ sessionId: "calm-reef", outputLines: 100, outputMaxChars: 30000 })
+```
+
+### Reviewing Long Sessions (autoExitOnQuiet disabled)
+
+When you disable auto-exit for long-running tasks, progressively review more output as needed:
 
 ```typescript
-// Custom budget for a long task
+// Start a long session without auto-exit
 interactive_shell({
   command: 'pi "Refactor entire codebase"',
   mode: "hands-free",
-  handsFree: { maxTotalChars: 200000 }  // 200KB budget
+  handsFree: { autoExitOnQuiet: false }
 })
+
+// Query returns last 20 lines by default
+interactive_shell({ sessionId: "calm-reef" })
+
+// Get more lines when you need more context
+interactive_shell({ sessionId: "calm-reef", outputLines: 50 })
+
+// Get even more for detailed review
+interactive_shell({ sessionId: "calm-reef", outputLines: 100, outputMaxChars: 30000 })
 ```
 
 ## Sending Input to Active Sessions
@@ -242,49 +278,17 @@ interactive_shell({ sessionId: "calm-reef", settings: { quietThreshold: 3000 } }
 interactive_shell({ sessionId: "calm-reef", settings: { updateInterval: 30000, quietThreshold: 2000 } })
 ```
 
-## CLI Cheat Sheet
-
-### Claude Code (`claude`)
-
-| Mode | Command |
-|------|---------|
-| Interactive (idle) | `claude` |
-| Interactive (prompted) | `claude "Explain this project"` |
-| Headless (use bash, not overlay) | `claude -p "Explain this function"` |
-
-### Gemini CLI (`gemini`)
-
-| Mode | Command |
-|------|---------|
-| Interactive (idle) | `gemini` |
-| Interactive (prompted) | `gemini -i "Explain this codebase"` |
-| Headless (use bash, not overlay) | `gemini -p "What is fine tuning?"` |
-
-### Codex CLI (`codex`)
-
-| Mode | Command |
-|------|---------|
-| Interactive (idle) | `codex` |
-| Interactive (prompted) | `codex "Explain this codebase"` |
-| Headless (use bash, not overlay) | `codex exec "summarize the repo"` |
-
-### Cursor CLI (`cursor-agent`)
-
-| Mode | Command |
-|------|---------|
-| Interactive (idle) | `cursor-agent` |
-| Interactive (prompted) | `cursor-agent "review this repo"` |
-| Headless (use bash, not overlay) | `cursor-agent -p "find issues" --output-format text` |
-
-### Pi (`pi`)
+## CLI Quick Reference
 
-| Mode | Command |
-|------|---------|
-| Interactive (idle) | `pi` |
-| Interactive (prompted) | `pi "List all .ts files"` |
-| Headless (use bash, not overlay) | `pi -p "List all .ts files"` |
+| Agent | Interactive | With Prompt | Headless (bash) |
+|-------|-------------|-------------|-----------------|
+| `claude` | `claude` | `claude "prompt"` | `claude -p "prompt"` |
+| `gemini` | `gemini` | `gemini -i "prompt"` | `gemini "prompt"` |
+| `codex` | `codex` | `codex "prompt"` | `codex exec "prompt"` |
+| `agent` | `agent` | `agent "prompt"` | `agent -p "prompt"` |
+| `pi` | `pi` | `pi "prompt"` | `pi -p "prompt"` |
 
-Note: Delegating pi to pi is recursive - usually prefer `subagent` for pi-to-pi delegation.
+**Gemini model:** `gemini -m gemini-3-flash-preview -i "prompt"`
 
 ## Prompt Packaging Rules
 

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,13 +312,19 @@ The user sees the overlay and can:
 - Kill/background via double-Escape
 
 QUERYING SESSION STATUS:
-- interactive_shell({ sessionId: "calm-reef" }) - get status + rendered terminal output (last 20 lines)
+- interactive_shell({ sessionId: "calm-reef" }) - get status + rendered terminal output (default: 20 lines, 5KB)
+- interactive_shell({ sessionId: "calm-reef", outputLines: 50 }) - get more lines (max: 200)
+- interactive_shell({ sessionId: "calm-reef", outputMaxChars: 20000 }) - get more content (max: 50KB)
 - 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"] } })
@@ -358,6 +364,16 @@ Examples:
 					description: "Kill the session (requires sessionId). Use when task appears complete.",
 				}),
 			),
+			outputLines: Type.Optional(
+				Type.Number({
+					description: "Number of lines to return when querying (default: 20, max: 200)",
+				}),
+			),
+			outputMaxChars: Type.Optional(
+				Type.Number({
+					description: "Max chars to return when querying (default: 5KB, max: 50KB)",
+				}),
+			),
 			settings: Type.Optional(
 				Type.Object({
 					updateInterval: Type.Optional(
@@ -437,7 +453,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.",
 						}),
 					),
 				}),
@@ -470,6 +486,8 @@ Examples:
 				command,
 				sessionId,
 				kill,
+				outputLines,
+				outputMaxChars,
 				settings,
 				input,
 				cwd,
@@ -484,6 +502,8 @@ Examples:
 				command?: string;
 				sessionId?: string;
 				kill?: boolean;
+				outputLines?: number;
+				outputMaxChars?: number;
 				settings?: { updateInterval?: number; quietThreshold?: number };
 				input?: string | { text?: string; keys?: string[]; hex?: string[]; paste?: string };
 				cwd?: string;
@@ -516,7 +536,7 @@ Examples:
 
 				// Kill session if requested
 				if (kill) {
-					const { output, truncated, totalBytes } = session.getOutput();
+					const { output, truncated, totalBytes } = session.getOutput({ skipRateLimit: true, lines: outputLines, maxChars: outputMaxChars });
 					const status = session.getStatus();
 					const runtime = session.getRuntime();
 					session.kill();
@@ -592,16 +612,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({ skipRateLimit: true, lines: outputLines, maxChars: outputMaxChars });
+						const truncatedNote = truncated ? ` (${totalBytes} bytes total, truncated)` : "";
+						const hasOutput = output.length > 0;
+
 						sessionManager.unregisterActive(sessionId, true);
 						return {
 							content: [
@@ -624,11 +645,138 @@ Examples:
 						};
 					}
 
+					// Session still running - check rate limiting
+					const outputResult = session.getOutput({ lines: outputLines, maxChars: outputMaxChars });
+
+					// 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({ skipRateLimit: true, lines: outputLines, maxChars: outputMaxChars });
+							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({ lines: outputLines, maxChars: outputMaxChars });
+						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: {
@@ -638,7 +786,7 @@ Examples:
 							output,
 							outputTruncated: truncated,
 							outputTotalBytes: totalBytes,
-							hasNewOutput: hasOutput,
+							hasOutput,
 						},
 					};
 				}
@@ -699,7 +847,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

@@ -98,6 +98,8 @@ export class InteractiveShellOverlay implements Component, Focusable {
 	private dialogSelection: DialogChoice = "background";
 	private exitCountdown = 0;
 	private lastEscapeTime = 0;
+	private showEscapeHint = false;
+	private escapeHintTimeout: ReturnType<typeof setTimeout> | null = null;
 	private countdownInterval: ReturnType<typeof setInterval> | null = null;
 	private lastWidth = 0;
 	private lastHeight = 0;
@@ -124,6 +126,12 @@ export class InteractiveShellOverlay implements Component, Focusable {
 	private hasUnsentData = false;
 	// 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> = [];
+	// Simple render throttle to reduce flicker
+	private renderTimeout: ReturnType<typeof setTimeout> | null = null;
 
 	constructor(
 		tui: TUI,
@@ -154,10 +162,9 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			},
 			{
 				onData: () => {
-					if (!this.session.isScrolledUp()) {
-						this.session.scrollToBottom();
-					}
-					this.tui.requestRender();
+					// Don't call scrollToBottom() here - pty-session handles auto-follow at render time
+					// Debounce render to batch rapid updates and reduce flicker
+					this.debouncedRender();
 
 					// Track activity for on-quiet mode
 					if (this.state === "hands-free" && this.updateMode === "on-quiet") {
@@ -221,12 +228,13 @@ export class InteractiveShellOverlay implements Component, Focusable {
 				reason: options.reason,
 				write: (data) => this.session.write(data),
 				kill: () => this.killSession(),
-				getOutput: () => this.getOutputSinceLastCheck(),
+				getOutput: (options) => this.getOutputSinceLastCheck(options),
 				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();
 		}
@@ -241,24 +249,59 @@ export class InteractiveShellOverlay implements Component, Focusable {
 
 	// Public methods for non-blocking mode (agent queries)
 
-	// 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;
+	// Default output limits per status query
+	private static readonly DEFAULT_STATUS_OUTPUT = 5 * 1024; // 5KB
+	private static readonly DEFAULT_STATUS_LINES = 20;
+	private static readonly MAX_STATUS_OUTPUT = 50 * 1024; // 50KB max
+	private static readonly MAX_STATUS_LINES = 200; // 200 lines max
 
 	/** Get rendered terminal output (last N lines, truncated if too large) */
-	getOutputSinceLastCheck(): { output: string; truncated: boolean; totalBytes: number } {
+	getOutputSinceLastCheck(options: { skipRateLimit?: boolean; lines?: number; maxChars?: number } | boolean = false): { output: string; truncated: boolean; totalBytes: number; rateLimited?: boolean; waitSeconds?: number } {
+		// Handle legacy boolean parameter
+		const opts = typeof options === "boolean" ? { skipRateLimit: options } : options;
+		const skipRateLimit = opts.skipRateLimit ?? false;
+		// Clamp lines and maxChars to valid ranges (1 to MAX)
+		const requestedLines = Math.max(1, Math.min(
+			opts.lines ?? InteractiveShellOverlay.DEFAULT_STATUS_LINES,
+			InteractiveShellOverlay.MAX_STATUS_LINES
+		));
+		const requestedMaxChars = Math.max(1, Math.min(
+			opts.maxChars ?? InteractiveShellOverlay.DEFAULT_STATUS_OUTPUT,
+			InteractiveShellOverlay.MAX_STATUS_OUTPUT
+		));
+
+		// 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;
+		}
+
 		// 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,
+			lines: requestedLines,
 			ansi: false,
-			maxChars: InteractiveShellOverlay.MAX_STATUS_OUTPUT,
+			maxChars: requestedMaxChars,
 		});
 
 		const output = lines.join("\n");
 		const totalBytes = output.length;
-		const truncated = lines.length >= InteractiveShellOverlay.MAX_STATUS_LINES;
+		const truncated = lines.length >= requestedLines;
 
 		return { output, truncated, totalBytes };
 	}
@@ -286,6 +329,40 @@ 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 = [];
+	}
+
+	/** Debounced render - waits for data to settle before rendering */
+	private debouncedRender(): void {
+		if (this.renderTimeout) {
+			clearTimeout(this.renderTimeout);
+		}
+		// Wait 16ms for more data before rendering
+		this.renderTimeout = setTimeout(() => {
+			this.renderTimeout = null;
+			this.tui.requestRender();
+		}, 16);
+	}
+
 	/** Get the session ID */
 	getSessionId(): string | null {
 		return this.sessionId;
@@ -358,9 +435,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: [],
@@ -631,6 +709,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.
@@ -663,6 +742,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.
@@ -694,6 +774,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.
@@ -746,6 +827,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.
@@ -760,12 +842,31 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		const now = Date.now();
 		if (now - this.lastEscapeTime < this.config.doubleEscapeThreshold) {
 			this.lastEscapeTime = 0;
+			this.clearEscapeHint();
 			return true;
 		}
 		this.lastEscapeTime = now;
+		// Show hint after first escape - clear any existing timeout first
+		if (this.escapeHintTimeout) {
+			clearTimeout(this.escapeHintTimeout);
+		}
+		this.showEscapeHint = true;
+		this.escapeHintTimeout = setTimeout(() => {
+			this.showEscapeHint = false;
+			this.tui.requestRender();
+		}, this.config.doubleEscapeThreshold);
+		this.tui.requestRender();
 		return false;
 	}
 
+	private clearEscapeHint(): void {
+		if (this.escapeHintTimeout) {
+			clearTimeout(this.escapeHintTimeout);
+			this.escapeHintTimeout = null;
+		}
+		this.showEscapeHint = false;
+	}
+
 	handleInput(data: string): void {
 		if (this.state === "detach-dialog") {
 			this.handleDialogInput(data);
@@ -900,6 +1001,8 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			this.session.resize(innerWidth, termRows);
 			this.lastWidth = innerWidth;
 			this.lastHeight = termRows;
+			// After resize, ensure we're at the bottom to prevent flash to top
+			this.session.scrollToBottom();
 		}
 
 		const viewportLines = this.session.getViewportLines({ ansi: this.config.ansiReemit });
@@ -945,9 +1048,17 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			footerLines.push(row(exitMsg));
 			footerLines.push(row(dim(`Closing in ${this.exitCountdown}s... (any key to close)`)));
 		} else if (this.state === "hands-free") {
-			footerLines.push(row(dim("🤖 Agent controlling • Type to take over • Shift+Up/Down scroll")));
+			if (this.showEscapeHint) {
+				footerLines.push(row(warning("Press Escape again to detach...")));
+			} else {
+				footerLines.push(row(dim("🤖 Agent controlling • Type to take over • Shift+Up/Down scroll")));
+			}
 		} else {
-			footerLines.push(row(dim("Shift+Up/Down scroll • Double-Esc detach • Ctrl+C interrupt")));
+			if (this.showEscapeHint) {
+				footerLines.push(row(warning("Press Escape again to detach...")));
+			} else {
+				footerLines.push(row(dim("Shift+Up/Down scroll • Double-Esc detach • Ctrl+C interrupt")));
+			}
 		}
 
 		while (footerLines.length < FOOTER_LINES) {
@@ -969,11 +1080,22 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.stopCountdown();
 		this.stopTimeout();
 		this.stopHandsFreeUpdates();
+		this.clearEscapeHint();
+		if (this.renderTimeout) {
+			clearTimeout(this.renderTimeout);
+			this.renderTimeout = null;
+		}
 		// 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
 	}
 }
 
@@ -1309,6 +1431,8 @@ export class ReattachOverlay implements Component, Focusable {
 			this.session.resize(innerWidth, termRows);
 			this.lastWidth = innerWidth;
 			this.lastHeight = termRows;
+			// After resize, ensure we're at the bottom to prevent flash to top
+			this.session.scrollToBottom();
 		}
 
 		const viewportLines = this.session.getViewportLines({ ansi: this.config.ansiReemit });

package/package.json

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

package/pty-session.ts

@@ -218,6 +218,7 @@ export class PtyTerminalSession {
 	private _exitCode: number | null = null;
 	private _signal: number | undefined;
 	private scrollOffset = 0;
+	private followBottom = true; // Auto-scroll to bottom when new data arrives
 
 	// Raw output buffer for incremental streaming
 	private rawOutput = "";
@@ -458,6 +459,11 @@ export class PtyTerminalSession {
 		const lines: string[] = [];
 
 		const totalLines = buffer.length;
+		// If following bottom, reset scroll offset at render time (not on each data event)
+		// This prevents flickering from scroll position racing with buffer updates
+		if (this.followBottom) {
+			this.scrollOffset = 0;
+		}
 		const viewportStart = Math.max(0, totalLines - this.xterm.rows - this.scrollOffset);
 
 		const useAnsi = !!options.ansi;
@@ -565,14 +571,20 @@ export class PtyTerminalSession {
 		const buffer = this.xterm.buffer.active;
 		const maxScroll = Math.max(0, buffer.length - this.xterm.rows);
 		this.scrollOffset = Math.min(this.scrollOffset + lines, maxScroll);
+		this.followBottom = false; // User scrolled up, stop auto-following
 	}
 
 	scrollDown(lines: number): void {
 		this.scrollOffset = Math.max(0, this.scrollOffset - lines);
+		// If scrolled to bottom, resume auto-following
+		if (this.scrollOffset === 0) {
+			this.followBottom = true;
+		}
 	}
 
 	scrollToBottom(): void {
 		this.scrollOffset = 0;
+		this.followBottom = true;
 	}
 
 	isScrolledUp(): boolean {

package/session-manager.ts

@@ -24,6 +24,15 @@ export interface OutputResult {
 	output: string;
 	truncated: boolean;
 	totalBytes: number;
+	// Rate limiting
+	rateLimited?: boolean;
+	waitSeconds?: number;
+}
+
+export interface OutputOptions {
+	skipRateLimit?: boolean;
+	lines?: number; // Override default 20 lines
+	maxChars?: number; // Override default 5KB
 }
 
 export interface ActiveSession {
@@ -32,12 +41,13 @@ export interface ActiveSession {
 	reason?: string;
 	write: (data: string) => void;
 	kill: () => void;
-	getOutput: () => OutputResult; // Get output since last check (truncated if large)
+	getOutput: (options?: OutputOptions | 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 +139,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 +270,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
 	}
 }