@light4/pi-shell-bridge 0.0.0-stage → 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 light4
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# pi-shell-bridge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Pi extension that connects Pi's `!` / `!!` commands to your shell:
+
+- **Tab completion** — on a `!cmd` line, `Tab` asks your shell for completions (commands, subcommands, options, paths, git branches, …) with their descriptions.
+- **Autosuggestions** — like fish, typing a `!` command shows the newest matching command from your shell history in grey after the cursor; `→` accepts it.
+- **Shell history** — every `!` / `!!` command is appended to the fish, zsh and bash history you already keep, so it shows up in `↑`, `Ctrl+R`, atuin imports and so on.
+
+Commands still run through Pi's built-in bash; this extension only adds completion and history.
+
+## Supported shells
+
+| Shell | Completion | History |
+|---|---|---|
+| fish | `complete -C` (full fish completions and descriptions) | `history append`, honouring `fish_history` |
+| zsh | the zsh completion system, captured through `zsh/zpty` with your `.zshrc` loaded | `print -s` + `fc -AI` into your `HISTFILE`, respecting `EXTENDED_HISTORY` |
+| bash | `complete -p` specs, loading [bash-completion](https://github.com/scop/bash-completion) when it is installed | `history -s` + `history -a` into your `HISTFILE`, respecting `HISTTIMEFORMAT` |
+
+Each shell writes its own history file, so locking, timestamps, multi-line commands and zsh's metafied encoding are handled by the shell itself. Helper shells never record their own commands in your history.
+
+## Use
+
+- Type `!git chec` and press `Tab`. A single match is inserted directly; several matches open Pi's completion list. Directories and `--option=` values do not get a trailing space, so you can keep completing.
+- Type `!pi` and, if you ran `pi update --extensions` before, ` update --extensions` appears dimmed after the cursor, as in fish. It is only a suggestion: `Enter` runs what you typed. `→`, `End`, `Ctrl+F` or `Ctrl+E` accept the whole suggestion; `Alt+→` or `Alt+F` accept one word. Suggestions come from the launching shell's history file and the `!` commands of the current session, newest first; they appear only while the cursor is at the end of a single-line `!` command and no completion list is open. The keys follow Pi's `tui.editor.cursorRight`, `cursorLineEnd` and `cursorWordRight` keybindings.
+- Run any `!` or `!!` command. It is added to the history of each configured shell. Open fish shells see it after `history merge` (or in new sessions); zsh with `SHARE_HISTORY` picks it up automatically.
+
+The shell is started only when you press `Tab`, never on every keystroke. Completion takes roughly 0.1–0.3 s for fish and bash and 0.5–1 s for zsh, depending on your startup files.
+
+## Configure
+
+Defaults work without configuration:
+
+- **completion** `auto`: the shell Pi was launched from (its nearest shell ancestor); if that shell is not supported, `$SHELL`, then the first installed of fish, zsh, bash.
+- **history** `auto`: only the shell Pi was launched from, and only when its history file already exists. When Pi is started from an unsupported shell (`nu`, `sh`, `dash`, …) nothing is written; when no shell ancestor exists (Pi launched directly by a terminal or IDE), `$SHELL` is used. zsh without a `HISTFILE` is skipped.
+
+Helper shells run in their own session without a controlling terminal, so interactive startup files (`bash -i`, `zsh -i`) can never take over Pi's terminal, whichever shell Pi was started from.
+
+To change them, create `~/.pi/agent/pi-shell-bridge.json`:
+
+```json
+{
+  "completion": "zsh",
+  "history": ["zsh", "fish"],
+  "autosuggest": true,
+  "loadUserConfig": true,
+  "ignore": ["^export .*TOKEN", "password"]
+}
+```
+
+| Key | Values | Default |
+|---|---|---|
+| `completion` | `auto`, `fish`, `zsh`, `bash`, `off` | `auto` |
+| `history` | `auto` (launching shell), `off`, or a list of `fish` / `zsh` / `bash` | `auto` |
+| `autosuggest` | Fish-style inline suggestions on `!` lines (`true` / `false`) | `true` |
+| `loadUserConfig` | Load your shell startup files for completion and to discover `HISTFILE` | `true` |
+| `ignore` | Regular expressions; matching commands are not written to history | `[]` |
+
+Environment variables override the file for one Pi launch:
+
+```sh
+PI_SHELL_BRIDGE_COMPLETION=bash PI_SHELL_BRIDGE_HISTORY=fish,zsh pi
+PI_SHELL_BRIDGE_HISTORY=off pi
+PI_SHELL_BRIDGE_AUTOSUGGEST=off pi
+```
+
+Autosuggestions replace Pi's input editor with a subclass of `CustomEditor`, keeping every Pi keybinding. If another extension has already replaced the editor, pi-shell-bridge leaves it alone and shows no suggestions; set `"autosuggest": false` to never touch the editor.
+
+Pi trims the command after `!`, so the usual "leading space skips history" convention cannot apply; use `ignore` instead.
+
+## Install
+
+Install the v0.1.4 release from npm:
+
+```sh
+pi install npm:@light4/pi-shell-bridge@0.1.4
+```
+
+Or install the same release from GitHub: `pi install git:github.com/light4/pi-shell-bridge@v0.1.4`.
+
+Restart Pi or run `/reload` afterwards.
+
+## Install for local development
+
+Pi auto-discovers an extension whose directory contains `index.ts`:
+
+```sh
+ln -sfn ~/sources/pi-shell-bridge/src ~/.pi/agent/extensions/pi-shell-bridge
+```
+
+Or load it for a single run:
+
+```sh
+pi -e ~/sources/pi-shell-bridge/src/index.ts
+```
+
+Type-check with:
+
+```sh
+pnpm install
+pnpm run typecheck
+```
+
+## End-to-end tests
+
+`e2e/test_e2e.py` (Python standard library only, run through [uv](https://docs.astral.sh/uv/)) starts real interactive fish, zsh, bash, sh, dash and nu shells in a pseudo terminal, launches `pi` with this extension from each, and checks that Pi stays in the terminal foreground (is never stopped by job control), that `Tab` completes `!` lines and that `!` commands reach the expected history files. Every test uses a temporary `HOME` and Pi agent dir, so your own history and settings are untouched; missing shells are skipped.
+
+```sh
+pnpm run test:e2e                              # or: uv run e2e/test_e2e.py
+E2E_SHELLS=fish,zsh uv run e2e/test_e2e.py     # only these shells
+E2E_EXTENSION=/path/to/src/index.ts PI_BIN=/path/to/pi E2E_VERBOSE=1 uv run e2e/test_e2e.py
+```
+
+## Acknowledgements
+
+The zsh capture technique follows [Valodim/zsh-capture-completion](https://github.com/Valodim/zsh-capture-completion) (MIT).
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@light4/pi-shell-bridge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.4",
+  "packageManager": "pnpm@12.8.1",
+  "description": "Shell completion, fish-style autosuggestions and fish/zsh/bash history for Pi's ! commands",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "shell",
+    "completion",
+    "history",
+    "autosuggestion",
+    "fish",
+    "zsh",
+    "bash"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/light4/pi-shell-bridge.git"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "test:e2e": "uv run e2e/test_e2e.py"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^1.5.0",
+    "@earendil-works/pi-tui": "^1.5.0",
+    "@types/node": "^22.20.5",
+    "typescript": "^7.0.2"
+  }
+}

package/src/autosuggest.ts

@@ -0,0 +1,100 @@
+// Fish-style autosuggestions for `!` lines: the newest matching history command is drawn dimmed after the
+// cursor. It is not part of the editor text; → / End / Ctrl+F accept it, Alt+→ / Alt+F accept one word.
+
+import { CustomEditor, type ExtensionUIContext, type KeybindingsManager } from "@earendil-works/pi-coding-agent";
+import { type EditorTheme, renderFakeCursor, type TUI, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { HistoryIndex } from "./history.ts";
+
+type EditorFactory = NonNullable<Parameters<ExtensionUIContext["setEditorComponent"]>[0]>;
+
+const END_CURSOR = renderFakeCursor(" ");
+const BANG_LINE = /^(\s*!!?\s*)(.*)$/s;
+
+/** The command typed after `!` / `!!`, or undefined when the text is not a bash-mode line. */
+export function bangCommand(text: string): string | undefined {
+	const match = text.match(BANG_LINE);
+	return match ? match[2] : undefined;
+}
+
+/** The first word of a suggestion, with the whitespace before it (fish: Alt+→). */
+export function firstWord(suffix: string): string {
+	return suffix.match(/^\s*\S+/)?.[0] ?? suffix;
+}
+
+/**
+ * Replace the end-of-line fake cursor and the padding after it with `suffix`: the cursor sits on the
+ * first suggested character, the rest is styled with `dim`. Lines without that cursor are returned unchanged.
+ */
+export function drawSuggestion(line: string, suffix: string, paddingX: number, dim: (text: string) => string): string {
+	const at = line.lastIndexOf(END_CURSOR);
+	if (at === -1) return line;
+	const after = line.slice(at + END_CURSOR.length);
+	if (!/^ *$/.test(after)) return line;
+	const room = 1 + Math.max(0, after.length - paddingX); // the cursor cell plus the padding up to the margin
+	const shown = truncateToWidth(suffix, room, "");
+	const graphemes = [...new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(shown)];
+	const head = graphemes[0]?.segment;
+	if (!head || visibleWidth(head) !== 1) return line; // keep the one-cell cursor layout intact
+	const rest = shown.slice(head.length);
+	const used = visibleWidth(shown);
+	return line.slice(0, at) + renderFakeCursor(dim(head)) + dim(rest) + " ".repeat(Math.max(0, after.length + 1 - used));
+}
+
+export class AutosuggestEditor extends CustomEditor {
+	constructor(
+		tui: TUI,
+		theme: EditorTheme,
+		private readonly keys: KeybindingsManager,
+		private readonly commands: HistoryIndex,
+		private readonly dim: (text: string) => string,
+	) {
+		super(tui, theme, keys);
+	}
+
+	/** The suggested completion of the current line, when the cursor is at the end of a single-line `!` command. */
+	suggestion(): string | undefined {
+		if (this.isShowingAutocomplete()) return undefined;
+		const lines = this.getLines();
+		if (lines.length !== 1) return undefined;
+		const cursor = this.getCursor();
+		if (cursor.line !== 0 || cursor.col !== lines[0].length) return undefined;
+		const command = bangCommand(lines[0]);
+		return command === undefined ? undefined : this.commands.suggest(command);
+	}
+
+	override render(width: number): string[] {
+		const lines = super.render(width);
+		try {
+			const suffix = this.suggestion();
+			if (!suffix) return lines;
+			const index = lines.findIndex((line) => line.includes(END_CURSOR));
+			if (index !== -1) lines[index] = drawSuggestion(lines[index], suffix, this.getPaddingX(), this.dim);
+		} catch {
+			// Never break the editor over a suggestion.
+		}
+		return lines;
+	}
+
+	override handleInput(data: string): void {
+		const suffix = this.acceptable(data);
+		if (suffix) {
+			this.insertTextAtCursor(suffix);
+			return;
+		}
+		super.handleInput(data);
+	}
+
+	private acceptable(data: string): string | undefined {
+		const keys = this.keys;
+		const whole = keys.matches(data, "tui.editor.cursorRight") || keys.matches(data, "tui.editor.cursorLineEnd");
+		const word = keys.matches(data, "tui.editor.cursorWordRight");
+		if (!whole && !word) return undefined;
+		const suffix = this.suggestion();
+		if (!suffix) return undefined;
+		return whole ? suffix : firstWord(suffix);
+	}
+}
+
+export function autosuggestEditorFactory(history: HistoryIndex, dim: (text: string) => string): EditorFactory {
+	return (tui, theme, keybindings) => new AutosuggestEditor(tui, theme, keybindings, history, dim);
+}

package/src/bash-complete.bash

@@ -0,0 +1,77 @@
+# Print bash completions for the command line in $1, one per line.
+# Run as: bash -i bash-complete.bash <command-line> [marker]   (loads ~/.bashrc)
+# Everything printed before the marker comes from user startup files and is ignored by the caller.
+# `bash -i` records script lines in history; never let them reach the user's history file.
+set +o history
+unset HISTFILE
+__pi_shell_bridge_line=$1
+printf '%s\n' "${2:-__PI_SHELL_BRIDGE_READY__}"
+
+__pi_shell_bridge_print() {
+	local item
+	while IFS= read -r item; do
+		[[ -z $item ]] && continue
+		if [[ $item != */ && -d ${item/#\~/$HOME} ]]; then item+=/; fi
+		printf '%s\n' "$item"
+	done
+}
+
+# Load bash-completion when the user's startup files did not.
+if ! declare -F _comp_load >/dev/null && ! declare -F _completion_loader >/dev/null; then
+	for __pi_shell_bridge_bc in \
+		"${BASH_COMPLETION_PATH:-}" \
+		"$HOME/.nix-profile/share/bash-completion/bash_completion" \
+		"/etc/profiles/per-user/$USER/share/bash-completion/bash_completion" \
+		/run/current-system/sw/share/bash-completion/bash_completion \
+		/opt/homebrew/share/bash-completion/bash_completion \
+		/usr/local/share/bash-completion/bash_completion \
+		/usr/share/bash-completion/bash_completion \
+		/etc/bash_completion; do
+		if [[ -n $__pi_shell_bridge_bc && -r $__pi_shell_bridge_bc ]]; then
+			# shellcheck disable=SC1090
+			source "$__pi_shell_bridge_bc" >/dev/null 2>&1
+			break
+		fi
+	done
+fi
+
+COMP_LINE=$__pi_shell_bridge_line
+COMP_POINT=${#COMP_LINE}
+COMP_TYPE=9
+COMP_KEY=9
+read -ra COMP_WORDS <<<"$COMP_LINE"
+if [[ -z $COMP_LINE || $COMP_LINE =~ [[:space:]]$ ]]; then COMP_WORDS+=(""); fi
+COMP_CWORD=$((${#COMP_WORDS[@]} - 1))
+__pi_shell_bridge_cur=${COMP_WORDS[COMP_CWORD]}
+
+if ((COMP_CWORD == 0)); then
+	compgen -A command -A alias -A function -A builtin -A keyword -- "$__pi_shell_bridge_cur" | sort -u
+	exit 0
+fi
+
+__pi_shell_bridge_cmd=${COMP_WORDS[0]}
+__pi_shell_bridge_spec=$(complete -p -- "$__pi_shell_bridge_cmd" 2>/dev/null)
+if [[ -z $__pi_shell_bridge_spec ]]; then
+	if declare -F _comp_load >/dev/null; then
+		_comp_load -- "$__pi_shell_bridge_cmd" >/dev/null 2>&1
+	elif declare -F _completion_loader >/dev/null; then
+		_completion_loader "$__pi_shell_bridge_cmd" >/dev/null 2>&1
+	fi
+	__pi_shell_bridge_spec=$(complete -p -- "$__pi_shell_bridge_cmd" 2>/dev/null)
+fi
+
+if [[ $__pi_shell_bridge_spec =~ [[:space:]]-F[[:space:]]+([^[:space:]]+) ]]; then
+	COMPREPLY=()
+	"${BASH_REMATCH[1]}" "$__pi_shell_bridge_cmd" "$__pi_shell_bridge_cur" "${COMP_WORDS[COMP_CWORD - 1]}" >/dev/null 2>&1
+	if ((${#COMPREPLY[@]} > 0)); then
+		printf '%s\n' "${COMPREPLY[@]}" | __pi_shell_bridge_print
+		exit 0
+	fi
+elif [[ -n $__pi_shell_bridge_spec ]]; then
+	__pi_shell_bridge_opts=${__pi_shell_bridge_spec#complete }
+	__pi_shell_bridge_opts=${__pi_shell_bridge_opts% *}
+	eval "compgen $__pi_shell_bridge_opts -- \"\$__pi_shell_bridge_cur\"" 2>/dev/null | __pi_shell_bridge_print
+	exit 0
+fi
+
+compgen -f -- "$__pi_shell_bridge_cur" | __pi_shell_bridge_print

package/src/completion.ts

@@ -0,0 +1,92 @@
+import type { AutocompleteItem, AutocompleteProvider } from "@earendil-works/pi-tui";
+import type { ShellBridgeConfig, ShellName } from "./config.ts";
+import { completeWith } from "./shells.ts";
+
+const MAX_ITEMS = 200;
+
+/** Text after `!` / `!!` and before the cursor, or undefined outside a bash-mode line. */
+export function shellCommandBeforeCursor(lines: string[], cursorLine: number, cursorCol: number): string | undefined {
+	if (cursorLine !== 0) return undefined;
+	const match = (lines[0] ?? "").slice(0, cursorCol).match(/^\s*!!?(.*)$/s);
+	return match?.[1]?.trimStart();
+}
+
+/** The word being completed: everything after the last unescaped, unquoted whitespace. */
+export function currentWord(command: string): string {
+	let start = 0;
+	let quote: string | undefined;
+	for (let index = 0; index < command.length; index++) {
+		const char = command[index];
+		if (char === "\\" && quote !== "'") {
+			index++;
+		} else if (quote) {
+			if (char === quote) quote = undefined;
+		} else if (char === "'" || char === '"') {
+			quote = char;
+		} else if (/\s/.test(char)) {
+			start = index + 1;
+		}
+	}
+	return command.slice(start);
+}
+
+export function applyShellCompletion(
+	lines: string[],
+	cursorLine: number,
+	cursorCol: number,
+	value: string,
+	prefix: string,
+): { lines: string[]; cursorLine: number; cursorCol: number } {
+	const line = lines[cursorLine] ?? "";
+	const before = line.slice(0, cursorCol - prefix.length);
+	const after = line.slice(cursorCol);
+	// Keep completing inside directories and `--option=` values; otherwise finish the word.
+	const suffix = /[/=:]$/.test(value) || /^\s/.test(after) ? "" : " ";
+	const next = [...lines];
+	next[cursorLine] = before + value + suffix + after;
+	return { lines: next, cursorLine, cursorCol: before.length + value.length + suffix.length };
+}
+
+export function createShellCompletionProvider(
+	current: AutocompleteProvider,
+	shell: ShellName,
+	getCwd: () => string,
+	config: ShellBridgeConfig,
+): AutocompleteProvider {
+	return {
+		triggerCharacters: current.triggerCharacters,
+
+		async getSuggestions(lines, cursorLine, cursorCol, options) {
+			const command = shellCommandBeforeCursor(lines, cursorLine, cursorCol);
+			// Spawn a shell only on an explicit Tab (force), never on every keystroke.
+			if (command === undefined || !options.force) {
+				return current.getSuggestions(lines, cursorLine, cursorCol, options);
+			}
+			let completions: Awaited<ReturnType<typeof completeWith>>;
+			try {
+				completions = await completeWith(shell, command, getCwd(), config, options.signal);
+			} catch {
+				return null;
+			}
+			if (options.signal.aborted || completions.length === 0) return null;
+			const items: AutocompleteItem[] = completions.slice(0, MAX_ITEMS).map((completion) => ({
+				value: completion.value,
+				label: completion.value,
+				description: completion.description,
+			}));
+			return { items, prefix: currentWord(command) };
+		},
+
+		applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+			if (shellCommandBeforeCursor(lines, cursorLine, cursorCol) === undefined) {
+				return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+			}
+			return applyShellCompletion(lines, cursorLine, cursorCol, item.value, prefix);
+		},
+
+		shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+			if (shellCommandBeforeCursor(lines, cursorLine, cursorCol) !== undefined) return true;
+			return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
+		},
+	};
+}

package/src/config.ts

@@ -0,0 +1,87 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export const SHELLS = ["fish", "zsh", "bash"] as const;
+export type ShellName = (typeof SHELLS)[number];
+
+export interface ShellBridgeConfig {
+	/** Completion backend for `!` lines: a shell name, "auto" ($SHELL first) or "off". */
+	completion: ShellName | "auto" | "off";
+	/** Shells whose history receives `!` commands: "auto" (shells with an existing history file), "off" or a list. */
+	history: ShellName[] | "auto" | "off";
+	/** Fish-style inline suggestions from the launching shell's history on `!` lines. */
+	autosuggest: boolean;
+	/** Load the user's shell startup files (aliases, custom completions, HISTFILE). */
+	loadUserConfig: boolean;
+	/** Regular expressions; matching commands are not written to history. */
+	ignore: string[];
+}
+
+export const DEFAULT_CONFIG: ShellBridgeConfig = {
+	completion: "auto",
+	history: "auto",
+	autosuggest: true,
+	loadUserConfig: true,
+	ignore: [],
+};
+
+export function configPath(): string {
+	return join(getAgentDir(), "pi-shell-bridge.json");
+}
+
+function isShell(value: unknown): value is ShellName {
+	return typeof value === "string" && (SHELLS as readonly string[]).includes(value);
+}
+
+function parseCompletion(value: unknown): ShellBridgeConfig["completion"] | undefined {
+	if (typeof value !== "string") return undefined;
+	const normalized = value.trim().toLowerCase();
+	return normalized === "auto" || normalized === "off" || isShell(normalized) ? normalized : undefined;
+}
+
+function parseHistory(value: unknown): ShellBridgeConfig["history"] | undefined {
+	if (typeof value === "string") {
+		const normalized = value.trim().toLowerCase();
+		if (normalized === "auto" || normalized === "off") return normalized;
+		value = normalized.split(",");
+	}
+	if (!Array.isArray(value)) return undefined;
+	const shells = value.map((item) => (typeof item === "string" ? item.trim().toLowerCase() : item)).filter(isShell);
+	return [...new Set(shells)];
+}
+
+function parseBoolean(value: unknown): boolean | undefined {
+	if (typeof value === "boolean") return value;
+	if (typeof value !== "string") return undefined;
+	const normalized = value.trim().toLowerCase();
+	if (["1", "true", "on", "yes"].includes(normalized)) return true;
+	if (["0", "false", "off", "no"].includes(normalized)) return false;
+	return undefined;
+}
+
+export function parseConfig(raw: unknown, env: NodeJS.ProcessEnv = process.env): ShellBridgeConfig {
+	const object = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {};
+	return {
+		completion:
+			parseCompletion(env.PI_SHELL_BRIDGE_COMPLETION) ?? parseCompletion(object.completion) ?? DEFAULT_CONFIG.completion,
+		history: parseHistory(env.PI_SHELL_BRIDGE_HISTORY) ?? parseHistory(object.history) ?? DEFAULT_CONFIG.history,
+		autosuggest:
+			parseBoolean(env.PI_SHELL_BRIDGE_AUTOSUGGEST) ?? parseBoolean(object.autosuggest) ?? DEFAULT_CONFIG.autosuggest,
+		loadUserConfig:
+			typeof object.loadUserConfig === "boolean" ? object.loadUserConfig : DEFAULT_CONFIG.loadUserConfig,
+		ignore: Array.isArray(object.ignore) ? object.ignore.filter((item): item is string => typeof item === "string") : [],
+	};
+}
+
+export function loadConfig(): { config: ShellBridgeConfig; error?: string } {
+	let raw: unknown;
+	try {
+		raw = JSON.parse(readFileSync(configPath(), "utf8"));
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		const message = code === "ENOENT" ? undefined : `${configPath()}: ${(error as Error).message}`;
+		return { config: parseConfig(undefined), error: message };
+	}
+	return { config: parseConfig(raw) };
+}

package/src/exec.ts

@@ -0,0 +1,72 @@
+import { spawn } from "node:child_process";
+
+export interface RunOptions {
+	cwd?: string;
+	timeout?: number;
+	signal?: AbortSignal;
+}
+
+export interface RunResult {
+	stdout: string;
+	stderr: string;
+	code: number;
+	killed: boolean;
+}
+
+/**
+ * Run a helper shell in its own session (setsid) with no controlling terminal.
+ *
+ * Interactive shells (`bash -i`, `zsh -i`) enable job control and move themselves into the terminal's
+ * foreground process group. Started with Pi's controlling terminal, they push Pi into the background and
+ * Pi is stopped by SIGTTIN/SIGTTOU ("fish: Job 1, 'pi' has stopped"). A new session has no terminal to take.
+ */
+export function run(command: string, args: string[], options: RunOptions = {}): Promise<RunResult> {
+	return new Promise((resolve) => {
+		let stdout = "";
+		let stderr = "";
+		let killed = false;
+		let settled = false;
+		let timer: NodeJS.Timeout | undefined;
+
+		let child: ReturnType<typeof spawn>;
+		try {
+			child = spawn(command, args, {
+				cwd: options.cwd,
+				detached: true,
+				stdio: ["ignore", "pipe", "pipe"],
+			});
+		} catch (error) {
+			resolve({ stdout, stderr: (error as Error).message, code: 1, killed });
+			return;
+		}
+
+		const kill = () => {
+			if (killed || child.pid === undefined) return;
+			killed = true;
+			try {
+				process.kill(-child.pid, "SIGKILL"); // whole process group, including zpty children
+			} catch {
+				child.kill("SIGKILL");
+			}
+		};
+		const finish = (code: number) => {
+			if (settled) return;
+			settled = true;
+			if (timer) clearTimeout(timer);
+			options.signal?.removeEventListener("abort", kill);
+			resolve({ stdout, stderr, code, killed });
+		};
+
+		if (options.signal?.aborted) kill();
+		else options.signal?.addEventListener("abort", kill, { once: true });
+		if (options.timeout && options.timeout > 0) timer = setTimeout(kill, options.timeout);
+
+		child.stdout?.on("data", (data: Buffer) => (stdout += data.toString()));
+		child.stderr?.on("data", (data: Buffer) => (stderr += data.toString()));
+		child.on("error", (error) => {
+			stderr += error.message;
+			finish(1);
+		});
+		child.on("close", (code) => finish(code ?? 1));
+	});
+}

package/src/history.ts

@@ -0,0 +1,161 @@
+import { closeSync, fstatSync, openSync, readSync, statSync } from "node:fs";
+import type { ShellName } from "./config.ts";
+
+/** Read at most this much from the end of a history file. */
+const MAX_READ_BYTES = 8 * 1024 * 1024;
+/** Re-check the history file's mtime at most this often. */
+const RECHECK_MS = 1_000;
+
+function readTail(file: string): Buffer {
+	const fd = openSync(file, "r");
+	try {
+		const size = fstatSync(fd).size;
+		const length = Math.min(size, MAX_READ_BYTES);
+		const buffer = Buffer.alloc(length);
+		readSync(fd, buffer, 0, length, size - length);
+		return buffer;
+	} finally {
+		closeSync(fd);
+	}
+}
+
+/** Undo zsh's metafication: 0x83 (Meta) followed by a byte XOR 0x20. */
+export function unmetafy(buffer: Buffer): Buffer {
+	if (!buffer.includes(0x83)) return buffer;
+	const out = Buffer.alloc(buffer.length);
+	let length = 0;
+	for (let index = 0; index < buffer.length; index++) {
+		const byte = buffer[index];
+		if (byte === 0x83 && index + 1 < buffer.length) out[length++] = buffer[++index] ^ 0x20;
+		else out[length++] = byte;
+	}
+	return out.subarray(0, length);
+}
+
+/** fish_history: YAML-like `- cmd: <escaped>` entries, oldest first. */
+export function parseFish(text: string): string[] {
+	const commands: string[] = [];
+	for (const line of text.split("\n")) {
+		if (!line.startsWith("- cmd: ")) continue;
+		commands.push(line.slice(7).replace(/\\(\\|n)/g, (_match, char: string) => (char === "n" ? "\n" : "\\")));
+	}
+	return commands;
+}
+
+/** zsh history (plain or EXTENDED_HISTORY), oldest first; continuation lines end with a backslash. */
+export function parseZsh(text: string): string[] {
+	const commands: string[] = [];
+	let pending: string | undefined;
+	for (const raw of text.split("\n")) {
+		let line = raw;
+		if (pending === undefined) {
+			const extended = line.match(/^: \d+:\d+;(.*)$/s);
+			if (extended) line = extended[1];
+			pending = "";
+		}
+		if (line.endsWith("\\")) {
+			pending += `${line.slice(0, -1)}\n`;
+			continue;
+		}
+		pending += line;
+		if (pending) commands.push(pending);
+		pending = undefined;
+	}
+	if (pending) commands.push(pending.replace(/\n$/, ""));
+	return commands;
+}
+
+/** bash history, oldest first; `#<epoch>` lines are HISTTIMEFORMAT timestamps. */
+export function parseBash(text: string): string[] {
+	return text.split("\n").filter((line) => line.length > 0 && !/^#\d{9,}$/.test(line));
+}
+
+export function parseHistory(shell: ShellName, buffer: Buffer): string[] {
+	switch (shell) {
+		case "fish":
+			return parseFish(buffer.toString("utf8"));
+		case "zsh":
+			return parseZsh(unmetafy(buffer).toString("utf8"));
+		case "bash":
+			return parseBash(buffer.toString("utf8"));
+	}
+}
+
+/** Only single-line commands without control characters can be drawn inline. */
+const UNSUGGESTABLE = /[\u0000-\u001f\u007f]/;
+
+/** Single-line commands, newest first, without duplicates. */
+function newestFirst(commands: string[]): string[] {
+	const seen = new Set<string>();
+	const result: string[] = [];
+	for (let index = commands.length - 1; index >= 0; index--) {
+		const command = commands[index].trim();
+		if (!command || UNSUGGESTABLE.test(command) || seen.has(command)) continue;
+		seen.add(command);
+		result.push(command);
+	}
+	return result;
+}
+
+/**
+ * Commands for fish-style autosuggestions: `!` commands of this Pi session first, then the shell's history file.
+ * The file is re-read only when its mtime changes, so lookups stay cheap enough for every keystroke.
+ */
+export class HistoryIndex {
+	private session: string[] = [];
+	private fromFile: string[] = [];
+	private shell: ShellName | undefined;
+	private file: string | undefined;
+	private mtimeMs = -1;
+	private checkedAt = 0;
+	private cache: { prefix: string; version: number; suffix: string | undefined } | undefined;
+	private version = 0;
+
+	setSource(shell: ShellName | undefined, file: string | undefined): void {
+		this.shell = shell;
+		this.file = file;
+		this.mtimeMs = -1;
+		this.checkedAt = 0;
+		this.refresh();
+	}
+
+	/** Record a `!` command run in this session (shown before the file catches up). */
+	remember(command: string): void {
+		const trimmed = command.trim();
+		if (!trimmed || UNSUGGESTABLE.test(trimmed)) return;
+		this.session = [trimmed, ...this.session.filter((item) => item !== trimmed)];
+		this.version++;
+	}
+
+	private refresh(): void {
+		const now = Date.now();
+		if (!this.shell || !this.file || now - this.checkedAt < RECHECK_MS) return;
+		this.checkedAt = now;
+		try {
+			const mtimeMs = statSync(this.file).mtimeMs;
+			if (mtimeMs === this.mtimeMs) return;
+			this.mtimeMs = mtimeMs;
+			this.fromFile = newestFirst(parseHistory(this.shell, readTail(this.file)));
+		} catch {
+			this.fromFile = [];
+		}
+		this.version++;
+	}
+
+	/** The text that completes `prefix` to the newest matching command, or undefined. */
+	suggest(prefix: string): string | undefined {
+		if (!prefix.trim()) return undefined;
+		this.refresh();
+		if (this.cache?.prefix === prefix && this.cache.version === this.version) return this.cache.suffix;
+		let suffix: string | undefined;
+		for (const list of [this.session, this.fromFile]) {
+			const match = list.find((command) => command.length > prefix.length && command.startsWith(prefix));
+			if (match) {
+				suffix = match.slice(prefix.length);
+				break;
+			}
+		}
+		this.cache = { prefix, version: this.version, suffix };
+		return suffix;
+	}
+}

package/src/index.ts

@@ -0,0 +1,95 @@
+// pi-shell-bridge: shell completion and shell history for Pi's `!` / `!!` commands.
+//
+// - Tab on a `!cmd` line asks fish, zsh or bash for completions, reusing the user's shell setup.
+// - Each `!` command is appended to the fish / zsh / bash history files the user keeps.
+// - Fish-style autosuggestions: the newest matching history command is shown dimmed after the cursor.
+// Commands still run through Pi's built-in bash; this extension does not change execution.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { autosuggestEditorFactory } from "./autosuggest.ts";
+import { createShellCompletionProvider } from "./completion.ts";
+import { loadConfig, type ShellName } from "./config.ts";
+import { HistoryIndex } from "./history.ts";
+import {
+	appendHistory,
+	historyFile,
+	resolveCompletionShell,
+	resolveHistoryShells,
+	suggestionShell,
+} from "./shells.ts";
+
+export default function piShellBridge(pi: ExtensionAPI): void {
+	const { config, error } = loadConfig();
+	const ignore = config.ignore.flatMap((pattern) => {
+		try {
+			return [new RegExp(pattern)];
+		} catch {
+			return [];
+		}
+	});
+	let historyShells: Promise<ShellName[]> | undefined;
+	const suggestions = new HistoryIndex();
+	let suggestionSource: Promise<void> | undefined;
+	let editorFactory: ReturnType<typeof autosuggestEditorFactory> | undefined;
+	let cwd = process.cwd();
+
+	const warn = (ctx: { ui: { notify(message: string, type?: "info" | "warning" | "error"): void } }, error: unknown) => {
+		try {
+			ctx.ui.notify(`pi-shell-bridge: ${error instanceof Error ? error.message : String(error)}`, "warning");
+		} catch {
+			// The UI may already be gone; never let the bridge take Pi down.
+		}
+	};
+	const shellsForHistory = () =>
+		(historyShells ??= resolveHistoryShells(config).catch((): ShellName[] => []));
+
+	pi.on("session_start", async (_event, ctx) => {
+		try {
+			cwd = ctx.cwd;
+			if (error) warn(ctx, error);
+			const shell = resolveCompletionShell(config);
+			if (shell) {
+				ctx.ui.addAutocompleteProvider((current) =>
+					createShellCompletionProvider(current, shell, () => cwd, config),
+				);
+			}
+			// Probe history locations in the background so the first command is not delayed.
+			void shellsForHistory();
+			if (config.autosuggest) {
+				const current = ctx.ui.getEditorComponent();
+				// Another extension owns the editor: leave it alone rather than replacing it.
+				if (current === undefined || current === editorFactory) {
+					editorFactory ??= autosuggestEditorFactory(suggestions, (text) => ctx.ui.theme.fg("dim", text));
+					if (current === undefined) ctx.ui.setEditorComponent(editorFactory);
+					const shell = suggestionShell(config);
+					suggestionSource ??= (shell ? historyFile(shell, config) : Promise.resolve(undefined))
+						.then((file) => suggestions.setSource(shell, file))
+						.catch(() => undefined);
+				}
+			}
+		} catch (caught) {
+			warn(ctx, caught);
+		}
+	});
+
+	pi.on("user_bash", async (event, ctx) => {
+		try {
+			cwd = event.cwd || cwd;
+			const command = event.command.trim();
+			if (!command || ignore.some((pattern) => pattern.test(command))) return undefined;
+			suggestions.remember(command);
+			void shellsForHistory()
+				.then((shells) => Promise.allSettled(shells.map((shell) => appendHistory(shell, command, config))))
+				.then((results) => {
+					const failures = results
+						.filter((result): result is PromiseRejectedResult => result.status === "rejected")
+						.map((result) => (result.reason instanceof Error ? result.reason.message : String(result.reason)));
+					if (failures.length > 0) warn(ctx, failures.join("; "));
+				})
+				.catch((caught: unknown) => warn(ctx, caught));
+		} catch (caught) {
+			warn(ctx, caught);
+		}
+		return undefined; // let Pi run the command as usual
+	});
+}

package/src/shells.ts

@@ -0,0 +1,340 @@
+import { accessSync, closeSync, constants, existsSync, fstatSync, openSync, readSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, delimiter, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+import { SHELLS, type ShellBridgeConfig, type ShellName } from "./config.ts";
+import { type RunResult, run } from "./exec.ts";
+
+const MARKER = "__PI_SHELL_BRIDGE_READY__";
+const COMPLETE_TIMEOUT_MS = 5_000;
+const HISTORY_TIMEOUT_MS = 5_000;
+const PROBE_TIMEOUT_MS = 5_000;
+
+const BASH_COMPLETE_SCRIPT = fileURLToPath(new URL("./bash-complete.bash", import.meta.url));
+const ZSH_CAPTURE_SCRIPT = fileURLToPath(new URL("./zsh-capture.zsh", import.meta.url));
+
+export interface Completion {
+	value: string;
+	description?: string;
+}
+
+interface HistoryTarget {
+	file: string;
+	/** bash: HISTTIMEFORMAT value (undefined when unset); zsh: "1" when EXTENDED_HISTORY is set. */
+	format?: string;
+}
+
+const binaryCache = new Map<ShellName, boolean>();
+
+export function isInstalled(shell: ShellName): boolean {
+	const cached = binaryCache.get(shell);
+	if (cached !== undefined) return cached;
+	const found = (process.env.PATH ?? "").split(delimiter).some((dir) => {
+		if (!dir) return false;
+		try {
+			accessSync(join(dir, shell), constants.X_OK);
+			return true;
+		} catch {
+			return false;
+		}
+	});
+	binaryCache.set(shell, found);
+	return found;
+}
+
+function asShell(name: string | undefined): ShellName | undefined {
+	const normalized = basename(name ?? "").replace(/^-/, ""); // login shells show up as "-zsh"
+	return (SHELLS as readonly string[]).includes(normalized) ? (normalized as ShellName) : undefined;
+}
+
+const MAX_ANCESTORS = 16;
+/** Interactive shells we recognise as "the shell Pi was launched from", supported or not. */
+const KNOWN_SHELLS = new Set([
+	...SHELLS,
+	"sh", "dash", "ash", "ksh", "mksh", "oksh", "pdksh", "csh", "tcsh", "nu", "xonsh", "elvish",
+	"pwsh", "powershell", "ion", "oil", "osh", "ysh", "murex", "rc", "es", "yash", "posh",
+]);
+
+export interface LaunchingShell {
+	/** Executable name of the nearest shell ancestor, e.g. "fish" or "nu"; undefined when none was found. */
+	name?: string;
+	/** The same shell when pi-shell-bridge supports it. */
+	shell?: ShellName;
+}
+
+let launchingShell: LaunchingShell | undefined;
+
+/** The nearest shell ancestor of this Pi process, i.e. the shell Pi was started from. Never throws. */
+export function detectLaunchingShell(): LaunchingShell {
+	if (launchingShell) return launchingShell;
+	launchingShell = {};
+	let pid = process.ppid;
+	try {
+		for (let depth = 0; depth < MAX_ANCESTORS && pid > 1; depth++) {
+			const output = execFileSync("ps", ["-o", "ppid=,comm=", "-p", String(pid)], {
+				encoding: "utf8",
+				stdio: ["ignore", "pipe", "ignore"],
+				timeout: 1_000,
+			}).trim();
+			const match = output.match(/^(\d+)\s+(.+)$/);
+			if (!match) break;
+			const name = basename(match[2].trim()).replace(/^-/, "");
+			if (KNOWN_SHELLS.has(name)) {
+				launchingShell = { name, shell: asShell(name) };
+				break;
+			}
+			pid = Number(match[1]);
+		}
+	} catch {
+		// `ps` missing or failing: behave as if no launching shell was found.
+	}
+	return launchingShell;
+}
+
+/**
+ * The shell `auto` refers to: the shell Pi was launched from. Only when no shell ancestor is found
+ * (e.g. Pi started directly by a terminal or IDE) does $SHELL stand in. An unsupported launching shell
+ * (nu, sh, …) yields undefined.
+ */
+export function autoShell(): ShellName | undefined {
+	const launching = detectLaunchingShell();
+	const shell = launching.name ? launching.shell : asShell(process.env.SHELL);
+	return shell && isInstalled(shell) ? shell : undefined;
+}
+
+export function resolveCompletionShell(config: ShellBridgeConfig): ShellName | undefined {
+	if (config.completion === "off") return undefined;
+	if (config.completion !== "auto") return isInstalled(config.completion) ? config.completion : undefined;
+	// Completion only runs on Tab and never touches history, so any installed shell is a fine fallback.
+	const login = asShell(process.env.SHELL);
+	return autoShell() ?? (login && isInstalled(login) ? login : undefined) ?? SHELLS.find(isInstalled);
+}
+
+function afterMarker(stdout: string): string[] {
+	const index = stdout.lastIndexOf(`${MARKER}\n`);
+	const body = index === -1 ? "" : stdout.slice(index + MARKER.length + 1);
+	return body.split("\n").map((line) => line.replace(/\r$/, ""));
+}
+
+export function parseCompletions(lines: string[]): Completion[] {
+	const byValue = new Map<string, Completion>();
+	for (const line of lines) {
+		if (!line.trim()) continue;
+		const tab = line.indexOf("\t");
+		const value = tab === -1 ? line : line.slice(0, tab);
+		const description = tab === -1 ? undefined : line.slice(tab + 1).trim() || undefined;
+		const existing = byValue.get(value);
+		if (!existing) byValue.set(value, { value, description });
+		else if (!existing.description && description) existing.description = description;
+	}
+	return [...byValue.values()];
+}
+
+/** Ask a shell to complete `commandLine` (text before the cursor) in `cwd`. */
+export async function completeWith(
+	shell: ShellName,
+	commandLine: string,
+	cwd: string,
+	config: ShellBridgeConfig,
+	signal: AbortSignal,
+): Promise<Completion[]> {
+	const options = { cwd, signal, timeout: COMPLETE_TIMEOUT_MS };
+	let result: RunResult;
+	let lines: string[];
+	switch (shell) {
+		case "fish": {
+			const args = config.loadUserConfig ? [] : ["--no-config"];
+			result = await run(
+				"fish",
+				[...args, "-c", `echo ${MARKER}; complete -C -- "$argv[1]"`, commandLine],
+				options,
+			);
+			lines = afterMarker(result.stdout);
+			break;
+		}
+		case "bash": {
+			const args = config.loadUserConfig ? ["-i"] : ["--norc", "--noprofile"];
+			result = await run("bash", [...args, BASH_COMPLETE_SCRIPT, commandLine, MARKER], options);
+			lines = afterMarker(result.stdout);
+			break;
+		}
+		case "zsh": {
+			const args = [ZSH_CAPTURE_SCRIPT, commandLine];
+			if (!config.loadUserConfig) args.push("no-rc");
+			result = await run("zsh", ["-f", ...args], options);
+			lines = result.stdout.split("\n");
+			break;
+		}
+	}
+	if (result.killed) return [];
+	return parseCompletions(lines);
+}
+
+const targetCache = new Map<ShellName, Promise<HistoryTarget | undefined>>();
+
+function fileExists(file: string): boolean {
+	try {
+		return statSync(file).isFile();
+	} catch {
+		return false;
+	}
+}
+
+/** Detect EXTENDED_HISTORY (": <epoch>:<duration>;command") from the tail of an existing zsh history file. */
+function sniffZshExtended(file: string): boolean {
+	if (!fileExists(file)) return false;
+	try {
+		const fd = openSync(file, "r");
+		try {
+			const size = fstatSync(fd).size;
+			const length = Math.min(size, 4096);
+			const buffer = Buffer.alloc(length);
+			readSync(fd, buffer, 0, length, size - length);
+			return /^: \d+:\d+;/m.test(buffer.toString("latin1"));
+		} finally {
+			closeSync(fd);
+		}
+	} catch {
+		return false;
+	}
+}
+
+async function probeHistoryTarget(
+	shell: ShellName,
+	config: ShellBridgeConfig,
+): Promise<HistoryTarget | undefined> {
+	const home = homedir();
+	switch (shell) {
+		case "fish": {
+			// fish owns its history file format and location (fish_history); `history append` handles both.
+			const dataHome = process.env.XDG_DATA_HOME || join(home, ".local", "share");
+			return { file: join(dataHome, "fish", "fish_history") };
+		}
+		case "bash": {
+			let file = process.env.HISTFILE || join(home, ".bash_history");
+			let format: string | undefined = process.env.HISTTIMEFORMAT;
+			if (config.loadUserConfig) {
+				const result = await run(
+					"bash",
+					["-i", "-c", `printf '%s\\n' ${MARKER} "$HISTFILE" "\${HISTTIMEFORMAT-__unset__}"`],
+					{ cwd: home, timeout: PROBE_TIMEOUT_MS },
+				);
+				const [histfile, timeFormat] = afterMarker(result.stdout);
+				if (histfile) file = histfile;
+				if (timeFormat !== undefined) format = timeFormat === "__unset__" ? undefined : timeFormat;
+			}
+			return { file, format };
+		}
+		case "zsh": {
+			// zsh has no default HISTFILE: without one the user does not keep history.
+			let file = process.env.HISTFILE;
+			let format: string | undefined;
+			if (config.loadUserConfig) {
+				const result = await run(
+					"zsh",
+					["-i", "-c", `print -rl -- ${MARKER} "$HISTFILE"; [[ -o extendedhistory ]] && print 1 || print 0`],
+					{ cwd: home, timeout: PROBE_TIMEOUT_MS },
+				);
+				const [histfile, extended] = afterMarker(result.stdout);
+				if (histfile) file = histfile;
+				format = extended;
+			}
+			if (!file) return undefined;
+			format ??= sniffZshExtended(file) ? "1" : "0";
+			return { file, format };
+		}
+	}
+}
+
+function historyTarget(shell: ShellName, config: ShellBridgeConfig): Promise<HistoryTarget | undefined> {
+	let target = targetCache.get(shell);
+	if (!target) {
+		target = probeHistoryTarget(shell, config).catch(() => undefined);
+		targetCache.set(shell, target);
+	}
+	return target;
+}
+
+/** The history file of `shell` (probed once per Pi process), or undefined when it keeps none. */
+export async function historyFile(shell: ShellName, config: ShellBridgeConfig): Promise<string | undefined> {
+	return (await historyTarget(shell, config))?.file;
+}
+
+/** The shell whose history feeds autosuggestions: the launching shell, else the first configured history shell. */
+export function suggestionShell(config: ShellBridgeConfig): ShellName | undefined {
+	return autoShell() ?? (Array.isArray(config.history) ? config.history.find(isInstalled) : undefined);
+}
+
+/** Resolve which shells receive history; probes run once per Pi process. */
+export async function resolveHistoryShells(config: ShellBridgeConfig): Promise<ShellName[]> {
+	if (config.history === "off") return [];
+	const auto = autoShell();
+	const candidates = config.history === "auto" ? (auto ? [auto] : []) : config.history.filter(isInstalled);
+	const resolved = await Promise.all(
+		candidates.map(async (shell) => {
+			const target = await historyTarget(shell, config);
+			if (!target) return undefined;
+			// In auto mode only write to the launching shell, and only when the user keeps history for it.
+			return config.history !== "auto" || existsSync(target.file) ? shell : undefined;
+		}),
+	);
+	return resolved.filter((shell): shell is ShellName => shell !== undefined);
+}
+
+/** Append one command to a shell's history using that shell's own history writer. */
+export async function appendHistory(
+	shell: ShellName,
+	command: string,
+	config: ShellBridgeConfig,
+): Promise<void> {
+	const target = await historyTarget(shell, config);
+	if (!target) return;
+	const options = { timeout: HISTORY_TIMEOUT_MS };
+	let result: RunResult;
+	switch (shell) {
+		case "fish": {
+			// --no-config disables history persistence, so fish must load its normal configuration.
+			result = await run("fish", ["-c", 'history append -- "$argv[1]"', command], options);
+			break;
+		}
+		case "bash": {
+			result = await run(
+				"bash",
+				[
+					"--norc",
+					"--noprofile",
+					"-c",
+					'HISTFILE=$1; if [ "$2" != __unset__ ]; then HISTTIMEFORMAT=$2; fi; set -o history; history -s -- "$3"; history -a',
+					"pi-shell-bridge",
+					target.file,
+					target.format ?? "__unset__",
+					command,
+				],
+				options,
+			);
+			break;
+		}
+		case "zsh": {
+			// Interactive (-i) so history is active; HISTFILE is unset afterwards so exit does not rewrite the file.
+			result = await run(
+				"zsh",
+				[
+					"-f",
+					"-i",
+					"-c",
+					'[[ $2 == 1 ]] && setopt extended_history; HISTFILE=$1; HISTSIZE=100; SAVEHIST=1000000; print -s -- "$3"; fc -AI; unset HISTFILE',
+					"pi-shell-bridge",
+					target.file,
+					target.format ?? "0",
+					command,
+				],
+				options,
+			);
+			break;
+		}
+	}
+	if (result.code !== 0 || result.killed) {
+		throw new Error(`${shell}: ${result.stderr.trim() || (result.killed ? "timed out" : `exit ${result.code}`)}`);
+	}
+}

package/src/zsh-capture.zsh

@@ -0,0 +1,95 @@
+# Print zsh completions for a command line without a terminal, one per line ("value<TAB>description").
+# Usage: zsh -f zsh-capture.zsh <command-line> [no-rc]
+#
+# Uses the zpty technique popularised by Valodim/zsh-capture-completion (MIT): an interactive zsh runs
+# in a pseudo terminal, `compadd` is wrapped to print every match, and Tab is sent after the command line.
+# The interactive zsh loads the user's ~/.zshenv and ~/.zshrc through a temporary ZDOTDIR so that no
+# setup command is typed into the line editor, and HISTFILE is unset so nothing reaches the history file.
+zmodload zsh/zpty || exit 1
+
+local line_to_complete=$1
+local no_rc=$2
+local dir=$(mktemp -d "${TMPDIR:-/tmp}/pi-shell-bridge.XXXXXX") || exit 1
+trap 'rm -rf -- ${(q)dir}; zpty -d pi_shell_bridge 2>/dev/null' EXIT
+
+local user_zdotdir=${ZDOTDIR:-$HOME}
+
+if [[ $no_rc != no-rc ]]; then
+  cat >| $dir/.zshenv <<ZSHENV
+ZDOTDIR=${(q)user_zdotdir}
+[[ -r \$ZDOTDIR/.zshenv ]] && source \$ZDOTDIR/.zshenv
+__pi_shell_bridge_user_zdotdir=\$ZDOTDIR
+ZDOTDIR=${(q)dir}
+ZSHENV
+fi
+
+cat >| $dir/.zshrc <<ZSHRC
+unset HISTFILE
+if [[ -n \$__pi_shell_bridge_user_zdotdir ]]; then
+  ZDOTDIR=\$__pi_shell_bridge_user_zdotdir
+  [[ -r \$ZDOTDIR/.zshrc ]] && source \$ZDOTDIR/.zshrc
+fi
+source ${(q)dir}/setup.zsh
+ZSHRC
+
+cat >| $dir/setup.zsh <<'SETUP'
+unset HISTFILE
+PROMPT= RPROMPT= PS2=
+unsetopt zle_bracketed_paste 2>/dev/null
+(( $+functions[compdef] )) || { autoload -Uz compinit && compinit -C -d "${TMPDIR:-/tmp}/pi-shell-bridge-zcompdump-$UID"; }
+bindkey '^M' undefined
+bindkey '^J' undefined
+bindkey '^I' complete-word
+__pi_shell_bridge_null() { print -rn -- $'\0\r\n' }
+compprefuncs=( __pi_shell_bridge_null )
+comppostfuncs=( __pi_shell_bridge_null exit )
+zstyle ':completion:*' list-grouped false
+zstyle ':completion:*' list-separator ''
+zstyle ':completion:*' menu no
+zmodload zsh/zutil
+compadd() {
+  if [[ ${@[1,(i)(-|--)]} == *-(O|A|D)\ * ]]; then
+    builtin compadd "$@"
+    return $?
+  fi
+  typeset -a __hits __dscr __tmp
+  if (( $@[(I)-d] )); then
+    __tmp=${@[$[${@[(i)-d]}+1]]}
+    if [[ $__tmp == \(* ]]; then eval "__dscr=$__tmp"; else __dscr=( "${(@P)__tmp}" ); fi
+  fi
+  builtin compadd -A __hits -D __dscr "$@"
+  setopt localoptions norcexpandparam extendedglob
+  typeset -A apre hpre hsuf asuf
+  zparseopts -E P:=apre p:=hpre S:=asuf s:=hsuf
+  integer dirsuf=0
+  if [[ -z $hsuf && "${${@//-default-/}% -# *}" == *-[[:alnum:]]#f* ]]; then dirsuf=1; fi
+  [[ -n $__hits ]] || return
+  local dsuf dscr i __path
+  for i in {1..$#__hits}; do
+    __path=$hpre$__hits[$i]
+    (( dirsuf )) && [[ -d ${~__path} ]] && dsuf=/ || dsuf=
+    (( $#__dscr >= $i )) && dscr=$'\t'${${__dscr[$i]}##$__hits[$i] #} || dscr=
+    print -r -- "$IPREFIX$apre$hpre$__hits[$i]$dsuf$hsuf$asuf$dscr"
+  done
+}
+print -r -- __PI_SHELL_BRIDGE_READY__
+SETUP
+
+export ZDOTDIR=$dir
+zpty pi_shell_bridge zsh -i
+local line
+while zpty -r pi_shell_bridge line; do
+  [[ $line == __PI_SHELL_BRIDGE_READY__* ]] && break
+done
+zpty -w -n pi_shell_bridge "$line_to_complete"$'\t'
+
+integer seen=0
+while zpty -r pi_shell_bridge line; do
+  if [[ $line == *$'\0\r'* ]]; then
+    (( seen++ )) && exit 0
+    continue
+  fi
+  line=${line//[$'\r\n']/}
+  (( seen )) && [[ -n $line ]] && print -r -- "$line"
+done
+exit 2