pi-interactive-shell 0.7.1 → 0.8.1

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to the `pi-interactive-shell` extension will be documented i
 
 ## [Unreleased]
 
+## [0.8.1] - 2026-02-08
+
+### Fixed
+- README: documented `handsFree.gracePeriod` tool parameter and startup grace period behavior in Auto-Exit on Quiet and Dispatch sections.
+- README: added missing `handoffPreviewLines` and `handoffPreviewMaxChars` to config settings table.
+
+## [0.8.0] - 2026-02-08
+
+### Added
+- `autoExitGracePeriod` config option (default: 30000ms, clamped 5000-120000ms) and `handsFree.gracePeriod` tool parameter override for startup quiet-kill grace control.
+
+### Changed
+- Default `overlayHeightPercent` increased from 45 to 60 for improved usable terminal rows on smaller displays.
+- Overlay sizing now uses dynamic footer chrome: compact 2-line footer in normal states and full 6-line footer in detach dialog, increasing terminal viewport height during normal operation.
+
+### Fixed
+- Dispatch/hands-free `autoExitOnQuiet` no longer kills sessions during startup silence; quiet timer now re-arms during grace period and applies auto-kill only after grace expires.
+- README config table missing `handoffPreviewLines` and `handoffPreviewMaxChars` entries despite appearing in the JSON example.
+
 ## [0.7.1] - 2026-02-03
 
 ### Changed
@@ -290,4 +309,3 @@ interactive_shell({ sessionId: "abc", input: "y", inputKeys: ["enter"] })
 ### Fixed
 - Prevented TUI width crashes by avoiding unbounded terminal escape rendering.
 - Reduced flicker by sanitizing/redrawing in a controlled overlay viewport.
-

package/README.md

@@ -115,7 +115,7 @@ Attach to review full output: interactive_shell({ attach: "calm-reef" })
 
 The notification includes a brief tail (last 5 lines) and a reattach instruction. The PTY is preserved for 5 minutes so the agent can attach to review full scrollback.
 
-Dispatch defaults `autoExitOnQuiet: true` — the session is killed after output goes silent (5s by default), which signals completion for task-oriented subagents. Opt out with `handsFree: { autoExitOnQuiet: false }` for long-running processes.
+Dispatch defaults `autoExitOnQuiet: true` — the session gets a 30s startup grace period, then is killed after output goes silent (5s by default), which signals completion for task-oriented subagents. Tune the grace period with `handsFree: { gracePeriod: 60000 }` or opt out entirely with `handsFree: { autoExitOnQuiet: false }`.
 
 The overlay still shows for the user, who can Ctrl+T to transfer output, Ctrl+B to background, take over by typing, or Ctrl+Q for more options.
 
@@ -161,6 +161,18 @@ interactive_shell({
 })
 ```
 
+A 30s startup grace period prevents the session from being killed before the subprocess has time to produce output. Customize it per-call with `gracePeriod`:
+
+```typescript
+interactive_shell({
+  command: 'pi "Run the full test suite"',
+  mode: "hands-free",
+  handsFree: { autoExitOnQuiet: true, gracePeriod: 60000 }
+})
+```
+
+The default grace period is also configurable globally via `autoExitGracePeriod` in the config file.
+
 For multi-turn sessions where you need back-and-forth interaction, leave it disabled (default) and use `kill: true` when done.
 
 ### Send Input
@@ -260,7 +272,7 @@ Configuration files (project overrides global):
 ```json
 {
   "overlayWidthPercent": 95,
-  "overlayHeightPercent": 45,
+  "overlayHeightPercent": 60,
   "scrollbackLines": 5000,
   "exitAutoCloseDelay": 10,
   "minQueryIntervalSeconds": 60,
@@ -271,6 +283,7 @@ Configuration files (project overrides global):
   "handsFreeUpdateMode": "on-quiet",
   "handsFreeUpdateInterval": 60000,
   "handsFreeQuietThreshold": 5000,
+  "autoExitGracePeriod": 30000,
   "handsFreeUpdateMaxChars": 1500,
   "handsFreeMaxTotalChars": 100000,
   "handoffPreviewEnabled": true,
@@ -284,7 +297,7 @@ Configuration files (project overrides global):
 | Setting | Default | Description |
 |---------|---------|-------------|
 | `overlayWidthPercent` | 95 | Overlay width (10-100%) |
-| `overlayHeightPercent` | 45 | Overlay height (20-90%) |
+| `overlayHeightPercent` | 60 | Overlay height (20-90%) |
 | `scrollbackLines` | 5000 | Terminal scrollback buffer |
 | `exitAutoCloseDelay` | 10 | Seconds before auto-close after exit |
 | `minQueryIntervalSeconds` | 60 | Rate limit between agent queries |
@@ -294,10 +307,13 @@ Configuration files (project overrides global):
 | `completionNotifyMaxChars` | 5000 | Max chars in completion notification (1KB-50KB) |
 | `handsFreeUpdateMode` | "on-quiet" | "on-quiet" or "interval" |
 | `handsFreeQuietThreshold` | 5000 | Silence duration before update (ms) |
+| `autoExitGracePeriod` | 30000 | Startup grace before `autoExitOnQuiet` kill (ms) |
 | `handsFreeUpdateInterval` | 60000 | Max interval between updates (ms) |
 | `handsFreeUpdateMaxChars` | 1500 | Max chars per update |
 | `handsFreeMaxTotalChars` | 100000 | Total char budget for updates |
 | `handoffPreviewEnabled` | true | Include tail in tool result |
+| `handoffPreviewLines` | 30 | Lines in tail preview (0-500) |
+| `handoffPreviewMaxChars` | 2000 | Max chars in tail preview (0-50KB) |
 | `handoffSnapshotEnabled` | false | Write transcript on detach/exit |
 | `ansiReemit` | true | Preserve ANSI colors in output |
 

package/config.ts

@@ -24,6 +24,7 @@ export interface InteractiveShellConfig {
 	handsFreeUpdateMode: "on-quiet" | "interval";
 	handsFreeUpdateInterval: number;
 	handsFreeQuietThreshold: number;
+	autoExitGracePeriod: number;
 	handsFreeUpdateMaxChars: number;
 	handsFreeMaxTotalChars: number;
 	// Query rate limiting
@@ -33,7 +34,7 @@ export interface InteractiveShellConfig {
 const DEFAULT_CONFIG: InteractiveShellConfig = {
 	exitAutoCloseDelay: 10,
 	overlayWidthPercent: 95,
-	overlayHeightPercent: 45,
+	overlayHeightPercent: 60,
 	scrollbackLines: 5000,
 	ansiReemit: true,
 	handoffPreviewEnabled: true,
@@ -52,6 +53,7 @@ const DEFAULT_CONFIG: InteractiveShellConfig = {
 	handsFreeUpdateMode: "on-quiet" as const,
 	handsFreeUpdateInterval: 60000,
 	handsFreeQuietThreshold: 5000,
+	autoExitGracePeriod: 30000,
 	handsFreeUpdateMaxChars: 1500,
 	handsFreeMaxTotalChars: 100000,
 	// Query rate limiting (default 60 seconds between queries)
@@ -87,7 +89,7 @@ export function loadConfig(cwd: string): InteractiveShellConfig {
 		...merged,
 		exitAutoCloseDelay: clampInt(merged.exitAutoCloseDelay, DEFAULT_CONFIG.exitAutoCloseDelay, 0, 60),
 		overlayWidthPercent: clampPercent(merged.overlayWidthPercent, DEFAULT_CONFIG.overlayWidthPercent),
-		// Height: 20-90% range (default 45%)
+		// Height: 20-90% range (default 60%)
 		overlayHeightPercent: clampInt(merged.overlayHeightPercent, DEFAULT_CONFIG.overlayHeightPercent, 20, 90),
 		scrollbackLines: clampInt(merged.scrollbackLines, DEFAULT_CONFIG.scrollbackLines, 200, 50000),
 		ansiReemit: merged.ansiReemit !== false,
@@ -127,6 +129,12 @@ export function loadConfig(cwd: string): InteractiveShellConfig {
 			1000,
 			30000,
 		),
+		autoExitGracePeriod: clampInt(
+			merged.autoExitGracePeriod,
+			DEFAULT_CONFIG.autoExitGracePeriod,
+			5000,
+			120000,
+		),
 		handsFreeUpdateMaxChars: clampInt(
 			merged.handsFreeUpdateMaxChars,
 			DEFAULT_CONFIG.handsFreeUpdateMaxChars,

package/headless-monitor.ts

@@ -4,6 +4,7 @@ import type { InteractiveShellConfig } from "./config.js";
 export interface HeadlessMonitorOptions {
 	autoExitOnQuiet: boolean;
 	quietThreshold: number;
+	gracePeriod?: number;
 	timeout?: number;
 }
 
@@ -80,6 +81,11 @@ export class HeadlessDispatchMonitor {
 		this.quietTimer = setTimeout(() => {
 			this.quietTimer = null;
 			if (!this._disposed && this.options.autoExitOnQuiet) {
+				const gracePeriod = this.options.gracePeriod ?? this.config.autoExitGracePeriod;
+				if (Date.now() - this.startTime < gracePeriod) {
+					this.resetQuietTimer();
+					return;
+				}
 				this.session.kill();
 				this.handleCompletion(null, undefined, false, true);
 			}

package/index.ts

@@ -494,6 +494,7 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 							autoExitOnQuiet: mode === "dispatch"
 								? handsFree?.autoExitOnQuiet !== false
 								: handsFree?.autoExitOnQuiet === true,
+							autoExitGracePeriod: handsFree?.gracePeriod ?? config.autoExitGracePeriod,
 							handoffPreviewEnabled: handoffPreview?.enabled,
 							handoffPreviewLines: handoffPreview?.lines,
 							handoffPreviewMaxChars: handoffPreview?.maxChars,
@@ -637,6 +638,7 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 				const monitor = new HeadlessDispatchMonitor(session, config, {
 					autoExitOnQuiet: handsFree?.autoExitOnQuiet !== false,
 					quietThreshold: handsFree?.quietThreshold ?? config.handsFreeQuietThreshold,
+					gracePeriod: handsFree?.gracePeriod ?? config.autoExitGracePeriod,
 					timeout,
 				}, makeMonitorCompletionCallback(pi, id, startTime));
 				headlessMonitors.set(id, monitor);
@@ -695,6 +697,7 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 							autoExitOnQuiet: mode === "dispatch"
 								? handsFree?.autoExitOnQuiet !== false
 								: handsFree?.autoExitOnQuiet === true,
+							autoExitGracePeriod: handsFree?.gracePeriod ?? config.autoExitGracePeriod,
 							handoffPreviewEnabled: handoffPreview?.enabled,
 							handoffPreviewLines: handoffPreview?.lines,
 							handoffPreviewMaxChars: handoffPreview?.maxChars,
@@ -760,6 +763,7 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 							handsFreeUpdateMaxChars: handsFree?.updateMaxChars,
 							handsFreeMaxTotalChars: handsFree?.maxTotalChars,
 							autoExitOnQuiet: handsFree?.autoExitOnQuiet,
+							autoExitGracePeriod: handsFree?.gracePeriod ?? config.autoExitGracePeriod,
 							onHandsFreeUpdate: mode === "hands-free"
 								? (update) => {
 									let statusText: string;
@@ -974,7 +978,7 @@ function setupDispatchCompletion(
 		command: string;
 		reason?: string;
 		timeout?: number;
-		handsFree?: { autoExitOnQuiet?: boolean; quietThreshold?: number };
+		handsFree?: { autoExitOnQuiet?: boolean; quietThreshold?: number; gracePeriod?: number };
 		overlayStartTime?: number;
 	},
 ): void {
@@ -1030,6 +1034,7 @@ function setupDispatchCompletion(
 					const monitor = new HeadlessDispatchMonitor(bgSession.session, config, {
 						autoExitOnQuiet: ctx.handsFree?.autoExitOnQuiet !== false,
 						quietThreshold: ctx.handsFree?.quietThreshold ?? config.handsFreeQuietThreshold,
+						gracePeriod: ctx.handsFree?.gracePeriod ?? config.autoExitGracePeriod,
 						timeout: remainingTimeout,
 					}, makeMonitorCompletionCallback(pi, bgId, bgStartTime));
 					headlessMonitors.set(bgId, monitor);

package/overlay-component.ts

@@ -13,8 +13,9 @@ import {
 	type InteractiveShellOptions,
 	type DialogChoice,
 	type OverlayState,
-	CHROME_LINES,
-	FOOTER_LINES,
+	HEADER_LINES,
+	FOOTER_LINES_COMPACT,
+	FOOTER_LINES_DIALOG,
 	formatDuration,
 } from "./types.js";
 
@@ -80,7 +81,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		const overlayWidth = Math.floor((tui.terminal.columns * this.config.overlayWidthPercent) / 100);
 		const overlayHeight = Math.floor((tui.terminal.rows * this.config.overlayHeightPercent) / 100);
 		const cols = Math.max(20, overlayWidth - 4);
-		const rows = Math.max(3, overlayHeight - CHROME_LINES);
+		const rows = Math.max(3, overlayHeight - (HEADER_LINES + FOOTER_LINES_COMPACT + 2));
 
 		const ptyEvents = {
 			onData: () => {
@@ -449,6 +450,15 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			if (this.state === "hands-free") {
 				// Auto-exit on quiet: kill session when output stops (agent likely finished task)
 				if (this.options.autoExitOnQuiet) {
+					const gracePeriod = this.options.autoExitGracePeriod ?? this.config.autoExitGracePeriod;
+					if (Date.now() - this.startTime < gracePeriod) {
+						if (this.hasUnsentData) {
+							this.emitHandsFreeUpdate();
+							this.hasUnsentData = false;
+						}
+						this.resetQuietTimer();
+						return;
+					}
 					// Emit final update with any pending output
 					if (this.hasUnsentData) {
 						this.emitHandsFreeUpdate();
@@ -1077,7 +1087,9 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		lines.push(border("├" + "─".repeat(width - 2) + "┤"));
 
 		const overlayHeight = Math.floor((this.tui.terminal.rows * this.config.overlayHeightPercent) / 100);
-		const termRows = Math.max(3, overlayHeight - CHROME_LINES);
+		const footerHeight = this.state === "detach-dialog" ? FOOTER_LINES_DIALOG : FOOTER_LINES_COMPACT;
+		const chrome = HEADER_LINES + footerHeight + 2;
+		const termRows = Math.max(3, overlayHeight - chrome);
 
 		if (innerWidth !== this.lastWidth || termRows !== this.lastHeight) {
 			this.session.resize(innerWidth, termRows);
@@ -1136,7 +1148,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			footerLines.push(row(dim("Ctrl+T transfer • Ctrl+B background • Ctrl+Q menu • Shift+Up/Down scroll")));
 		}
 
-		while (footerLines.length < FOOTER_LINES) {
+		while (footerLines.length < footerHeight) {
 			footerLines.push(emptyRow());
 		}
 		lines.push(...footerLines);

package/package.json

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

package/reattach-overlay.ts

@@ -11,8 +11,9 @@ import {
 	type InteractiveShellResult,
 	type DialogChoice,
 	type OverlayState,
-	CHROME_LINES,
-	FOOTER_LINES,
+	HEADER_LINES,
+	FOOTER_LINES_COMPACT,
+	FOOTER_LINES_DIALOG,
 } from "./types.js";
 
 export class ReattachOverlay implements Component, Focusable {
@@ -74,7 +75,7 @@ export class ReattachOverlay implements Component, Focusable {
 		const overlayWidth = Math.floor((tui.terminal.columns * this.config.overlayWidthPercent) / 100);
 		const overlayHeight = Math.floor((tui.terminal.rows * this.config.overlayHeightPercent) / 100);
 		const cols = Math.max(20, overlayWidth - 4);
-		const rows = Math.max(3, overlayHeight - CHROME_LINES);
+		const rows = Math.max(3, overlayHeight - (HEADER_LINES + FOOTER_LINES_COMPACT + 2));
 		bgSession.session.resize(cols, rows);
 	}
 
@@ -400,7 +401,9 @@ export class ReattachOverlay implements Component, Focusable {
 		lines.push(border("├" + "─".repeat(width - 2) + "┤"));
 
 		const overlayHeight = Math.floor((this.tui.terminal.rows * this.config.overlayHeightPercent) / 100);
-		const termRows = Math.max(3, overlayHeight - CHROME_LINES);
+		const footerHeight = this.state === "detach-dialog" ? FOOTER_LINES_DIALOG : FOOTER_LINES_COMPACT;
+		const chrome = HEADER_LINES + footerHeight + 2;
+		const termRows = Math.max(3, overlayHeight - chrome);
 
 		if (innerWidth !== this.lastWidth || termRows !== this.lastHeight) {
 			this.session.resize(innerWidth, termRows);
@@ -457,7 +460,7 @@ export class ReattachOverlay implements Component, Focusable {
 			footerLines.push(row(dim("Ctrl+T transfer • Ctrl+B background • Ctrl+Q menu • Shift+Up/Down scroll")));
 		}
 
-		while (footerLines.length < FOOTER_LINES) {
+		while (footerLines.length < footerHeight) {
 			footerLines.push(emptyRow());
 		}
 		lines.push(...footerLines);

package/tool-schema.ts

@@ -236,6 +236,9 @@ export const toolParameters = Type.Object({
 			quietThreshold: Type.Optional(
 				Type.Number({ description: "Silence duration before emitting update in on-quiet mode (default: 5000ms)" }),
 			),
+			gracePeriod: Type.Optional(
+				Type.Number({ description: "Startup grace period before autoExitOnQuiet can kill the session (default: 30000ms)" }),
+			),
 			updateMaxChars: Type.Optional(
 				Type.Number({ description: "Max chars per update (default: 1500)" }),
 			),
@@ -299,6 +302,7 @@ export interface ToolParams {
 		updateMode?: "on-quiet" | "interval";
 		updateInterval?: number;
 		quietThreshold?: number;
+		gracePeriod?: number;
 		updateMaxChars?: number;
 		maxTotalChars?: number;
 		autoExitOnQuiet?: boolean;

package/types.ts

@@ -70,6 +70,7 @@ export interface InteractiveShellOptions {
 	onHandsFreeUpdate?: (update: HandsFreeUpdate) => void;
 	// Auto-exit when output stops (for agents that don't exit on their own)
 	autoExitOnQuiet?: boolean;
+	autoExitGracePeriod?: number;
 	// Auto-kill timeout
 	timeout?: number;
 	// Existing PTY session (for attach flow -- skip creating a new PTY)
@@ -80,9 +81,9 @@ export type DialogChoice = "kill" | "background" | "transfer" | "cancel";
 export type OverlayState = "running" | "exited" | "detach-dialog" | "hands-free";
 
 // UI constants
-export const FOOTER_LINES = 6;
+export const FOOTER_LINES_COMPACT = 2;
+export const FOOTER_LINES_DIALOG = 6;
 export const HEADER_LINES = 4;
-export const CHROME_LINES = HEADER_LINES + FOOTER_LINES + 2;
 
 /** Format milliseconds to human-readable duration */
 export function formatDuration(ms: number): string {