gentle-pi 3.4.0 → 3.5.1

package/README.md

@@ -12,8 +12,8 @@
   <a href="https://www.npmjs.com/package/gentle-pi"><img src="https://img.shields.io/npm/v/gentle-pi?style=for-the-badge&labelColor=1A1218&color=F095C8" alt="npm"></a>
   <a href="https://pi.dev/packages/gentle-pi"><img src="https://img.shields.io/badge/Pi-native-F095C8?style=for-the-badge&labelColor=1A1218" alt="Pi-native package"></a>
   <a href="LICENSE"><img src="https://img.shields.io/npm/l/gentle-pi?style=for-the-badge&labelColor=1A1218&color=F095C8" alt="MIT license"></a>
-  <a href="https://github.com/Gentleman-Programming/gentle-pi/stargazers"><img src="https://img.shields.io/github/stars/Gentleman-Programming/gentle-pi?style=for-the-badge&labelColor=1A1218&color=F095C8" alt="GitHub stars"></a>
-  <a href="https://github.com/Gentleman-Programming/gentle-pi"><img src="https://img.shields.io/github/last-commit/Gentleman-Programming/gentle-pi?style=for-the-badge&labelColor=1A1218&color=D7A0B8" alt="Last commit"></a>
+  <a href="https://github.com/Gentleman-Programming/gentle-shell/stargazers"><img src="https://img.shields.io/github/stars/Gentleman-Programming/gentle-shell?style=for-the-badge&labelColor=1A1218&color=F095C8" alt="GitHub stars"></a>
+  <a href="https://github.com/Gentleman-Programming/gentle-shell"><img src="https://img.shields.io/github/last-commit/Gentleman-Programming/gentle-shell?style=for-the-badge&labelColor=1A1218&color=D7A0B8" alt="Last commit"></a>
 </p>
 
 <p align="center">
@@ -37,7 +37,7 @@
 <p align="center"><strong>BUILT FOR PI</strong> &nbsp;·&nbsp; Coding-agent workspace &nbsp;·&nbsp; Focused agents &nbsp;·&nbsp; ODD</p>
 
 <p align="center">
-  <a href="https://github.com/Gentleman-Programming/gentle-pi/stargazers"><strong>★ Star gentle-shell on GitHub</strong></a>
+  <a href="https://github.com/Gentleman-Programming/gentle-shell/stargazers"><strong>★ Star gentle-shell on GitHub</strong></a>
 </p>
 
 <div align="center">
@@ -185,13 +185,13 @@ Extension commands are only useful if you can find them. `alt+k` opens a curated
 
 ---
 
-### What's new in v2.6.0
+### What's new in v3.5
 
-The [v2.6.0 release](https://github.com/Gentleman-Programming/gentle-pi/releases/tag/v2.6.0) brings a more persistent, inspectable Pi workspace:
+The [v3.5.1 release](https://github.com/Gentleman-Programming/gentle-shell/releases/tag/v3.5.1) makes Gentle Shell runnable on its own:
 
-- **Shell:** `/gentle:changes` groups captured write/edit changes from the current agent session and its subagents, without startup repository scans; fullscreen navigation, sidebars, and mouse support stay available. See the [capture limits and shell-command coverage](docs/gentle-shell.md#what-appears-in-changes).
-- **Agents and profiles:** the Agents view shows orchestrator/session hierarchy, retained completion, abort, and lost-exit history, parent-child handoff, and model, effort, and usage observability. Named `/gentle:profiles` atomically route the orchestrator independently from packaged and review roles; applying one replaces the routing of every agent, a repository can be pinned to a profile with `p` so its subagent launches stop following the globally active profile, and the panel shows the routing the runtime actually uses even when `models.json` is sparse.
-- **Control and recovery:** native SDD requires parent-confirmed preflight; native review supports intended-untracked selection, consent, and provider continuations. Subsystems install with explicit recovery guidance when npm lifecycle scripts were skipped; Pi Git installs are recognized globally; custom ask responses are opt-in. Windows keeps child consoles hidden and fixes ownership mode; Gentle Todo keeps the next pending task visible when collapsed.
+- **Standalone launcher:** `npm i -g gentle-pi` installs `gentle-shell`, which opens Pi with the Gentle Shell package loaded from its own home (`~/.gentle-shell/agent`) or, with `--link`, from your existing `~/.pi/agent`; `gentle-shell install npm:<pkg>` and the other pi subcommands run against the selected home. A bundled or `PATH` pi is used, never a modified one.
+- **Link mode take-over:** when `~/.pi/agent` already declares gentle-pi as a path package, the launcher takes over extension loading (`--no-extensions` plus explicit `-e` for every other declared package and loose extension) so tools never register twice.
+- **Interactive RPC hosts:** with `GENTLE_SHELL_INTERACTIVE_HOST=1` and `--mode rpc`, ask-user tools use pi's RPC dialogs and gentle-agents publishes live subagent activity for the desktop app. See the [reference](docs/readme-reference.md#interactive-rpc-hosts).
 
 ---
 
@@ -203,13 +203,38 @@ The [v2.6.0 release](https://github.com/Gentleman-Programming/gentle-pi/releases
 
 ## Get started
 
-Install the stable release, restart Pi, then synchronize the installed assets.
-
 > **Naming transition:** The product is called `gentle-shell`; the current npm package and repository remain `gentle-pi` until migration.
 
+### Path A: standalone `gentle-shell` (recommended, no pi changes)
+
+`gentle-shell` opens Pi with the Gentle Shell package loaded, without installing it into your pi agent or editing its `settings.json`.
+
+```bash
+npm i -g gentle-pi
+
+# Own home, never touches your pi install
+gentle-shell
+
+# Reuse your pi sign-ins, models and chats instead
+gentle-shell --link
+```
+
+`gentle-shell` alone starts in its own home, `~/.gentle-shell/agent`. `gentle-shell --link` reuses `~/.pi/agent` as-is.
+
+```bash
+# Make --link the default
+gentle-shell home link
+```
+
+Every other argument is forwarded to pi unchanged, for example `gentle-shell --mode rpc` or `gentle-shell -p "..."`. Full flags, env vars, and modes: **[launcher reference](docs/readme-reference.md#gentle-shell-launcher)**.
+
+### Path B: inside an existing pi
+
+Install the stable release into an existing pi agent, restart Pi, then synchronize the installed assets.
+
 ```bash
-# Published stable release: v2.6.0
-pi install npm:gentle-pi@2.6.0
+# Published stable release: v3.5.1
+pi install npm:gentle-pi@3.5.1
 
 # Restart Pi, then run:
 gentle-ai sync
@@ -218,7 +243,7 @@ gentle-ai sync
 pi
 ```
 
-See the [v2.6.0 release notes](https://github.com/Gentleman-Programming/gentle-pi/releases/tag/v2.6.0) for version-specific changes.
+See the [v3.5.1 release notes](https://github.com/Gentleman-Programming/gentle-shell/releases/tag/v3.5.1) for version-specific changes.
 
 ```text
 /gentle:status
@@ -229,6 +254,8 @@ See the [v2.6.0 release notes](https://github.com/Gentleman-Programming/gentle-p
 
 > **Fullscreen installation note:** a recognized global installation persists Pi’s `"tuiMode": "fullscreen"` setting. Project-local and other install paths do not receive that change.
 
+> **Interactive RPC hosts:** the desktop app sets `GENTLE_SHELL_INTERACTIVE_HOST=1` automatically, without touching your Pi config — see the [installation reference](docs/readme-reference.md#interactive-rpc-hosts).
+
 For prerequisites, source-checkout instructions, full install behavior, and release policy, use the **[installation reference](docs/readme-reference.md#install)**. For everyday work, describe the outcome and follow [ODD](#odd--the-everyday-workflow).
 
 <p align="right"><a href="#top">Back to top ↑</a></p>
@@ -262,17 +289,17 @@ Start with the product-facing destination, then move into the operational refere
 This project is built in public. Bring a real workflow, a sharp question, a bug report, or a small improvement that makes the next person’s work clearer.
 
 <p align="center">
-  <a href="https://github.com/Gentleman-Programming/gentle-pi/issues"><img src="https://img.shields.io/badge/Issues-join%20the%20conversation-F095C8?style=for-the-badge&labelColor=1A1218" alt="GitHub issues"></a>
-  <a href="https://github.com/Gentleman-Programming/gentle-pi/graphs/contributors"><img src="https://img.shields.io/badge/Contributors-thank%20you-D7A0B8?style=for-the-badge&labelColor=1A1218" alt="Contributors"></a>
+  <a href="https://github.com/Gentleman-Programming/gentle-shell/issues"><img src="https://img.shields.io/badge/Issues-join%20the%20conversation-F095C8?style=for-the-badge&labelColor=1A1218" alt="GitHub issues"></a>
+  <a href="https://github.com/Gentleman-Programming/gentle-shell/graphs/contributors"><img src="https://img.shields.io/badge/Contributors-thank%20you-D7A0B8?style=for-the-badge&labelColor=1A1218" alt="Contributors"></a>
   <a href="https://discord.com/invite/gentleman-programming-769863833996754944"><img src="https://img.shields.io/badge/Discord-Gentleman%20Programming-F095C8?style=for-the-badge&labelColor=1A1218" alt="Gentleman Programming Discord"></a>
 </p>
 
 <p align="center">
-  <a href="https://github.com/Gentleman-Programming/gentle-pi/graphs/contributors"><img src="https://contrib.rocks/image?repo=Gentleman-Programming/gentle-pi" alt="gentle-shell contributors"></a>
+  <a href="https://github.com/Gentleman-Programming/gentle-shell/graphs/contributors"><img src="https://contrib.rocks/image?repo=Gentleman-Programming/gentle-shell" alt="gentle-shell contributors"></a>
 </p>
 
-- Open an [issue](https://github.com/Gentleman-Programming/gentle-pi/issues) with the context needed to reproduce or understand the idea.
-- See the people shaping the project in the [contributors graph](https://github.com/Gentleman-Programming/gentle-pi/graphs/contributors).
+- Open an [issue](https://github.com/Gentleman-Programming/gentle-shell/issues) with the context needed to reproduce or understand the idea.
+- See the people shaping the project in the [contributors graph](https://github.com/Gentleman-Programming/gentle-shell/graphs/contributors).
 - Follow [Gentleman Programming](https://github.com/Gentleman-Programming) for the wider ecosystem.
 
 <p align="right"><a href="#top">Back to top ↑</a></p>

package/bin/gentle-shell.mjs

@@ -0,0 +1,373 @@
+#!/usr/bin/env node
+// Thin process/fs/exec glue around lib/gentle-shell-launcher.ts (built to
+// runtime/gentle-shell-launcher.mjs). All decision logic — argv parsing, home
+// resolution, pi resolution order, the version gate, and the pi invocation —
+// lives in that pure, unit-tested module; this file only wires it to the real
+// process, filesystem, and child process.
+import { accessSync, constants as fsConstants, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { constants as osConstants, homedir } from "node:os";
+import { delimiter, dirname, join, resolve as resolvePath } from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import {
+	buildPiInvocation,
+	checkPiVersion,
+	decideTakeOver,
+	describeVersion,
+	discoverLooseExtensionEntries,
+	findGentlePiDeclaration,
+	helpText,
+	launcherConfigPath,
+	missingPiMessage,
+	otherPackageInjections,
+	parseLauncherArgs,
+	parseLauncherConfig,
+	planSpawn,
+	resolveHome,
+	resolvePiRuntime,
+} from "../runtime/gentle-shell-launcher.mjs";
+import { installIsolatedTuiModeSetting } from "../scripts/install-tui-mode-setting.mjs";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+function fail(message, code) {
+	process.stderr.write(`${message}\n`);
+	process.exit(code);
+}
+
+function readJsonIfExists(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+// @earendil-works/pi-coding-agent ships as an optional peer dependency: it may
+// not be installed at all, so a resolution failure here is expected, not an error.
+function resolveBundledCli() {
+	try {
+		const require = createRequire(import.meta.url);
+		const pkgJsonPath = require.resolve("@earendil-works/pi-coding-agent/package.json");
+		const cliPath = join(dirname(pkgJsonPath), "dist", "bundle", "cli.js");
+		return existsSync(cliPath) ? cliPath : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function findOnPath(name) {
+	const dirs = (process.env.PATH || "").split(delimiter).filter((entry) => entry.length > 0);
+	const extensions = process.platform === "win32" ? (process.env.PATHEXT || ".COM;.EXE;.BAT;.CMD").split(";") : [""];
+	for (const dir of dirs) {
+		for (const extension of extensions) {
+			const candidate = join(dir, `${name}${extension}`);
+			try {
+				accessSync(candidate, fsConstants.X_OK);
+				return candidate;
+			} catch {
+				// keep scanning
+			}
+		}
+	}
+	return undefined;
+}
+
+function signalExitCode(signal) {
+	const number = osConstants.signals[signal];
+	return 128 + (typeof number === "number" ? number : 0);
+}
+
+function ownPackageVersion() {
+	const packageJson = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+	return packageJson.version;
+}
+
+function emptyArgs() {
+	return {
+		link: false,
+		isolated: false,
+		home: undefined,
+		packageRoot: undefined,
+		help: false,
+		version: false,
+		command: undefined,
+		commandArgs: [],
+		passthrough: [],
+		piSubcommand: undefined,
+		error: undefined,
+	};
+}
+
+// package.json "name" reader injected into findGentlePiDeclaration: a
+// missing or unreadable package.json, or a non-string "name", is never an
+// error here — it just means that path package is not gentle-pi.
+function readPackageName(dir) {
+	try {
+		const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+		return typeof pkg.name === "string" ? pkg.name : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+// Best-effort realpath: a directory that does not exist (yet, or ever)
+// cannot be realpath'd, so the take-over decision falls back to comparing
+// the raw path instead of failing.
+function safeRealpath(path) {
+	try {
+		return realpathSync(path);
+	} catch {
+		return path;
+	}
+}
+
+// Used to filter the loose extension dirs a take-over re-injects: a missing
+// path, or one that is not a directory (for example a stray file named
+// "extensions"), is silently excluded rather than passed to pi as -e.
+function isDirectory(path) {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+// Real-fs adapter for discoverLooseExtensionEntries (lib/gentle-shell-launcher.ts):
+// statSync-based isFile/isDirectory (not readdirSync's Dirent, which uses
+// lstat and so would treat a symlinked file or directory as neither) so a
+// symlinked loose extension resolves the same way pi's own fs.existsSync-based
+// checks would.
+const looseExtensionFs = {
+	readdir(dir) {
+		let names;
+		try {
+			names = readdirSync(dir);
+		} catch (error) {
+			// resolveLooseExtensionEntries only calls this once isDirectory(dir)
+			// has already confirmed the directory exists, so a failure here (for
+			// example EACCES) is a real read failure, not a missing directory.
+			// Warn instead of silently dropping every loose extension it would
+			// have contributed (R4-loose-extension-enumeration-fails-silently).
+			process.stderr.write(`gentle-shell: could not read loose extension directory ${dir}: ${error.message} (skipping)\n`);
+			return [];
+		}
+		return names.map((name) => {
+			const entryPath = join(dir, name);
+			try {
+				const entryStat = statSync(entryPath);
+				return { name, isFile: entryStat.isFile(), isDirectory: entryStat.isDirectory() };
+			} catch {
+				return { name, isFile: false, isDirectory: false };
+			}
+		});
+	},
+	exists: existsSync,
+};
+
+// A loose extensions directory that is itself a self-contained extension —
+// a package.json declaring a non-empty "pi.extensions" manifest — is passed
+// through as a single -e <dir> instead of being broken into per-file
+// entries: pi's own module loader (jiti) resolves that case directly,
+// exactly as it would for any other explicitly configured package path. A
+// root-level index.ts/index.js is deliberately NOT treated as that same
+// marker: pi's own discovery loads it as just another loose file, so
+// collapsing the whole directory on its presence silently dropped sibling
+// loose files like extra.ts (R4-loose-index-collapses-sibling-extensions).
+function readPiManifestExtensions(dir) {
+	try {
+		const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+		return Array.isArray(pkg?.pi?.extensions) ? pkg.pi.extensions : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function looseDirHasOwnEntryPoint(dir) {
+	const manifestExtensions = readPiManifestExtensions(dir);
+	return manifestExtensions !== undefined && manifestExtensions.length > 0;
+}
+
+// Resolves one candidate loose-extensions directory (<agentDir>/extensions or
+// <cwd>/.pi/extensions) into the -e entries a take-over must re-inject: the
+// directory itself when it is a self-contained extension, otherwise every
+// loose file discoverLooseExtensionEntries finds inside it. A missing or
+// non-directory candidate resolves to no entries.
+function resolveLooseExtensionEntries(dir) {
+	if (!isDirectory(dir)) return [];
+	if (looseDirHasOwnEntryPoint(dir)) return [dir];
+	return discoverLooseExtensionEntries(dir, looseExtensionFs);
+}
+
+function loadConfig() {
+	const configPath = launcherConfigPath(homedir());
+	const text = readJsonIfExists(configPath);
+	return text === undefined ? undefined : parseLauncherConfig(text);
+}
+
+function handleHomeCommand(commandArgs) {
+	if (commandArgs.length === 0) {
+		const resolved = resolveHome({ args: emptyArgs(), env: process.env, homedir: homedir(), config: loadConfig() });
+		process.stdout.write(`${resolved.mode} ${resolved.dir}\n`);
+		process.exit(0);
+	}
+	if (commandArgs.length > 1) fail("gentle-shell home accepts at most one argument. Run 'gentle-shell --help'.", 2);
+	const [value] = commandArgs;
+	if (value.length === 0) fail("gentle-shell home requires a non-empty argument. Run 'gentle-shell --help'.", 2);
+
+	const configPath = launcherConfigPath(homedir());
+	const configDir = dirname(configPath);
+	if (!existsSync(configDir)) mkdirSync(configDir, { recursive: true, mode: 0o700 });
+
+	if (value === "link" || value === "isolated") {
+		writeFileSync(configPath, `${JSON.stringify({ home: value }, null, 2)}\n`, "utf8");
+		process.stdout.write(`Saved home: ${value}\n`);
+		process.exit(0);
+	}
+	const dir = resolvePath(value);
+	writeFileSync(configPath, `${JSON.stringify({ home: dir }, null, 2)}\n`, "utf8");
+	process.stdout.write(`Saved home: path ${dir}\n`);
+	process.exit(0);
+}
+
+async function main() {
+	const args = parseLauncherArgs(process.argv.slice(2));
+	if (args.error !== undefined) fail(`${args.error}\nRun 'gentle-shell --help' for usage.`, 2);
+	if (args.help) {
+		process.stdout.write(`${helpText()}\n`);
+		process.exit(0);
+	}
+	if (args.command === "home") {
+		handleHomeCommand(args.commandArgs);
+		return;
+	}
+
+	const config = loadConfig();
+	let home = resolveHome({ args, env: process.env, homedir: homedir(), config });
+	if (home.mode === "path") home = { ...home, dir: resolvePath(home.dir) };
+
+	const runtime = resolvePiRuntime({
+		env: process.env,
+		resolveBundledCli,
+		findOnPath,
+		nodeExecPath: process.execPath,
+	});
+	if (runtime === undefined) fail(missingPiMessage(), 1);
+
+	const versionProbePlan = planSpawn({ command: runtime.command, args: [...runtime.args, "--version"], platform: process.platform });
+	const versionProbe = spawnSync(versionProbePlan.command, versionProbePlan.args, {
+		stdio: ["ignore", "pipe", "pipe"],
+		timeout: 15000,
+		encoding: "utf8",
+		shell: versionProbePlan.shell,
+	});
+	if (versionProbe.error) fail(`Could not run the pi runtime at "${runtime.command}": ${versionProbe.error.message}`, 1);
+	const versionCheck = checkPiVersion(versionProbe.stdout ?? "");
+	if (!versionCheck.ok) fail(versionCheck.message, 1);
+
+	if (args.version) {
+		process.stdout.write(`${describeVersion({ gentlePiVersion: ownPackageVersion(), piVersion: versionCheck.version, home })}\n`);
+		process.exit(0);
+	}
+
+	// Isolated-home bootstrap: only on a home gentle-shell has not seen before
+	// (link never bootstraps — it reuses the user's own pi agent home as-is).
+	if ((home.mode === "isolated" || home.mode === "path") && !existsSync(home.dir)) {
+		mkdirSync(home.dir, { recursive: true });
+		await installIsolatedTuiModeSetting(home.dir);
+		process.stderr.write(`gentle-shell: using a separate home at ${home.dir}. Run 'gentle-shell --link' to reuse your pi sign-ins and chats.\n`);
+	}
+
+	const packageRootExplicit = args.packageRoot !== undefined;
+	const effectivePackageRoot = packageRootExplicit ? resolvePath(args.packageRoot) : packageRoot;
+	// R4-forced-package-root-unvalidated / R3-005: an unvalidated --package-root
+	// forces a take-over (dropping normal extension discovery via
+	// --no-extensions) and then hands pi -e/--theme/--skill/--prompt-template
+	// flags pointing at directories that do not exist, turning an operator typo
+	// into an obscure pi loader failure instead of a clear launcher error.
+	if (packageRootExplicit && !isDirectory(effectivePackageRoot)) {
+		fail(`--package-root ${args.packageRoot} does not exist or is not a directory.`, 2);
+	}
+
+	let declaration;
+	let takeOver = false;
+	let otherPackagePaths = [];
+	let looseExtensionEntries = [];
+
+	// Only --link can read another gentle-pi declaration out of a real
+	// settings.json; isolated and --home homes never declare one, so they
+	// always get the plain injection (declaration stays undefined) unless
+	// --package-root itself forces a take-over below. A pi subcommand skips
+	// this whole block: buildPiInvocation ignores takeOver/declaration once
+	// piSubcommand is set, and running the take-over/loose-dir discovery
+	// anyway would still print a misleading "taking over gentle-pi..."
+	// message (and otherPackageInjections warnings) for a plain
+	// `gentle-shell install npm:x` that never actually takes anything over.
+	if (home.mode === "link" && args.piSubcommand === undefined) {
+		const settingsText = readJsonIfExists(join(home.dir, "settings.json"));
+		declaration = findGentlePiDeclaration(settingsText, { agentDir: home.dir, readPackageName });
+		const realEffectivePackageRoot = safeRealpath(effectivePackageRoot);
+		const realDeclaredDir = declaration?.kind === "path" ? safeRealpath(declaration.dir) : undefined;
+		takeOver = decideTakeOver({
+			declaration,
+			realPackageRoot: realEffectivePackageRoot,
+			realDeclaredDir,
+			packageRootExplicit,
+		});
+		if (takeOver) {
+			const skip = declaration ?? { kind: "path", dir: realEffectivePackageRoot };
+			const injections = otherPackageInjections({ settingsText, agentDir: home.dir, skip, isDirectory, realpath: safeRealpath });
+			otherPackagePaths = injections.paths;
+			for (const warning of injections.warnings) process.stderr.write(`${warning}\n`);
+			// --no-extensions drops pi's normal settings-driven extension
+			// discovery, which also covers loose (non-package) extensions
+			// under <agentDir>/extensions and the project-local
+			// <cwd>/.pi/extensions. Re-injecting either directory wholesale
+			// as `-e <dir>` does not work for a directory of loose files: pi's
+			// -e flag hands the path straight to its module loader with no
+			// directory-discovery pass, so a bare directory of loose files
+			// fails with "Cannot find module ...". Resolve each candidate
+			// into its actual loose file entries (or pass it through
+			// unchanged when it is itself a self-contained extension) so a
+			// take-over does not silently stop loading them.
+			looseExtensionEntries = [join(home.dir, "extensions"), join(process.cwd(), ".pi", "extensions")].flatMap(resolveLooseExtensionEntries);
+			const declaredFrom = declaration === undefined ? "the requested package root" : declaration.kind === "npm" ? "npm:gentle-pi" : declaration.dir;
+			process.stderr.write(
+				`gentle-shell: taking over gentle-pi from ${declaredFrom} for this run (settings unchanged; its skills, prompts, and themes still load alongside this launcher's).\n`,
+			);
+		}
+	}
+	// Isolated and --home homes have no declaration to take over: declaration
+	// stays undefined and buildPiInvocation injects effectivePackageRoot the
+	// same way it always has, --package-root included.
+
+	const invocation = buildPiInvocation({
+		runtime,
+		home,
+		packageRoot: effectivePackageRoot,
+		declaration,
+		takeOver,
+		otherPackagePaths,
+		looseExtensionEntries,
+		passthrough: args.passthrough,
+		piSubcommand: args.piSubcommand,
+		baseEnv: process.env,
+	});
+
+	const launchPlan = planSpawn({ command: invocation.command, args: invocation.args, platform: process.platform });
+	const child = spawn(launchPlan.command, launchPlan.args, { stdio: "inherit", env: invocation.env, shell: launchPlan.shell });
+	for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+		process.on(signal, () => child.kill(signal));
+	}
+	child.on("error", (error) => fail(`Could not start pi: ${error.message}`, 1));
+	child.on("exit", (code, signal) => {
+		process.exit(signal ? signalExitCode(signal) : (code ?? 1));
+	});
+}
+
+main().catch((error) => {
+	process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+	process.exit(1);
+});

package/docs/gentle-agents-activity.md

@@ -0,0 +1,95 @@
+# Gentle Agents activity schema (`gentle-agents.activity/v1`)
+
+An interactive RPC host — a client that runs `pi --mode rpc` itself, such as the Gentle Shell desktop app — receives live Gentle Agents subagent state as one bounded JSON document per coalescing window, so it can render a per-chat Helpers view without polling `subagent_status`.
+
+Source map: [publisher](../lib/agents-rpc-publisher.ts), [wiring](../extensions/gentle-agents.ts), [store](../lib/agents-protocol.ts).
+
+## Turning it on
+
+Set `GENTLE_SHELL_INTERACTIVE_HOST=1` on the `pi --mode rpc` process the host spawns directly. `lib/rpc-host.ts`'s `isInteractiveRpcHost(mode, env)` gates the feature on that exact value; any other value, or its absence, keeps RPC headless — the existing subagent-child behavior is byte-identical. `lib/agents-runner.ts` strips the variable from every subagent child's environment, so a subagent spawned by an interactive host never inherits it and stays headless itself.
+
+## Transport
+
+Pi's `setWidget` is the only fire-and-forget RPC push structured enough to carry this: in RPC mode it accepts a `string[]` (sent as `extension_ui_request`) and silently ignores a component-factory function (the shape the TUI card above the editor uses). The publisher and the TUI card therefore share one widget key without colliding on the wire — a plain RPC host or a TUI session only ever sees the factory call, which its own transport ignores or renders locally.
+
+```json
+{
+  "type": "extension_ui_request",
+  "method": "setWidget",
+  "widgetKey": "gentle-agents",
+  "widgetLines": ["{\"schema\":\"gentle-agents.activity/v1\", ...}"]
+}
+```
+
+`widgetLines` is always exactly one line: one JSON document, `JSON.stringify`'d, never pretty-printed. Parse it as `gentle-agents.activity/v1`.
+
+## Payload shape
+
+```jsonc
+{
+  "schema": "gentle-agents.activity/v1",
+  "summary": { "running": 1, "queued": 0, "waiting": 0, "finished": 2 },
+  "tasks": [
+    {
+      "summary": {
+        "id": "t_abc123",
+        "agent": "explore",
+        "label": "Map the auth module",
+        "prompt": "Explore how authentication works…",
+        "status": "running",
+        "createdAt": 1732000000000,
+        "startedAt": 1732000000100,
+        "endedAt": null,
+        "lastStep": "reading lib/auth.ts",
+        "lastActivityAt": 1732000005000,
+        "turns": 2,
+        "toolCalls": 3,
+        "error": null
+      },
+      "thread": {
+        "version": 7,
+        "dropped": 0,
+        "items": [
+          { "kind": "text", "text": "Looking at the auth flow first." },
+          { "kind": "tool", "name": "read", "args": "{\"path\":\"lib/auth.ts\"}", "running": false, "isError": false, "output": "…file contents…" }
+        ]
+      }
+    }
+  ]
+}
+```
+
+`summary` is `TaskSummary` from `lib/agents-protocol.ts`, unchanged. Each task's `summary` is a field whitelist of its `TaskRecord`: `id`, `agent`, `label`, `prompt`, `status`, `createdAt`, `startedAt`, `endedAt`, `lastStep`, `lastActivityAt`, `turns`, `toolCalls`, `error`. Every other `TaskRecord` field — `cwd`, `parentSessionId`, `mode`, `model`, `thinking`, `sessionPath`, `result`, `tokens`, `cost` — is deliberately left out, the same discipline `lib/orchestrator-presence.ts`'s `projectActivity` already applies to same-profile peer discovery.
+
+`thread.items` is a `ThreadItem[]` whitelist too: text/thinking/note items keep `{ kind, text }` (`text` bounded, see below); tool items carry `{ kind: "tool", name, args, running, isError, output }`, where `args` is the tool's argument object `JSON.stringify`'d (never the raw object). `thread.dropped` is the store's own ring-buffer drop counter (unrelated to the per-push item cap below); `thread.version` increments on every thread mutation.
+
+Tasks are ordered `running`, `waiting`, `queued`, then finished tasks by `endedAt` descending (most recently finished first).
+
+## Bounds
+
+Every bound below fails closed: a value that cannot fit is truncated or dropped, and `lib/agents-rpc-publisher.ts`'s `encodeActivityLines` never throws.
+
+| Field | Bound |
+|---|---|
+| `summary.prompt` | 200 characters, trailing `…` |
+| `summary.error`, `summary.label`, `summary.lastStep` | 500 characters, trailing `…` |
+| tool `args` (stringified) | 500 characters, trailing `…` |
+| tool `output` | 500 characters, trailing `…` |
+| text/thinking/note item `text` | 2000 characters, trailing `…` |
+| `thread.items` per task | last 40, most recent last |
+| whole payload | 256 KiB |
+
+Truncation always keeps the field's prefix and marks the cut with a trailing `…` (never a separate `truncated` flag) — the same convention `projectRpcActivity`'s other bounded fields already use.
+
+When the whole-payload bound is still exceeded after the field- and item-level truncations above, `encodeActivityLines` shrinks the payload in this order:
+
+1. Halve every task's kept `thread.items` (repeatedly, down to one item each).
+2. Empty finished tasks' threads entirely.
+3. Drop whole finished tasks — oldest-finished first, by `endedAt`.
+4. Last resort: once only active (running/waiting/queued) tasks remain, each already down to one thread item, empty every remaining task's thread too — a summary-only payload.
+
+An active task's `summary` (running, waiting or queued) is never dropped; only its `thread.items` shrink. Finished tasks can be dropped whole by step 3, oldest first.
+
+## Coalescing
+
+`createRpcActivityPublisher` subscribes to `TaskStore#subscribeSummary` (task added, removed, or changed status) and to `TaskStore#subscribe(id)` for every known task, including ones added after `start()`. Changes inside a 150 ms window collapse into exactly one `setWidget("gentle-agents", [line])` call; `stop()` tears down every subscription and publishes one final frame.