gentle-pi 3.3.0 → 3.5.0

package/scripts/install-gentle-ai.mjs

@@ -3,8 +3,10 @@
 // hardcoded copies of it survived a pin bump once and reported installing
 // v2.1.11 while writing v2.2.0 to disk, which is the one moment an operator
 // most needs the number to be true.
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { INSTALLER_VERSION, installGentleAi } from "./gentle-ai-installer.mjs";
-import { installTuiModeSetting } from "./install-tui-mode-setting.mjs";
+import { installTuiModeSetting, isPiManagedInstall } from "./install-tui-mode-setting.mjs";
 
 if (process.env.GENTLE_PI_SKIP_GENTLE_AI_INSTALL === "1") {
 	console.warn("GENTLE_PI_SKIP_GENTLE_AI_INSTALL=1: skipped package-local Gentle AI installation; native review operations will fail with package-local-binary-missing until gentle-pi is reinstalled.");
@@ -20,11 +22,16 @@ if (process.env.GENTLE_PI_SKIP_GENTLE_AI_INSTALL === "1") {
 
 // A native failure never changes settings; the explicit native-only skip does.
 if (!process.exitCode) {
-	try {
-		const result = await installTuiModeSetting();
-		if (result.changed) console.log("gentle-pi enabled fullscreen in global Pi settings; /settings can switch back to regular.");
-	} catch (error) {
-		console.error(`gentle-pi could not enable fullscreen: ${error instanceof Error ? error.message : String(error)}`);
-		process.exitCode = 1;
+	const packageDir = dirname(dirname(fileURLToPath(import.meta.url)));
+	if (!isPiManagedInstall(packageDir)) {
+		console.log(`gentle-pi skipped enabling fullscreen in global Pi settings: ${packageDir} is not a pi-managed install (npm install -g, a git checkout, and npx all land here).`);
+	} else {
+		try {
+			const result = await installTuiModeSetting();
+			if (result.changed) console.log("gentle-pi enabled fullscreen in global Pi settings; /settings can switch back to regular.");
+		} catch (error) {
+			console.error(`gentle-pi could not enable fullscreen: ${error instanceof Error ? error.message : String(error)}`);
+			process.exitCode = 1;
+		}
 	}
 }

package/scripts/install-tui-mode-setting.mjs

@@ -1,10 +1,44 @@
 import { closeSync, constants, fchmodSync, fsyncSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";
 import { setTimeout as delay } from "node:timers/promises";
 
+// The two directory layouts Pi's own package manager creates when it installs
+// a package into an agent home: the npm-backed `npm/node_modules/<package>`
+// (user scope `<agent dir>/npm/node_modules/gentle-pi`, project scope
+// `.pi/npm/node_modules/gentle-pi`) and the git-backed
+// `git/github.com/Gentleman-Programming/<package>` layout. A path is checked
+// for these sequences anywhere in its segments, not anchored to a specific
+// resolved agent home — unlike installTuiModeSetting's own ownership check.
+const PI_MANAGED_SEGMENT_SEQUENCES = [
+	["npm", "node_modules"],
+	["git", "github.com", "Gentleman-Programming"],
+];
+
+function containsSequence(segments, sequence) {
+	for (let start = 0; start + sequence.length <= segments.length; start += 1) {
+		if (sequence.every((part, offset) => segments[start + offset] === part)) return true;
+	}
+	return false;
+}
+
+/** Gates the POSTINSTALL entry point only (scripts/install-gentle-ai.mjs), not
+ * installTuiModeSetting or installIsolatedTuiModeSetting: true when
+ * `packageDir` (the directory of the gentle-pi package actually running,
+ * typically derived from that script's own import.meta.url) sits under one of
+ * the directory layouts above. A plain `npm install -g gentle-pi`, a
+ * development git checkout, an `npx` cache directory, or a pnpm store never
+ * match, so the postinstall entry skips writing the user's global Pi settings
+ * for those instead of relying solely on installTuiModeSetting's own,
+ * differently-scoped ownership check.
+ */
+export function isPiManagedInstall(packageDir) {
+	const segments = resolve(packageDir).split(sep);
+	return PI_MANAGED_SEGMENT_SEQUENCES.some((sequence) => containsSequence(segments, sequence));
+}
+
 function inspect(path) {
 	try { return lstatSync(path); }
 	catch (error) { if (error.code === "ENOENT") return undefined; throw error; }
@@ -112,3 +146,46 @@ export async function installTuiModeSetting(options = {}) {
 		}
 	}
 }
+
+/** Writes tuiMode: "fullscreen" into a directory gentle-shell's own isolated-home
+ * bootstrap (T2) just created and owns. Unlike installTuiModeSetting, there is no
+ * "physically installed under this home's npm/node_modules" ownership check to
+ * satisfy: the caller already knows it created `dir` moments ago as gentle-shell's
+ * dedicated agent home, so the only safety property that still matters is the one
+ * every writer here needs — atomic, non-symlink, cooperative-lock-respecting.
+ */
+export async function installIsolatedTuiModeSetting(dir) {
+	const home = realpathSync(resolve(dir));
+	assertDirectories([home]);
+	const settingsPath = join(home, "settings.json");
+	const lockPath = `${settingsPath}.lock`;
+	const lock = await acquireLock(lockPath);
+	const started = Date.now();
+	let staging;
+	try {
+		assertDirectories([home]);
+		const original = readSettings(settingsPath);
+		if (original.value.tuiMode === "fullscreen") return { changed: false, recognized: true };
+		staging = join(home, `.settings-fullscreen-${randomUUID()}.tmp`);
+		const fd = openSync(staging, "wx", original.stat ? original.stat.mode & 0o777 : 0o600);
+		try {
+			if (original.stat) fchmodSync(fd, original.stat.mode & 0o777);
+			writeFileSync(fd, `${JSON.stringify({ ...original.value, tuiMode: "fullscreen" }, null, 2)}\n`, "utf8");
+			fsyncSync(fd);
+		} finally { closeSync(fd); }
+		assertDirectories([home]);
+		const latest = readSettings(settingsPath);
+		if (latest.text !== original.text || (original.stat ? !sameFile(original.stat, latest.stat) : latest.stat !== undefined)) {
+			throw new Error("settings.json changed concurrently; retry installation");
+		}
+		if (!sameFile(lock, inspect(lockPath)) || Date.now() - started >= 5000) throw new Error("Fullscreen settings lock ownership expired; retry installation");
+		renameSync(staging, settingsPath);
+		staging = undefined;
+		return { changed: true, recognized: true };
+	} finally {
+		if (realpathSync(home) === home) {
+			if (staging) unlinkSync(staging);
+			if (sameFile(lock, inspect(lockPath))) rmdirSync(lockPath);
+		}
+	}
+}

package/scripts/verify-package-files.mjs

@@ -8,6 +8,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 const root = join(fileURLToPath(new URL("..", import.meta.url)));
 
 const requiredPaths = [
+  "bin/gentle-shell.mjs",
   "assets/orchestrator.md",
   "assets/orchestrator-delegation.md",
   "assets/orchestrator-memory.md",
@@ -54,6 +55,7 @@ const requiredPaths = [
   "extensions/sdd-init.ts",
   "extensions/skill-registry.ts",
   "lib/gentle-ai-binary.ts",
+  "lib/gentle-shell-launcher.ts",
   "lib/native-review-cli.ts",
   "lib/provider-contract-bundle.ts",
   "lib/review-host-relay.ts",
@@ -62,6 +64,7 @@ const requiredPaths = [
   "lib/sdd-preflight.ts",
   "lib/telemetry-trigger.ts",
 	"runtime/gentle-ai-binary.mjs",
+	"runtime/gentle-shell-launcher.mjs",
 	"runtime/native-review-cli.mjs",
 	"runtime/review-integration-v2.mjs",
 	"runtime/review-risk-assessment.mjs",
@@ -70,6 +73,7 @@ const requiredPaths = [
   "scripts/check-provider-contract.mjs",
   "scripts/gentle-ai-installer.mjs",
   "scripts/install-gentle-ai.mjs",
+  "scripts/install-tui-mode-setting.mjs",
   "scripts/mirror-provider-contract.mjs",
   "tests/fixtures/native-review-cli/v2.1.3/start.json",
   "tests/fixtures/provider-contract-bundle/v1.1.0/README.md",
@@ -105,7 +109,6 @@ const requiredPaths = [
   "skills/issue-creation/SKILL.md",
   "skills/judgment-day/SKILL.md",
   "skills/rdd-defect-workflow/SKILL.md",
-  "skills/release/SKILL.md",
   "skills/skill-creator/SKILL.md",
   "skills/skill-improver/SKILL.md",
   "skills/skill-registry/SKILL.md",
@@ -339,7 +342,7 @@ async function main() {
   });
 
   if (driftedContracts.length > 0) {
-    console.error("gentle-pi packaged review-integration/v1 and review-integration/v2 contract bytes drifted from the pinned v3.4.0 runtime's vendored Gentle AI contract artifacts:");
+    console.error("gentle-pi packaged review-integration/v1 and review-integration/v2 contract bytes drifted from the pinned v3.5.0 runtime's vendored Gentle AI contract artifacts:");
     for (const drift of driftedContracts) console.error(`- ${drift.relativePath}: expected ${drift.expected}, got ${drift.actual}`);
     process.exit(1);
   }
@@ -384,7 +387,7 @@ async function main() {
     process.exit(1);
   }
 
-  console.log(`gentle-pi package resource check passed (${requiredPaths.length} files; ${Object.keys(contractHashes).length} exact byte-pinned contract artifacts for the v3.4.0 runtime).`);
+  console.log(`gentle-pi package resource check passed (${requiredPaths.length} files; ${Object.keys(contractHashes).length} exact byte-pinned contract artifacts for the v3.5.0 runtime).`);
 }
 
 const isMainModule = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;

package/tests/agents-rpc-publisher.test.ts

@@ -0,0 +1,407 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { TASK_EVENT, TASK_STATUS, TaskStore, type TaskRecord, type TaskStatus } from "../lib/agents-protocol.ts";
+import {
+	ACTIVITY_SCHEMA,
+	ACTIVITY_WIDGET_KEY,
+	createRpcActivityPublisher,
+	encodeActivityLines,
+	projectRpcActivity,
+	type RpcActivity,
+	type RpcTask,
+} from "../lib/agents-rpc-publisher.ts";
+
+// gentle-agents RPC publisher: a pure projection of TaskStore state into the
+// bounded JSON payload an interactive RPC host receives through setWidget,
+// plus the store-driven, coalesced publisher that pushes it.
+
+function task(id: string, parentSessionId: string, overrides: Partial<TaskRecord> = {}): TaskRecord {
+	return {
+		id,
+		agent: "worker",
+		mode: "task",
+		prompt: "p",
+		label: "p",
+		cwd: "/r",
+		parentSessionId,
+		status: TASK_STATUS.RUNNING,
+		createdAt: 1000,
+		startedAt: 1000,
+		endedAt: null,
+		model: "gpt",
+		thinking: undefined,
+		sessionPath: "/sessions/child.jsonl",
+		error: null,
+		result: null,
+		lastStep: "working",
+		lastActivityAt: 1000,
+		turns: 0,
+		toolCalls: 0,
+		tokens: 0,
+		cost: 0,
+		...overrides,
+	};
+}
+
+/** Build one already-projected `RpcTask` fixture directly, bypassing `projectRpcActivity`, so `encodeActivityLines` shrink-stage tests control exact sizes. */
+function rpcTask(id: string, status: TaskStatus, endedAt: number | null, opts: { items?: number; itemTextLen?: number; labelLen?: number } = {}): RpcTask {
+	const { items = 1, itemTextLen = 20, labelLen = 4 } = opts;
+	return {
+		summary: {
+			id,
+			agent: "a",
+			label: "l".repeat(labelLen),
+			prompt: "p",
+			status,
+			createdAt: 1,
+			startedAt: 1,
+			endedAt,
+			lastStep: "s",
+			lastActivityAt: 1,
+			turns: 0,
+			toolCalls: 0,
+			error: null,
+		},
+		thread: {
+			version: 1,
+			dropped: 0,
+			items: Array.from({ length: items }, (_v, index) => ({ kind: "note" as const, text: `${"n".repeat(itemTextLen)}${index}` })),
+		},
+	};
+}
+
+function byteLength(value: string): number {
+	return Buffer.byteLength(value, "utf8");
+}
+
+test("projectRpcActivity whitelists task fields and orders running, waiting, queued, then finished by endedAt desc", () => {
+	const store = new TaskStore();
+	store.add(task("running-1", "s1", { status: TASK_STATUS.RUNNING, agent: "explore", label: "Explore X", prompt: "short prompt", turns: 2, toolCalls: 1, createdAt: 1, lastActivityAt: 5 }));
+	store.add(task("waiting-1", "s1", { status: TASK_STATUS.WAITING, createdAt: 2, lastActivityAt: 6 }));
+	store.add(task("queued-1", "s1", { status: TASK_STATUS.QUEUED, createdAt: 3, startedAt: null, lastActivityAt: 3 }));
+	store.add(task("finished-old", "s1", { status: TASK_STATUS.COMPLETED, createdAt: 4, endedAt: 100, lastActivityAt: 100 }));
+	store.add(task("finished-new", "s1", { status: TASK_STATUS.FAILED, createdAt: 5, endedAt: 200, lastActivityAt: 200, error: "boom" }));
+
+	const activity = projectRpcActivity(store);
+
+	assert.equal(activity.schema, ACTIVITY_SCHEMA);
+	assert.deepEqual(activity.summary, store.summary());
+	assert.deepEqual(activity.tasks.map((entry) => entry.summary.id), ["running-1", "waiting-1", "queued-1", "finished-new", "finished-old"]);
+
+	const runningSummary = activity.tasks[0]!.summary;
+	assert.deepEqual(
+		Object.keys(runningSummary).sort(),
+		["id", "agent", "label", "prompt", "status", "createdAt", "startedAt", "endedAt", "lastStep", "lastActivityAt", "turns", "toolCalls", "error"].sort(),
+		"only the whitelisted fields are projected: cwd, parentSessionId, mode, model, thinking, sessionPath, result, tokens, and cost never leak",
+	);
+	assert.equal(runningSummary.agent, "explore");
+	assert.equal(runningSummary.label, "Explore X");
+	assert.equal(runningSummary.prompt, "short prompt");
+	assert.equal(activity.tasks[4]!.summary.error, null);
+	assert.equal(activity.tasks[3]!.summary.error, "boom");
+});
+
+test("projectRpcActivity truncates the prompt, tool args, and tool output to their bounds", () => {
+	const store = new TaskStore();
+	store.add(task("t1", "s1", { prompt: "x".repeat(250) }));
+	store.apply("t1", { type: TASK_EVENT.TOOL_START, callId: "c1", name: "bash", args: { note: "y".repeat(600) } }, 1);
+	store.apply("t1", { type: TASK_EVENT.TOOL_END, callId: "c1", output: "z".repeat(600), isError: false }, 2);
+
+	const activity = projectRpcActivity(store);
+	const summary = activity.tasks[0]!.summary;
+	assert.equal(summary.prompt.length, 200);
+	assert.ok(summary.prompt.endsWith("…"));
+
+	const toolItem = activity.tasks[0]!.thread.items.at(-1) as { kind: string; name: string; args: string; running: boolean; isError: boolean; output: string };
+	assert.equal(toolItem.kind, "tool");
+	assert.equal(toolItem.name, "bash");
+	assert.equal(toolItem.running, false);
+	assert.equal(toolItem.isError, false);
+	assert.ok(toolItem.args.length <= 500 && toolItem.args.endsWith("…"));
+	assert.ok(toolItem.output.length <= 500 && toolItem.output.endsWith("…"));
+	assert.match(toolItem.args, /^\{"note":"y+…$/);
+});
+
+test("projectRpcActivity keeps only the last N thread items per task (default 40)", () => {
+	const store = new TaskStore();
+	store.add(task("t1", "s1"));
+	for (let index = 0; index < 50; index += 1) store.apply("t1", { type: TASK_EVENT.NOTE, text: `note-${index}` }, index);
+
+	const activity = projectRpcActivity(store);
+	const items = activity.tasks[0]!.thread.items as { text: string }[];
+	assert.equal(items.length, 40);
+	assert.equal(items[0]!.text, "note-10");
+	assert.equal(items.at(-1)!.text, "note-49");
+});
+
+test("projectRpcActivity truncates text, thinking, and note item text to 2000 characters", () => {
+	const store = new TaskStore();
+	store.add(task("t1", "s1"));
+	store.apply("t1", { type: TASK_EVENT.TEXT, text: "a".repeat(3000) }, 1);
+	store.apply("t1", { type: TASK_EVENT.THINKING, text: "b".repeat(3000) }, 2);
+	store.apply("t1", { type: TASK_EVENT.NOTE, text: "c".repeat(3000) }, 3);
+
+	const activity = projectRpcActivity(store);
+	const items = activity.tasks[0]!.thread.items as { kind: string; text: string }[];
+
+	assert.equal(items.length, 3);
+	for (const item of items) {
+		assert.ok(item.text.length <= 2000, `${item.kind} item must be bounded to 2000 characters`);
+		assert.ok(item.text.endsWith("…"), `${item.kind} item must carry the truncation marker`);
+	}
+});
+
+test("projectRpcActivity truncates a synthetic 1 MiB text item to 2000 characters", () => {
+	const store = new TaskStore();
+	store.add(task("t1", "s1"));
+	store.apply("t1", { type: TASK_EVENT.TEXT, text: "x".repeat(1024 * 1024) }, 1);
+
+	const activity = projectRpcActivity(store);
+	const item = activity.tasks[0]!.thread.items[0] as { text: string };
+
+	assert.equal(item.text.length, 2000);
+	assert.ok(item.text.endsWith("…"));
+});
+
+test("projectRpcActivity truncates the summary error, label, and lastStep fields to 500 characters", () => {
+	const store = new TaskStore();
+	store.add(task("t1", "s1", { label: "l".repeat(600) }));
+	store.apply("t1", { type: TASK_EVENT.AGENT_END, text: "", outcome: "error", diagnostic: "e".repeat(600) }, 1);
+
+	const activity = projectRpcActivity(store);
+	const summary = activity.tasks[0]!.summary;
+
+	assert.ok(summary.label.length <= 500 && summary.label.endsWith("…"));
+	assert.ok(summary.lastStep.length <= 500 && summary.lastStep.endsWith("…"));
+	assert.ok(summary.error !== null && summary.error.length <= 500 && summary.error.endsWith("…"));
+});
+
+test("projectRpcActivity honors a custom maxThreadItems override", () => {
+	const store = new TaskStore();
+	store.add(task("t1", "s1"));
+	for (let index = 0; index < 5; index += 1) store.apply("t1", { type: TASK_EVENT.NOTE, text: `n${index}` }, index);
+
+	const activity = projectRpcActivity(store, { maxThreadItems: 2 });
+	assert.deepEqual((activity.tasks[0]!.thread.items as { text: string }[]).map((item) => item.text), ["n3", "n4"]);
+});
+
+test("encodeActivityLines returns the activity untouched as a single line when it already fits", () => {
+	const activity: RpcActivity = { schema: ACTIVITY_SCHEMA, summary: { running: 0, queued: 0, waiting: 0, finished: 0 }, tasks: [] };
+
+	const lines = encodeActivityLines(activity);
+
+	assert.equal(lines.length, 1);
+	assert.deepEqual(JSON.parse(lines[0]!), activity);
+});
+
+test("encodeActivityLines halves thread items per task when only halving can help", () => {
+	const activity: RpcActivity = {
+		schema: ACTIVITY_SCHEMA,
+		summary: { running: 1, queued: 0, waiting: 0, finished: 0 },
+		tasks: [rpcTask("r1", TASK_STATUS.RUNNING, null, { items: 16, itemTextLen: 50 })],
+	};
+	const maxBytes = Math.floor(byteLength(JSON.stringify(activity)) / 2);
+
+	const [line] = encodeActivityLines(activity, maxBytes);
+	const shrunk = JSON.parse(line!) as RpcActivity;
+
+	assert.equal(shrunk.tasks.length, 1);
+	assert.ok(shrunk.tasks[0]!.thread.items.length < 16, "items must have been halved down");
+	assert.ok(shrunk.tasks[0]!.thread.items.length >= 1, "halving never removes the last item on a running task");
+});
+
+test("encodeActivityLines drops a finished task's thread items before dropping the task itself", () => {
+	const activity: RpcActivity = {
+		schema: ACTIVITY_SCHEMA,
+		summary: { running: 1, queued: 0, waiting: 0, finished: 1 },
+		tasks: [rpcTask("r1", TASK_STATUS.RUNNING, null, { items: 1, itemTextLen: 10 }), rpcTask("f1", TASK_STATUS.COMPLETED, 100, { items: 1, itemTextLen: 5000 })],
+	};
+	const full = byteLength(JSON.stringify(activity));
+	const maxBytes = full - 4000; // enough slack that only emptying f1's thread is needed
+
+	const [line] = encodeActivityLines(activity, maxBytes);
+	const shrunk = JSON.parse(line!) as RpcActivity;
+
+	const finishedTask = shrunk.tasks.find((entry) => entry.summary.id === "f1")!;
+	assert.deepEqual(finishedTask.thread.items, [], "the finished task's thread is emptied, not the task itself");
+	assert.ok(shrunk.tasks.some((entry) => entry.summary.id === "r1"), "the running task is untouched");
+});
+
+test("encodeActivityLines drops whole finished tasks, oldest first, once emptying threads is not enough", () => {
+	const activity: RpcActivity = {
+		schema: ACTIVITY_SCHEMA,
+		summary: { running: 1, queued: 0, waiting: 0, finished: 2 },
+		tasks: [
+			rpcTask("r1", TASK_STATUS.RUNNING, null, { items: 1, itemTextLen: 10 }),
+			rpcTask("f-new", TASK_STATUS.COMPLETED, 200, { items: 1, itemTextLen: 10, labelLen: 3000 }),
+			rpcTask("f-old", TASK_STATUS.COMPLETED, 100, { items: 1, itemTextLen: 10, labelLen: 3000 }),
+		],
+	};
+	const emptiedThreads: RpcActivity = { ...activity, tasks: activity.tasks.map((entry) => (entry.summary.status === TASK_STATUS.COMPLETED ? { ...entry, thread: { ...entry.thread, items: [] } } : entry)) };
+	const maxBytes = byteLength(JSON.stringify(emptiedThreads)) - 1000; // still too big with both finished threads emptied
+
+	const [line] = encodeActivityLines(activity, maxBytes);
+	const shrunk = JSON.parse(line!) as RpcActivity;
+
+	assert.ok(!shrunk.tasks.some((entry) => entry.summary.id === "f-old"), "the oldest finished task must be dropped first");
+	assert.ok(shrunk.tasks.some((entry) => entry.summary.id === "f-new"), "the more recently finished task survives longer");
+	assert.ok(shrunk.tasks.some((entry) => entry.summary.id === "r1"), "the running task must never be dropped");
+});
+
+test("encodeActivityLines empties every remaining active task's thread as a last resort, emitting a summary-only payload", () => {
+	const activity: RpcActivity = {
+		schema: ACTIVITY_SCHEMA,
+		summary: { running: 2, queued: 0, waiting: 0, finished: 0 },
+		tasks: [
+			rpcTask("r1", TASK_STATUS.RUNNING, null, { items: 1, itemTextLen: 2000 }),
+			rpcTask("r2", TASK_STATUS.RUNNING, null, { items: 1, itemTextLen: 2000 }),
+		],
+	};
+	// No finished tasks to drop, and both running tasks are already down to
+	// one item each; only emptying every thread can still shrink this.
+	const maxBytes = byteLength(JSON.stringify(activity)) - 1000;
+
+	const [line] = encodeActivityLines(activity, maxBytes);
+	const shrunk = JSON.parse(line!) as RpcActivity;
+
+	assert.equal(shrunk.tasks.length, 2, "no active task's summary is ever dropped");
+	for (const entry of shrunk.tasks) assert.deepEqual(entry.thread.items, [], "every task's thread is emptied, summary-only");
+});
+
+test("encodeActivityLines never throws even when nothing left can be dropped to fit", () => {
+	const activity: RpcActivity = {
+		schema: ACTIVITY_SCHEMA,
+		summary: { running: 1, queued: 0, waiting: 0, finished: 0 },
+		tasks: [rpcTask("r1", TASK_STATUS.RUNNING, null, { items: 3, itemTextLen: 50 })],
+	};
+
+	const lines = encodeActivityLines(activity, 1);
+
+	assert.equal(lines.length, 1);
+	assert.doesNotThrow(() => JSON.parse(lines[0]!));
+});
+
+function fakeScheduler() {
+	const pending: Array<{ id: number; fn: () => void }> = [];
+	let nextId = 0;
+	return {
+		schedule: (fn: () => void, _ms: number) => {
+			const id = nextId++;
+			pending.push({ id, fn });
+			return () => {
+				const index = pending.findIndex((entry) => entry.id === id);
+				if (index !== -1) pending.splice(index, 1);
+			};
+		},
+		pendingCount: () => pending.length,
+		flushAll: () => {
+			const due = pending.splice(0, pending.length);
+			for (const entry of due) entry.fn();
+		},
+	};
+}
+
+test("createRpcActivityPublisher coalesces multiple task changes into one flush per window", () => {
+	const store = new TaskStore();
+	store.add(task("t1", "s1"));
+	const scheduler = fakeScheduler();
+	const calls: string[][] = [];
+	const publisher = createRpcActivityPublisher({ store, ui: { setWidget: (key, lines) => { assert.equal(key, ACTIVITY_WIDGET_KEY); calls.push(lines); } }, schedule: scheduler.schedule });
+
+	publisher.start();
+	assert.equal(scheduler.pendingCount(), 1, "start schedules exactly one coalescing flush");
+	store.apply("t1", { type: TASK_EVENT.TEXT, text: "hello" }, 1);
+	store.apply("t1", { type: TASK_EVENT.TEXT, text: " world" }, 2);
+	assert.equal(scheduler.pendingCount(), 1, "further changes inside the coalescing window do not add timers");
+	assert.equal(calls.length, 0, "nothing is published before the coalescing timer fires");
+
+	scheduler.flushAll();
+
+	assert.equal(calls.length, 1);
+	const activity = JSON.parse(calls[0]![0]!) as RpcActivity;
+	assert.equal(activity.schema, ACTIVITY_SCHEMA);
+	assert.equal(activity.tasks[0]!.summary.id, "t1");
+});
+
+test("createRpcActivityPublisher tracks a task created after start through the summary subscription", () => {
+	const store = new TaskStore();
+	const scheduler = fakeScheduler();
+	const calls: string[][] = [];
+	const publisher = createRpcActivityPublisher({ store, ui: { setWidget: (_key, lines) => calls.push(lines) }, schedule: scheduler.schedule });
+
+	publisher.start();
+	scheduler.flushAll();
+	calls.length = 0;
+
+	store.add(task("late-task", "s1"));
+	assert.equal(scheduler.pendingCount(), 1, "adding a task schedules a coalesced flush");
+	scheduler.flushAll();
+	calls.length = 0;
+
+	store.apply("late-task", { type: TASK_EVENT.TEXT, text: "streamed" }, 1);
+	assert.equal(scheduler.pendingCount(), 1, "the new task's own thread changes must also be tracked");
+	scheduler.flushAll();
+
+	const activity = JSON.parse(calls[0]![0]!) as RpcActivity;
+	assert.deepEqual((activity.tasks[0]!.thread.items as { text: string }[]).map((item) => item.text), ["streamed"]);
+});
+
+test("createRpcActivityPublisher stop unsubscribes everything and publishes exactly one final frame", () => {
+	const store = new TaskStore();
+	store.add(task("t1", "s1"));
+	const scheduler = fakeScheduler();
+	const calls: string[][] = [];
+	const publisher = createRpcActivityPublisher({ store, ui: { setWidget: (_key, lines) => calls.push(lines) }, schedule: scheduler.schedule });
+	publisher.start();
+	scheduler.flushAll();
+	calls.length = 0;
+
+	publisher.stop();
+
+	assert.equal(calls.length, 1, "stop publishes exactly one final frame");
+	assert.equal(scheduler.pendingCount(), 0, "stop cancels any pending coalescing timer");
+
+	store.apply("t1", { type: TASK_EVENT.TEXT, text: "after stop" }, 10);
+	assert.equal(scheduler.pendingCount(), 0, "task subscriptions are torn down by stop");
+	assert.equal(calls.length, 1, "no further frame is published after stop");
+});
+
+test("createRpcActivityPublisher flush publishes immediately and cancels a pending coalescing timer", () => {
+	const store = new TaskStore();
+	store.add(task("t1", "s1"));
+	const scheduler = fakeScheduler();
+	const calls: string[][] = [];
+	const publisher = createRpcActivityPublisher({ store, ui: { setWidget: (_key, lines) => calls.push(lines) }, schedule: scheduler.schedule });
+	publisher.start();
+	scheduler.flushAll();
+	calls.length = 0;
+
+	store.apply("t1", { type: TASK_EVENT.TEXT, text: "pending" }, 1);
+	assert.equal(scheduler.pendingCount(), 1);
+
+	publisher.flush();
+
+	assert.equal(calls.length, 1);
+	assert.equal(scheduler.pendingCount(), 0, "flush cancels the timer it preempted");
+});
+
+test("createRpcActivityPublisher swallows setWidget errors through an injectable onError", () => {
+	const store = new TaskStore();
+	store.add(task("t1", "s1"));
+	const scheduler = fakeScheduler();
+	const errors: unknown[] = [];
+	const publisher = createRpcActivityPublisher({
+		store,
+		ui: { setWidget: () => { throw new Error("boom"); } },
+		schedule: scheduler.schedule,
+		onError: (error) => errors.push(error),
+	});
+
+	assert.doesNotThrow(() => {
+		publisher.start();
+		scheduler.flushAll();
+	});
+	assert.equal(errors.length, 1);
+	assert.match(String((errors[0] as Error).message), /boom/);
+	assert.doesNotThrow(() => publisher.stop());
+});

package/tests/agents-runner.test.ts

@@ -5,6 +5,7 @@ import { AGENT_MODE, parseAgentsConfig, resolveAgentProfile, type AgentDefinitio
 import { TASK_STATUS, TaskStore, type TaskRecord } from "../lib/agents-protocol.ts";
 import { AgentRunner, childArguments, JsonLines, piCommand, abortReasonText, type ChildLike, type RunnerDeps, type RunnerHooks, type TaskRequest } from "../lib/agents-runner.ts";
 import { fakeChild, type FakeChild } from "./agents-fake-child.ts";
+import { INTERACTIVE_HOST_ENV } from "../lib/rpc-host.ts";
 
 // Gentle Agents runner: every subagent is a child `pi --mode rpc` process.
 // The host only parses JSON lines, applies deltas to the store, answers
@@ -806,6 +807,15 @@ for (const [platform, detached] of [["win32", false], ["linux", true]] as const)
 	assert.equal((await runner.waitFor(task.id)).status, TASK_STATUS.COMPLETED);
 });
 
+test("AgentRunner strips the interactive-host signal from every spawned child env", async () => {
+	const { runner, spawnOptions } = harness();
+	runner.run(request({ env: { PATH: "/fixture", [INTERACTIVE_HOST_ENV]: "1" } }));
+	await tick();
+
+	assert.equal(spawnOptions[0]?.env[INTERACTIVE_HOST_ENV], undefined, "subagent children never see the interactive-host signal");
+	assert.equal(spawnOptions[0]?.env.PATH, "/fixture", "unrelated inherited env is preserved");
+});
+
 function ipcCleanupHarness(connected: boolean | undefined) {
 	const child = fakeChild({ exitOnKill: false });
 	const disconnectListeners: Array<(...args: unknown[]) => void> = [];

package/tests/animation-policy.test.ts

@@ -0,0 +1,42 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { ANIMATION_SCHEMA, parseAnimationPolicyFile, resolveAnimationPolicy, writeAnimationPolicy } from "../lib/animation-policy.ts";
+
+test("animation policy strictly accepts only the v1 schema and three modes", () => {
+	for (const policy of ["quality", "performance", "potato"]) {
+		assert.equal(parseAnimationPolicyFile(JSON.stringify({ schema: ANIMATION_SCHEMA, policy })), policy);
+	}
+	for (const raw of ["bad", "null", "[]", '{}', '{"policy":"potato"}', ...[
+		{ schema: "gentle-pi.animations/v2", policy: "potato" },
+		{ schema: ANIMATION_SCHEMA, policy: "POTATO" },
+		{ schema: ANIMATION_SCHEMA, policy: false },
+		{ schema: ANIMATION_SCHEMA, policy: "quality", extra: true },
+	].map((value) => JSON.stringify(value))]) assert.equal(parseAnimationPolicyFile(raw), undefined);
+});
+
+test("global policy defaults to quality, persists atomically, and attributes malformed input without rewriting", () => {
+	const home = mkdtempSync(join(tmpdir(), "gp-animations-"));
+	try {
+		const options = { gentlePiConfigHome: home };
+		assert.equal(resolveAnimationPolicy(options).policy, "quality");
+		assert.equal(resolveAnimationPolicy(options).source, "default");
+		for (const policy of ["potato", "performance", "quality"] as const) {
+			const path = writeAnimationPolicy(policy, options);
+			assert.deepEqual(JSON.parse(readFileSync(path, "utf8")), { schema: ANIMATION_SCHEMA, policy });
+			assert.equal(resolveAnimationPolicy(options).policy, policy);
+			assert.equal(resolveAnimationPolicy(options).source, "global_file");
+			assert.deepEqual(readdirSync(home), ["animations.json"]);
+		}
+		const path = join(home, "animations.json");
+		writeFileSync(path, "broken");
+		const result = resolveAnimationPolicy(options);
+		assert.equal(result.policy, "quality");
+		assert.equal(result.source, "global_file");
+		assert.equal(result.malformed, true);
+		assert.equal(result.globalFile, path);
+		assert.equal(readFileSync(path, "utf8"), "broken");
+	} finally { rmSync(home, { recursive: true, force: true }); }
+});