pi-interactive-shell 0.6.4 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to the `pi-interactive-shell` extension will be documented i
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-02-03
+
+### Added
+- **Dispatch mode** (`mode: "dispatch"`) - Fire-and-forget sessions where the agent is notified on completion via `triggerTurn` instead of polling. Defaults `autoExitOnQuiet: true`.
+- **Background dispatch** (`mode: "dispatch", background: true`) - Headless sessions with no overlay. Multiple can run concurrently alongside an interactive overlay.
+- **Agent-initiated background** (`sessionId, background: true`) - Dismiss an active overlay while keeping the process running.
+- **Attach** (`attach: "session-id"`) - Reattach to background sessions with any mode (interactive, hands-free, dispatch).
+- **List background sessions** (`listBackground: true`) - Query all background sessions with status and duration.
+- **Ctrl+B shortcut** - Direct keyboard shortcut to background a session (dismiss overlay, keep process running) without navigating the Ctrl+Q menu.
+- **HeadlessDispatchMonitor** - Lightweight monitor for background PTY sessions handling quiet timer, timeout, exit detection, and output capture.
+- **Completion output capture** - `completionOutput` captured before PTY disposal in all `finishWith*` methods for dispatch notifications.
+- `completionNotifyLines` and `completionNotifyMaxChars` config options for notification output size.
+- **Dismiss background sessions** - `/dismiss [id]` user command and `dismissBackground` tool param to kill running / remove exited sessions without opening an overlay.
+- **Background sessions widget** - Persistent widget below the editor showing all background sessions with status indicators (`●` running / `○` exited), session ID, command, reason, and live duration. Auto-appears/disappears. Responsive layout wraps to two lines on narrow terminals.
+- **Additive listeners on PtyTerminalSession** - `addDataListener()` and `addExitListener()` allow multiple subscribers alongside the primary `setEventHandlers()`. Headless monitor and overlay coexist without conflicts.
+
+### Changed
+- `sessionManager.add()` now accepts optional `{ id, noAutoCleanup }` options for headless dispatch sessions.
+- `sessionManager.take()` removes sessions from background registry without disposing PTY (for attach flow).
+- `ActiveSession` interface now includes `background()` method.
+- Overlay `onExit` handler broadened: non-blocking modes (dispatch and hands-free) auto-close immediately on exit instead of showing countdown.
+- `finishWithBackground()` reuses sessionId as backgroundId for non-blocking modes.
+- `getOutputSinceLastCheck()` returns `completionOutput` as fallback when session is finished.
+- `/attach` command coordinates with headless monitors via additive listeners (monitor stays active during overlay).
+- Headless dispatch completion notifications are compact: status line, duration, 5-line tail, and reattach instruction. Full output available via `details.completionOutput` or by reattaching.
+- Completed headless sessions preserve their PTY for 5 minutes (`scheduleCleanup`) instead of disposing immediately, allowing the agent to reattach and review full scrollback.
+- Notification tail strips trailing blank lines from terminal buffer before slicing.
+
+### Fixed
+- Interval timer in `startHandsFreeUpdates()` and `setUpdateInterval()` no longer kills autoExitOnQuiet detection in dispatch mode (guarded on-quiet branch with `onHandsFreeUpdate` null check).
+- Hands-free non-blocking polls returning empty output for completed sessions now return captured `completionOutput`.
+
 ## [0.6.4] - 2026-02-01
 
 ### Fixed

package/README.md

@@ -32,11 +32,28 @@ The `interactive-shell` skill is automatically symlinked to `~/.pi/agent/skills/
 
 **Requires:** Node.js, build tools for `node-pty` (Xcode CLI tools on macOS).
 
-## Quick Start
+## Modes
+
+Three modes control how the agent engages with a session:
+
+| | Interactive | Hands-Free | Dispatch |
+|---|---|---|---|
+| **Agent blocked?** | Yes — tool call waits | No — returns immediately | No — returns immediately |
+| **How agent gets output** | Tool return value | Polls with `sessionId` | Notification via `triggerTurn` |
+| **Overlay visible?** | Yes | Yes | Yes (or headless with `background: true`) |
+| **User can interact?** | Always | Type to take over | Type to take over |
+| **Concurrent sessions?** | No | One overlay + queries | Multiple headless, one overlay |
+| **Best for** | Editors, REPLs, SSH | Dev servers, builds | Delegating to other agents |
 
-### Interactive Mode
+**Interactive** is the default. The agent's tool call blocks until the session ends — use this when the agent needs the result right away, or when the user drives the session (editors, database shells).
 
-User controls the session directly:
+**Hands-free** returns immediately so the agent can do other work, but the agent must poll periodically to discover output and completion. Good for processes the agent needs to monitor and react to mid-flight, like watching build output and sending follow-up commands.
+
+**Dispatch** also returns immediately, but the agent doesn't poll at all. When the session completes — whether by natural exit, quiet detection, timeout, or user intervention — the agent gets woken up with a notification containing the tail output. This is the right mode for delegating a task to a subagent and moving on. Add `background: true` to skip the overlay entirely and run headless.
+
+## Quick Start
+
+### Interactive
 
 ```typescript
 interactive_shell({ command: 'vim package.json' })
@@ -44,9 +61,9 @@ interactive_shell({ command: 'psql -d mydb' })
 interactive_shell({ command: 'ssh user@server' })
 ```
 
-### Hands-Free Mode
+The agent's turn is blocked until the overlay closes. User controls the session directly.
 
-Agent monitors while user watches. Returns immediately with sessionId:
+### Hands-Free
 
 ```typescript
 // Start a long-running process
@@ -57,20 +74,68 @@ interactive_shell({
 })
 // → { sessionId: "calm-reef", status: "running" }
 
-// Query status (rate-limited to 60s)
+// Poll for output (rate-limited to 60s between queries)
 interactive_shell({ sessionId: "calm-reef" })
-// → { status: "running", output: "...", runtime: 45000 }
+// → { status: "running", output: "Server ready on :3000", runtime: 45000 }
 
-// Send input if needed
+// Send input when needed
 interactive_shell({ sessionId: "calm-reef", inputKeys: ["ctrl+c"] })
 
 // Kill when done
 interactive_shell({ sessionId: "calm-reef", kill: true })
+// → { status: "killed", output: "..." }
+```
+
+The overlay opens for the user to watch. The agent checks in periodically. User can type anything to take over control.
+
+### Dispatch
+
+```typescript
+// Fire off a task
+interactive_shell({
+  command: 'pi "Refactor the auth module"',
+  mode: "dispatch",
+  reason: "Auth refactor"
+})
+// → Returns immediately: { sessionId: "calm-reef" }
+// → Agent ends turn or does other work.
+```
+
+When the session completes, the agent receives a compact notification on a new turn:
+
+```
+Session calm-reef completed successfully (5m 23s). 847 lines of output.
+
+Step 9 of 10
+Step 10 of 10
+All tasks completed.
+
+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.
+
+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.
+
+### Background Dispatch (Headless)
+
+```typescript
+// No overlay — runs completely invisibly
+interactive_shell({
+  command: 'pi "Fix all lint errors"',
+  mode: "dispatch",
+  background: true
+})
+// → { sessionId: "calm-reef" }
+// → User can /attach calm-reef to peek
+// → Agent notified on completion, same as regular dispatch
 ```
 
-User sees the overlay in real-time. Type anything to take over control.
+Multiple headless dispatches can run concurrently alongside a single interactive overlay. This is how you parallelize subagent work — fire off three background dispatches and process results as each completion notification arrives.
 
-### Timeout Mode
+### Timeout
 
 Capture output from TUI apps that don't exit cleanly:
 
@@ -154,14 +219,34 @@ The main agent then has the subagent's response in context and can continue work
 
 ### Background Sessions
 
-1. Ctrl+Q → "Run in background"
-2. `/attach` or `/attach <id>` to reattach
+Sessions can be backgrounded by the user (Ctrl+B, or Ctrl+Q → "Run in background") or by the agent:
+
+```typescript
+// Agent backgrounds an active session
+interactive_shell({ sessionId: "calm-reef", background: true })
+// → Overlay closes, process keeps running
+
+// List background sessions
+interactive_shell({ listBackground: true })
+
+// Reattach with a specific mode
+interactive_shell({ attach: "calm-reef" })                      // interactive (blocking)
+interactive_shell({ attach: "calm-reef", mode: "hands-free" })  // hands-free (poll)
+interactive_shell({ attach: "calm-reef", mode: "dispatch" })    // dispatch (notified)
+
+// Dismiss background sessions
+interactive_shell({ dismissBackground: true })               // all sessions
+interactive_shell({ dismissBackground: "calm-reef" })        // specific session
+```
+
+User can also `/attach` or `/attach <id>` to reattach, and `/dismiss` or `/dismiss <id>` to clean up from the chat.
 
 ## Keys
 
 | Key | Action |
 |-----|--------|
 | Ctrl+T | **Transfer & close** - capture output and send to main agent |
+| Ctrl+B | Background session (dismiss overlay, keep running) |
 | Ctrl+Q | Session menu (transfer/background/kill/cancel) |
 | Shift+Up/Down | Scroll history |
 | Any key (hands-free) | Take over control |
@@ -181,6 +266,8 @@ Configuration files (project overrides global):
   "minQueryIntervalSeconds": 60,
   "transferLines": 200,
   "transferMaxChars": 20000,
+  "completionNotifyLines": 50,
+  "completionNotifyMaxChars": 5000,
   "handsFreeUpdateMode": "on-quiet",
   "handsFreeUpdateInterval": 60000,
   "handsFreeQuietThreshold": 5000,
@@ -203,6 +290,8 @@ Configuration files (project overrides global):
 | `minQueryIntervalSeconds` | 60 | Rate limit between agent queries |
 | `transferLines` | 200 | Lines to capture on Ctrl+T transfer (10-1000) |
 | `transferMaxChars` | 20000 | Max chars for transfer (1KB-100KB) |
+| `completionNotifyLines` | 50 | Lines in dispatch completion notification (10-500) |
+| `completionNotifyMaxChars` | 5000 | Max chars in completion notification (1KB-50KB) |
 | `handsFreeUpdateMode` | "on-quiet" | "on-quiet" or "interval" |
 | `handsFreeQuietThreshold` | 5000 | Silence duration before update (ms) |
 | `handsFreeUpdateInterval` | 60000 | Max interval between updates (ms) |

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: interactive-shell
-description: Cheat sheet + workflow for launching interactive coding-agent CLIs (Claude Code, Gemini CLI, Codex CLI, Cursor CLI, and pi itself) via the interactive_shell overlay. The overlay is for interactive supervision only - headless commands should use the bash tool instead.
+description: Cheat sheet + workflow for launching interactive coding-agent CLIs (Claude Code, Gemini CLI, Codex CLI, Cursor CLI, and pi itself) via the interactive_shell overlay or headless dispatch. Use for TUI agents and long-running processes that need supervision, fire-and-forget delegation, or headless background execution. Regular bash commands should use the bash tool instead.
 ---
 
 # Interactive Shell (Skill)
@@ -11,16 +11,18 @@ Last verified: 2026-01-18
 
 Pi has two ways to delegate work to other AI coding agents:
 
-| | Foreground Subagents | Background Subagents |
-|---|---|---|
-| **Tool** | `interactive_shell` | `subagent` |
-| **Visibility** | User sees overlay in real-time | Hidden from user |
-| **Default agent** | `pi` (others if user requests) | Pi only |
-| **Output** | Minimal (tail preview) | Full output captured |
-| **User control** | Can take over anytime | No intervention |
-| **Best for** | Long tasks needing supervision | Parallel tasks, structured delegation |
+| | Foreground Subagents | Dispatch Subagents | Background Subagents |
+|---|---|---|---|
+| **Tool** | `interactive_shell` | `interactive_shell` (dispatch) | `subagent` |
+| **Visibility** | User sees overlay | User sees overlay (or headless) | Hidden from user |
+| **Agent model** | Polls for status | Notified on completion | Full output captured |
+| **Default agent** | `pi` (others if user requests) | `pi` (others if user requests) | Pi only |
+| **User control** | Can take over anytime | Can take over anytime | No intervention |
+| **Best for** | Long tasks needing supervision | Fire-and-forget delegations | Parallel tasks, structured delegation |
 
-**Foreground subagents** run in an overlay where the user watches (and can intervene). Use `interactive_shell` with `mode: "hands-free"` to monitor while receiving periodic updates.
+**Foreground subagents** run in an overlay where the user watches (and can intervene). Use `interactive_shell` with `mode: "hands-free"` to monitor while receiving periodic updates, or `mode: "dispatch"` to be notified on completion without polling.
+
+**Dispatch subagents** also use `interactive_shell` but with `mode: "dispatch"`. The agent fires the session and moves on. When the session completes, the agent is woken up via `triggerTurn` with the output in context. Add `background: true` for headless execution (no overlay).
 
 **Background subagents** run invisibly via the `subagent` tool. Pi-only, but captures full output and supports parallel execution.
 
@@ -66,6 +68,34 @@ Agent starts working immediately, user supervises.
 interactive_shell({ command: 'pi "Review this codebase for security issues"' })
 ```
 
+### Dispatch (Fire-and-Forget) - NON-BLOCKING, NO POLLING
+Agent fires a session and moves on. Notified automatically on completion via `triggerTurn`.
+
+```typescript
+// Start session - returns immediately, no polling needed
+interactive_shell({
+  command: 'pi "Fix all TypeScript errors in src/"',
+  mode: "dispatch",
+  reason: "Fixing TS errors"
+})
+// Returns: { sessionId: "calm-reef", mode: "dispatch" }
+// → Do other work. When session completes, you receive notification with output.
+```
+
+Dispatch defaults `autoExitOnQuiet: true`. The agent can still query the sessionId if needed, but doesn't have to.
+
+#### Background Dispatch (Headless)
+No overlay opens. Multiple headless dispatches can run concurrently:
+
+```typescript
+interactive_shell({
+  command: 'pi "Fix lint errors"',
+  mode: "dispatch",
+  background: true
+})
+// → No overlay. User can /attach to watch. Agent notified on completion.
+```
+
 ### Hands-Free (Foreground Subagent) - NON-BLOCKING
 Agent works autonomously, **returns immediately** with sessionId. You query for status/output and kill when done.
 
@@ -315,13 +345,13 @@ interactive_shell({ sessionId: "calm-reef", settings: { updateInterval: 30000, q
 
 ## CLI Quick Reference
 
-| 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"` |
+| Agent | Interactive | With Prompt | Headless (bash) | Dispatch |
+|-------|-------------|-------------|-----------------|----------|
+| `claude` | `claude` | `claude "prompt"` | `claude -p "prompt"` | `mode: "dispatch"` |
+| `gemini` | `gemini` | `gemini -i "prompt"` | `gemini "prompt"` | `mode: "dispatch"` |
+| `codex` | `codex` | `codex "prompt"` | `codex exec "prompt"` | `mode: "dispatch"` |
+| `agent` | `agent` | `agent "prompt"` | `agent -p "prompt"` | `mode: "dispatch"` |
+| `pi` | `pi` | `pi "prompt"` | `pi -p "prompt"` | `mode: "dispatch"` |
 
 **Gemini model:** `gemini -m gemini-3-flash-preview -i "prompt"`
 
@@ -401,8 +431,47 @@ The process is killed after timeout and captured output is returned in the hando
 
 For pi CLI documentation, you can also read directly: `/opt/homebrew/lib/node_modules/@mariozechner/pi-coding-agent/README.md`
 
+## Background Session Management
+
+```typescript
+// Background an active session (close overlay, keep running)
+interactive_shell({ sessionId: "calm-reef", background: true })
+
+// List all background sessions
+interactive_shell({ listBackground: true })
+
+// Reattach to a background session
+interactive_shell({ attach: "calm-reef" })                    // interactive (blocking)
+interactive_shell({ attach: "calm-reef", mode: "hands-free" })  // hands-free (poll)
+interactive_shell({ attach: "calm-reef", mode: "dispatch" })    // dispatch (notified)
+
+// Dismiss background sessions (kill running, remove exited)
+interactive_shell({ dismissBackground: true })               // all
+interactive_shell({ dismissBackground: "calm-reef" })        // specific
+```
+
 ## Quick Reference
 
+**Dispatch subagent (fire-and-forget, default to pi):**
+```typescript
+interactive_shell({
+  command: 'pi "Implement the feature described in SPEC.md"',
+  mode: "dispatch",
+  reason: "Implementing feature"
+})
+// Returns immediately. You'll be notified when done.
+```
+
+**Background dispatch (headless, no overlay):**
+```typescript
+interactive_shell({
+  command: 'pi "Fix lint errors"',
+  mode: "dispatch",
+  background: true,
+  reason: "Fixing lint"
+})
+```
+
 **Start foreground subagent (hands-free, default to pi):**
 ```typescript
 interactive_shell({

package/config.ts

@@ -17,6 +17,9 @@ export interface InteractiveShellConfig {
 	// Transfer output settings (Ctrl+T)
 	transferLines: number;
 	transferMaxChars: number;
+	// Dispatch completion notification output
+	completionNotifyLines: number;
+	completionNotifyMaxChars: number;
 	// Hands-free mode defaults
 	handsFreeUpdateMode: "on-quiet" | "interval";
 	handsFreeUpdateInterval: number;
@@ -42,6 +45,9 @@ const DEFAULT_CONFIG: InteractiveShellConfig = {
 	// Transfer output settings (Ctrl+T) - generous defaults for full context transfer
 	transferLines: 200,
 	transferMaxChars: 20000,
+	// Dispatch completion notification output (between handoff preview and transfer)
+	completionNotifyLines: 50,
+	completionNotifyMaxChars: 5000,
 	// Hands-free mode defaults
 	handsFreeUpdateMode: "on-quiet" as const,
 	handsFreeUpdateInterval: 60000,
@@ -79,6 +85,7 @@ export function loadConfig(cwd: string): InteractiveShellConfig {
 
 	return {
 		...merged,
+		exitAutoCloseDelay: clampInt(merged.exitAutoCloseDelay, DEFAULT_CONFIG.exitAutoCloseDelay, 0, 60),
 		overlayWidthPercent: clampPercent(merged.overlayWidthPercent, DEFAULT_CONFIG.overlayWidthPercent),
 		// Height: 20-90% range (default 45%)
 		overlayHeightPercent: clampInt(merged.overlayHeightPercent, DEFAULT_CONFIG.overlayHeightPercent, 20, 90),
@@ -103,6 +110,9 @@ export function loadConfig(cwd: string): InteractiveShellConfig {
 		// Transfer output settings (Ctrl+T)
 		transferLines: clampInt(merged.transferLines, DEFAULT_CONFIG.transferLines, 10, 1000),
 		transferMaxChars: clampInt(merged.transferMaxChars, DEFAULT_CONFIG.transferMaxChars, 1000, 100000),
+		// Dispatch completion notification output
+		completionNotifyLines: clampInt(merged.completionNotifyLines, DEFAULT_CONFIG.completionNotifyLines, 10, 500),
+		completionNotifyMaxChars: clampInt(merged.completionNotifyMaxChars, DEFAULT_CONFIG.completionNotifyMaxChars, 1000, 50000),
 		// Hands-free mode
 		handsFreeUpdateMode: merged.handsFreeUpdateMode === "interval" ? "interval" : "on-quiet",
 		handsFreeUpdateInterval: clampInt(

package/headless-monitor.ts

@@ -0,0 +1,171 @@
+import type { PtyTerminalSession } from "./pty-session.js";
+import type { InteractiveShellConfig } from "./config.js";
+
+export interface HeadlessMonitorOptions {
+	autoExitOnQuiet: boolean;
+	quietThreshold: number;
+	timeout?: number;
+}
+
+export interface HeadlessCompletionInfo {
+	exitCode: number | null;
+	signal?: number;
+	timedOut?: boolean;
+	cancelled?: boolean;
+	completionOutput?: {
+		lines: string[];
+		totalLines: number;
+		truncated: boolean;
+	};
+}
+
+export class HeadlessDispatchMonitor {
+	readonly startTime = Date.now();
+	private _disposed = false;
+	private quietTimer: ReturnType<typeof setTimeout> | null = null;
+	private timeoutTimer: ReturnType<typeof setTimeout> | null = null;
+	private result: HeadlessCompletionInfo | undefined;
+	private completeCallbacks: Array<() => void> = [];
+	private unsubData: (() => void) | null = null;
+	private unsubExit: (() => void) | null = null;
+
+	get disposed(): boolean { return this._disposed; }
+
+	constructor(
+		private session: PtyTerminalSession,
+		private config: InteractiveShellConfig,
+		private options: HeadlessMonitorOptions,
+		private onComplete: (info: HeadlessCompletionInfo) => void,
+	) {
+		this.subscribe();
+
+		if (options.timeout && options.timeout > 0) {
+			this.timeoutTimer = setTimeout(() => {
+				this.handleCompletion(null, undefined, true);
+			}, options.timeout);
+		}
+
+		if (session.exited) {
+			queueMicrotask(() => {
+				if (!this._disposed) {
+					this.handleCompletion(session.exitCode, session.signal);
+				}
+			});
+		}
+	}
+
+	private subscribe(): void {
+		this.unsubscribe();
+		this.unsubData = this.session.addDataListener(() => {
+			if (this.options.autoExitOnQuiet) {
+				this.resetQuietTimer();
+			}
+		});
+		this.unsubExit = this.session.addExitListener((exitCode, signal) => {
+			if (!this._disposed) {
+				this.handleCompletion(exitCode, signal);
+			}
+		});
+	}
+
+	private unsubscribe(): void {
+		this.unsubData?.();
+		this.unsubData = null;
+		this.unsubExit?.();
+		this.unsubExit = null;
+	}
+
+	private resetQuietTimer(): void {
+		this.stopQuietTimer();
+		this.quietTimer = setTimeout(() => {
+			this.quietTimer = null;
+			if (!this._disposed && this.options.autoExitOnQuiet) {
+				this.session.kill();
+				this.handleCompletion(null, undefined, false, true);
+			}
+		}, this.options.quietThreshold);
+	}
+
+	private stopQuietTimer(): void {
+		if (this.quietTimer) {
+			clearTimeout(this.quietTimer);
+			this.quietTimer = null;
+		}
+	}
+
+	private captureOutput(): HeadlessCompletionInfo["completionOutput"] {
+		try {
+			const result = this.session.getTailLines({
+				lines: this.config.completionNotifyLines,
+				ansi: false,
+				maxChars: this.config.completionNotifyMaxChars,
+			});
+			return {
+				lines: result.lines,
+				totalLines: result.totalLinesInBuffer,
+				truncated: result.lines.length < result.totalLinesInBuffer || result.truncatedByChars,
+			};
+		} catch {
+			return { lines: [], totalLines: 0, truncated: false };
+		}
+	}
+
+	private handleCompletion(exitCode: number | null, signal?: number, timedOut?: boolean, cancelled?: boolean): void {
+		if (this._disposed) return;
+		this._disposed = true;
+		this.stopQuietTimer();
+		if (this.timeoutTimer) { clearTimeout(this.timeoutTimer); this.timeoutTimer = null; }
+		this.unsubscribe();
+
+		if (timedOut) {
+			this.session.kill();
+		}
+
+		const completionOutput = this.captureOutput();
+		const info: HeadlessCompletionInfo = { exitCode, signal, timedOut, cancelled, completionOutput };
+		this.result = info;
+		this.triggerCompleteCallbacks();
+		this.onComplete(info);
+	}
+
+	handleExternalCompletion(exitCode: number | null, signal?: number, completionOutput?: HeadlessCompletionInfo["completionOutput"]): void {
+		if (this._disposed) return;
+		this._disposed = true;
+		this.stopQuietTimer();
+		if (this.timeoutTimer) { clearTimeout(this.timeoutTimer); this.timeoutTimer = null; }
+		this.unsubscribe();
+
+		const output = completionOutput ?? this.captureOutput();
+		const info: HeadlessCompletionInfo = { exitCode, signal, completionOutput: output };
+		this.result = info;
+		this.triggerCompleteCallbacks();
+		this.onComplete(info);
+	}
+
+	getResult(): HeadlessCompletionInfo | undefined {
+		return this.result;
+	}
+
+	registerCompleteCallback(callback: () => void): void {
+		if (this.result) {
+			callback();
+			return;
+		}
+		this.completeCallbacks.push(callback);
+	}
+
+	private triggerCompleteCallbacks(): void {
+		for (const cb of this.completeCallbacks) {
+			try { cb(); } catch { /* ignore */ }
+		}
+		this.completeCallbacks = [];
+	}
+
+	dispose(): void {
+		if (this._disposed) return;
+		this._disposed = true;
+		this.stopQuietTimer();
+		if (this.timeoutTimer) { clearTimeout(this.timeoutTimer); this.timeoutTimer = null; }
+		this.unsubscribe();
+	}
+}