gentle-pi 4.3.0 → 4.5.0

package/tests/main-channel.test.ts

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import * as fsPromises from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, win32 } from "node:path";
@@ -7,6 +7,7 @@ import test from "node:test";
 import {
 	CHANNEL_SCHEMA,
 	GENTLE_AI_MAIN_PACKAGE,
+	GENTLE_AI_MODULE,
 	MainChannelError,
 	buildMainGentleAi,
 	channelStatePath,
@@ -23,6 +24,8 @@ import { artifactFor } from "../scripts/installer-downloads.mjs";
 
 const SHELL_SHA = "6e7e3a18f794223396527a54c7c36d19c7d236c6";
 const AI_SHA = "1f9d5e6423e37f7d2316859045f379ba9b5d8c3a";
+const PSEUDO = "v4.0.1-0.20261008202137-1f9d5e6423e3";
+const LIST_FAILURE = "go: github.com/gentleman-programming/gentle-ai/v4@v4.0.1-0.20261008202137-1f9d5e6423e3: module lookup failed";
 const posixOnly = { skip: process.platform === "win32" };
 
 function sandbox() {
@@ -33,6 +36,38 @@ function sandbox() {
 }
 type Call = { command: string; argv: string[]; options: { env?: Record<string, string>; cwd?: string } };
 
+// Emulates the Go and binary invocations buildMainGentleAi makes, each driven by
+// what `go list -m -json` resolves, what the binary embeds, and what it prints.
+function gentleAiBuildRun(world: {
+	commit: string;
+	listVersion?: string;
+	originHash?: string;
+	embeddedVersion?: string;
+	probeVersion?: string;
+	listFails?: boolean;
+}) {
+	const { commit, listVersion = "v4.2.0", originHash = commit, embeddedVersion = listVersion, probeVersion = listVersion.replace(/^v/, ""), listFails = false } = world;
+	const calls: Call[] = [];
+	const run = async (command: string, argv: string[], options: Call["options"]) => {
+		calls.push({ command, argv, options });
+		if (argv[0] === "install") {
+			mkdirSync(options.env!.GOBIN, { recursive: true });
+			writeFileSync(join(options.env!.GOBIN, "gentle-ai"), "#!/bin/sh\n", { mode: 0o755 });
+			return { code: 0, stdout: "" };
+		}
+		if (argv[0] === "list") {
+			if (listFails) return { code: 1, stdout: "", stderrTail: `${LIST_FAILURE}\n` };
+			return { code: 0, stdout: JSON.stringify({ Path: GENTLE_AI_MODULE, Version: listVersion,
+				Origin: { VCS: "git", URL: "https://github.com/gentleman-programming/gentle-ai", Hash: originHash, Ref: "refs/tags/v4.2.0" } }) };
+		}
+		if (argv[0] === "version" && argv[1] === "-m") {
+			return { code: 0, stdout: `${command} (binary)\n\tmod\t${GENTLE_AI_MODULE}\t${embeddedVersion}\th1:J8EluS7QrfM+m3vmQlF26B/shZRjD6rBfsKtrABL5mc=\n` };
+		}
+		return { code: 0, stdout: `gentle-ai ${probeVersion}\n` };
+	};
+	return { calls, run };
+}
+
 test("channel state defaults to release and round-trips a main record", async () => {
 	const s = sandbox();
 	try {
@@ -169,18 +204,7 @@ test("Gentle AI main is built from the exact commit through Go's checksum databa
 	const s = sandbox();
 	try {
 		const goPath = join(s.root, "go", "bin", "go");
-		const calls: Call[] = [];
-		const run = async (command: string, argv: string[], options: Call["options"]) => {
-			calls.push({ command, argv, options });
-			if (argv[0] === "install") {
-				mkdirSync(options.env!.GOBIN, { recursive: true });
-				const binary = join(options.env!.GOBIN, "gentle-ai");
-				writeFileSync(binary, "#!/bin/sh\n");
-				chmodSync(binary, 0o755);
-				return { code: 0, stdout: "" };
-			}
-			return { code: 0, stdout: "gentle-ai 4.0.1-0.20261008202137-1f9d5e6423e3\n" };
-		};
+		const { calls, run } = gentleAiBuildRun({ commit: AI_SHA, listVersion: PSEUDO });
 		const built = await buildMainGentleAi({ commit: AI_SHA, ctx: s.ctx, platform: "darwin", goPath, run, fs: fsPromises });
 		const install = calls[0];
 		assert.equal(install.command, goPath);
@@ -194,19 +218,107 @@ test("Gentle AI main is built from the exact commit through Go's checksum databa
 	} finally { s.cleanup(); }
 });
 
-test("a Gentle AI build whose version names another commit is rejected and never registered", posixOnly, async () => {
+// #2301: when main's HEAD is exactly a tag commit, Go stamps the tag (v4.2.0), not a
+// pseudo-version, so the suffix check alone rejects every tagged release.
+test("a main commit that is exactly a release tag is accepted when Go resolves that tag to the commit", posixOnly, async () => {
 	const s = sandbox();
 	try {
-		const run = async (_command: string, argv: string[], options: Call["options"]) => {
-			if (argv[0] === "install") {
-				mkdirSync(options.env!.GOBIN, { recursive: true });
-				writeFileSync(join(options.env!.GOBIN, "gentle-ai"), "#!/bin/sh\n", { mode: 0o755 });
-			}
-			return { code: 0, stdout: "gentle-ai 4.0.1-0.20261008202137-aaaaaaaaaaaa\n" };
-		};
+		const TAGGED = "4acaf4241beae1e0c977c92dfe406a270f8d40de";
+		const { run } = gentleAiBuildRun({ commit: TAGGED, listVersion: "v4.2.0", originHash: TAGGED });
+		const built = await buildMainGentleAi({ commit: TAGGED, ctx: s.ctx, platform: "darwin", goPath: "/go/bin/go", run, fs: fsPromises });
+		assert.equal(built.binaryPath, join(s.home, ".pi", "gentle-ai", "main", "gentle-ai", TAGGED, "gentle-ai"));
+		assert.equal(built.version, "4.2.0");
+		assert.deepEqual(JSON.parse(readFileSync(join(s.home, ".pi", "gentle-ai", "dev-binary.json"), "utf8")),
+			{ schema: "gentle-pi.dev-binary/v1", path: built.binaryPath });
+	} finally { s.cleanup(); }
+});
+
+test("a go list whose Origin.Hash names another commit is rejected, and the build is removed", posixOnly, async () => {
+	const s = sandbox();
+	try {
+		const OTHER = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+		const { run } = gentleAiBuildRun({ commit: AI_SHA, listVersion: PSEUDO, originHash: OTHER });
+		await assert.rejects(buildMainGentleAi({ commit: AI_SHA, ctx: s.ctx, platform: "darwin", goPath: "/go/bin/go", run, fs: fsPromises }),
+			(error: MainChannelError) => error.code === "main-gentle-ai-unverified" && error.message.includes(OTHER) && error.message.includes(AI_SHA.slice(0, 12)));
+		assert.equal(existsSync(join(s.home, ".pi", "gentle-ai", "dev-binary.json")), false);
+		assert.equal(existsSync(join(s.home, ".pi", "gentle-ai", "main", "gentle-ai", AI_SHA)), false);
+		assert.equal(existsSync(join(s.home, ".pi", "gentle-ai", "main", ".build")), false);
+	} finally { s.cleanup(); }
+});
+
+test("a binary whose embedded module version differs from what Go resolved is rejected and never registered", posixOnly, async () => {
+	const s = sandbox();
+	try {
+		const { run } = gentleAiBuildRun({ commit: AI_SHA, listVersion: PSEUDO, embeddedVersion: "v4.1.2" });
+		await assert.rejects(buildMainGentleAi({ commit: AI_SHA, ctx: s.ctx, platform: "darwin", goPath: "/go/bin/go", run, fs: fsPromises }),
+			(error: MainChannelError) => error.code === "main-gentle-ai-unverified");
+		assert.equal(existsSync(join(s.home, ".pi", "gentle-ai", "dev-binary.json")), false);
+		assert.equal(existsSync(join(s.home, ".pi", "gentle-ai", "main", "gentle-ai", AI_SHA)), false);
+	} finally { s.cleanup(); }
+});
+
+test("a failed go list is rejected as unverified, with its stderr tail as the cause, and nothing is registered", posixOnly, async () => {
+	const s = sandbox();
+	try {
+		const { run } = gentleAiBuildRun({ commit: AI_SHA, listVersion: PSEUDO, listFails: true });
+		await assert.rejects(buildMainGentleAi({ commit: AI_SHA, ctx: s.ctx, platform: "darwin", goPath: "/go/bin/go", run, fs: fsPromises }),
+			(error: MainChannelError) => error.code === "main-gentle-ai-unverified" && error.cause instanceof Error && error.cause.message === LIST_FAILURE);
+		assert.equal(existsSync(join(s.home, ".pi", "gentle-ai", "dev-binary.json")), false);
+		assert.equal(existsSync(join(s.home, ".pi", "gentle-ai", "main", "gentle-ai", AI_SHA)), false);
+	} finally { s.cleanup(); }
+});
+
+// Rebuilding a commit that is already registered (a rerun wizard step, a lost
+// channel record) must not delete the working override when verification fails.
+for (const [name, failure] of Object.entries({
+	"go list fails": { listFails: true },
+	"the embedded version differs": { embeddedVersion: "v4.1.2" },
+	"the reported version differs": { probeVersion: "4.0.1-0.20261008202137-aaaaaaaaaaaa" },
+})) test(`a registered build of the same commit survives a rebuild whose verification fails because ${name}`, posixOnly, async () => {
+	const s = sandbox();
+	try {
+		const directory = join(s.home, ".pi", "gentle-ai", "main", "gentle-ai", AI_SHA);
+		const binary = join(directory, "gentle-ai");
+		const registration = join(s.home, ".pi", "gentle-ai", "dev-binary.json");
+		mkdirSync(directory, { recursive: true });
+		writeFileSync(binary, "#!/bin/sh\n# registered\n", { mode: 0o755 });
+		const record = JSON.stringify({ schema: "gentle-pi.dev-binary/v1", path: binary });
+		writeFileSync(registration, record);
+		const { run } = gentleAiBuildRun({ commit: AI_SHA, listVersion: PSEUDO, ...failure });
+		await assert.rejects(buildMainGentleAi({ commit: AI_SHA, ctx: s.ctx, platform: "darwin", goPath: "/go/bin/go", run, fs: fsPromises }),
+			(error: MainChannelError) => error.code === "main-gentle-ai-unverified");
+		assert.equal(readFileSync(binary, "utf8"), "#!/bin/sh\n# registered\n");
+		assert.equal(readFileSync(registration, "utf8"), record);
+		assert.deepEqual(readdirSync(join(s.home, ".pi", "gentle-ai", "main", "gentle-ai")), [AI_SHA]);
+		assert.equal(existsSync(join(s.home, ".pi", "gentle-ai", "main", ".build")), false);
+	} finally { s.cleanup(); }
+});
+
+test("go list and go version -m run with the same sealed environment and cwd as go install", posixOnly, async () => {
+	const s = sandbox();
+	try {
+		const goPath = join(s.root, "go", "bin", "go");
+		const { calls, run } = gentleAiBuildRun({ commit: AI_SHA, listVersion: PSEUDO });
+		await buildMainGentleAi({ commit: AI_SHA, ctx: s.ctx, platform: "darwin", goPath, run, fs: fsPromises });
+		const sealed = { GOPROXY: "https://proxy.golang.org", GOSUMDB: "sum.golang.org", GOTOOLCHAIN: "local",
+			GOFLAGS: "-modcacherw", GONOSUMDB: "", GOPRIVATE: "", GOINSECURE: "", GOENV: "off", GOWORK: "off" };
+		const goCalls = calls.filter((call) => call.command === goPath);
+		assert.deepEqual(goCalls.map((call) => call.argv[0]), ["install", "list", "version"]);
+		for (const call of goCalls) {
+			assert.equal(call.options.cwd, join(s.home, ".pi", "gentle-ai", "main", ".build"), call.argv.join(" "));
+			for (const [key, value] of Object.entries(sealed)) assert.equal(call.options.env![key], value, `${key} for ${call.argv.join(" ")}`);
+		}
+	} finally { s.cleanup(); }
+});
+
+test("a Gentle AI build whose reported version differs from the resolved module version is rejected and never registered", posixOnly, async () => {
+	const s = sandbox();
+	try {
+		const { run } = gentleAiBuildRun({ commit: AI_SHA, listVersion: PSEUDO, probeVersion: "4.0.1-0.20261008202137-aaaaaaaaaaaa" });
 		await assert.rejects(buildMainGentleAi({ commit: AI_SHA, ctx: s.ctx, platform: "darwin", goPath: "/go/bin/go", run, fs: fsPromises }),
 			(error: MainChannelError) => error.code === "main-gentle-ai-unverified");
 		assert.equal(existsSync(join(s.home, ".pi", "gentle-ai", "dev-binary.json")), false);
+		assert.equal(existsSync(join(s.home, ".pi", "gentle-ai", "main", "gentle-ai", AI_SHA)), false);
 	} finally { s.cleanup(); }
 });
 
@@ -278,6 +390,13 @@ async function upgradeWorld({ userGo = null as string | null, pinned = false, ac
 	const fetch = async (url: string) => ({ ok: true, status: 200, text: async () => (url.endsWith("/gentle-ai/commits/main") ? NEW_AI : SHELL_SHA) });
 	const run = async (command: string, argv: string[], options: Call["options"]) => {
 		calls.push({ command, argv, options });
+		const isGo = command === "/usr/bin/go" || command === pinnedGo;
+		const pseudo = (commit: string) => `v4.0.1-0.20261008202137-${commit.slice(0, 12)}`;
+		if (isGo && argv[0] === "version" && argv[1] === "-m") return { code: 0, stdout: `${command} (binary)\n\tmod\t${GENTLE_AI_MODULE}\t${pseudo(NEW_AI)}\th1:J8EluS7QrfM+m3vmQlF26B/shZRjD6rBfsKtrABL5mc=\n` };
+		if (isGo && argv[0] === "list") {
+			const requested = argv[3].slice(`${GENTLE_AI_MODULE}@`.length);
+			return { code: 0, stdout: JSON.stringify({ Path: GENTLE_AI_MODULE, Version: pseudo(requested), Origin: { VCS: "git", URL: "https://github.com/gentleman-programming/gentle-ai", Hash: requested } }) };
+		}
 		if (command === "/usr/bin/go" && argv[0] === "version") return { code: 0, stdout: `go version ${userGo === "devel" ? "devel go1.26-abc" : `go${userGo}`} darwin/arm64\n` };
 		if (argv[0] === "install") {
 			mkdirSync(options.env!.GOBIN, { recursive: true });

package/tests/model-profiles-preservation.test.ts

@@ -7,7 +7,7 @@ import test from "node:test";
 import { applyModelConfig, applyModelConfigAsync, applySavedModelConfig } from "../extensions/gentle-ai.ts";
 
 // gentle-ai#4946: the activation sweep re-applies saved routing without user
-// consent. Persisted clear entries (an "inherit" saved from /gentle:models is
+// consent. Persisted clear entries (an "inherit" saved from /gentle:profiles is
 // `{}`) must not delete `model_profiles` entries the user authored in the
 // agent-home `subagents.json`. Clearing stays owned by the consented flows
 // that issue it: the panel save and a confirmed profile apply.
@@ -66,7 +66,7 @@ function preservedProfilesFixture(t: test.TestContext) {
 
 test("startup sweep keeps user model_profiles entries for persisted clears", async (t) => {
 	const fixture = preservedProfilesFixture(t);
-	// Saved routing as /gentle:models leaves it after pressing "inherit" on
+	// Saved routing as /gentle:profiles leaves it after pressing "inherit" on
 	// worker: a persisted clear entry. The sweep must not delete the entries.
 	writeFileSync(fixture.globalModelsPath, JSON.stringify({ worker: {} }));
 	const result = await applySavedModelConfig(fixture.context);

package/tests/nan-provider.test.ts

@@ -3,6 +3,7 @@ import test from "node:test";
 import type { RefreshModelsContext } from "@earendil-works/pi-ai";
 import { clampThinkingLevel, createModels, getSupportedThinkingLevels, InMemoryCredentialStore } from "@earendil-works/pi-ai";
 import type { Provider } from "@earendil-works/pi-ai";
+import { completeSimple } from "@earendil-works/pi-ai/compat";
 import nanProviderExtension from "../extensions/nan-provider.ts";
 import { createNanProviderConfig as createNativeProvider, isNanAdaptiveReasoningModel, NAN_PROVIDER_BASE_URL, NAN_PROVIDER_ID } from "../lib/nan-provider.ts";
 
@@ -195,6 +196,41 @@ test("initial catalog contains all seven documented chat models with configured
 	assert.deepEqual(model?.cost, { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 });
 });
 
+test("only NaN DeepSeek serializes its unchanged output cap as max_tokens", async () => {
+	const models = createNativeProvider().getModels();
+	const model = models.find((model) => model.id === "deepseek-v4-flash")!;
+	let body: Record<string, unknown> | undefined;
+	const result = await completeSimple(model, { messages: [{ role: "user", content: "offline probe", timestamp: 0 }] }, {
+		apiKey: "synthetic-key", reasoning: "minimal",
+		fetch: async (input, init) => {
+			assert.equal(String(input), `${NAN_PROVIDER_BASE_URL}/chat/completions`);
+			body = JSON.parse(String(init?.body));
+			return new Response('data: {"id":"offline","choices":[{"index":0,"delta":{"role":"assistant","content":"ok"},"finish_reason":"stop"}]}\n\ndata: [DONE]\n\n', {
+				headers: { "content-type": "text/event-stream" },
+			});
+		},
+	});
+	assert.equal(result.stopReason, "stop");
+	assert.equal(body?.max_tokens, 16_384);
+	assert.ok(!Object.hasOwn(body!, "max_completion_tokens"));
+	assert.equal(body?.reasoning_effort, "minimal");
+	assert.equal(model.maxTokens, 16_384);
+	assert.equal(model.compat?.maxTokensField, "max_tokens");
+	assert.ok(models.filter((candidate) => candidate.id !== model.id).every((candidate) => candidate.compat === undefined));
+});
+
+test("DeepSeek compat is isolated across snapshots, providers, and live refreshes", async () => {
+	const provider = createNativeProvider({ fetchImpl: async () => jsonResponse({ data: [{ id: "deepseek-v4-flash" }] }) });
+	for (const live of [false, true]) {
+		if (live) await provider.refreshModels!(refreshContext({ type: "api_key", key: "synthetic-key" }));
+		const model = provider.getModels().find((model) => model.id === "deepseek-v4-flash")!;
+		assert.equal(model.compat?.maxTokensField, "max_tokens");
+		model.compat!.maxTokensField = "max_completion_tokens";
+		assert.equal(provider.getModels().find((candidate) => candidate.id === model.id)!.compat?.maxTokensField, "max_tokens");
+		assert.equal(createNativeProvider().getModels().find((model) => model.id === "deepseek-v4-flash")!.compat?.maxTokensField, "max_tokens");
+	}
+});
+
 test("GLM models expose exactly NaN's four efforts and no off", () => {
 	const models = createNativeProvider().getModels();
 	for (const id of ["glm5.3", "glm5.3-flash"]) {

package/tests/native-review-capability-contract.test.ts

@@ -103,9 +103,10 @@ test("2.4.0 repeats 2.2.3 because the START envelope Pi consumes still omits ris
 	//             the envelope carries, not a capability it lost.
 	//   delivery  `review validate --gate pre-commit` still answers
 	//             `gentle-ai.review-gate-result/v1` with
-	//             `delivery: "disabled/unmanaged"` at exit 0. Under opt-in RDD
-	//             this is now the DEFAULT delivery answer for an install that
-	//             never enabled review, so the column matters more, not less.
+	//             `delivery: "disabled/unmanaged"` at exit 0. RDD is on by
+	//             default again since gentle-ai v4.0.0, so this is the answer
+	//             for an install that turned review off, and the column still
+	//             matters.
 	//
 	// riskEvidence and hint stay dark for exactly the reason the 2.2.0 comment
 	// gives, re-proven rather than inherited: the negotiated
@@ -385,11 +386,17 @@ test("4.2.0 explicitly repeats 4.1.1 because capabilities/v2.6 is unchanged desp
 	assert.deepEqual(contract, NATIVE_CLI_CONTRACTS["4.1.1"] as Record<string, boolean>);
 });
 
+test("4.3.1 explicitly repeats 4.2.0 because capabilities/v2.6 and provider contract 1.4.0 are unchanged", () => {
+	const contract = NATIVE_CLI_CONTRACTS["4.3.1"] as Record<string, boolean>;
+	assert.ok(contract);
+	assert.deepEqual(contract, NATIVE_CLI_CONTRACTS["4.2.0"] as Record<string, boolean>);
+});
+
 test("no shipped version key was added beyond the pin bump", () => {
 	// Rows are promises to consumers, so a new key only ever appears in a
 	// dedicated commit alongside a pin bump, never as a side effect. v2.2.4 and
 	// v2.3.0 shipped upstream while Pi stayed on 2.2.3 and were never pinned,
 	// so they get no row: a row asserts ground truth measured against a binary
 	// Pi actually ran, and the table only has to be ascending, not gapless.
-	assert.deepEqual(Object.keys(NATIVE_CLI_CONTRACTS), [...DARK_VERSIONS, "2.2.0", "2.2.1", "2.2.2", "2.2.3", "2.4.0", "2.5.0-rc.3", "2.5.0", "2.6.0", "2.7.0", "2.8.0", "2.8.1", "2.8.2", "2.9.0", "2.9.1", "3.0.0", "3.0.1", "3.1.0", "3.2.1", "3.4.0", "3.5.0", "3.6.0", "3.6.1", "3.7.0", "4.0.0", "4.1.1", "4.2.0"]);
+	assert.deepEqual(Object.keys(NATIVE_CLI_CONTRACTS), [...DARK_VERSIONS, "2.2.0", "2.2.1", "2.2.2", "2.2.3", "2.4.0", "2.5.0-rc.3", "2.5.0", "2.6.0", "2.7.0", "2.8.0", "2.8.1", "2.8.2", "2.9.0", "2.9.1", "3.0.0", "3.0.1", "3.1.0", "3.2.1", "3.4.0", "3.5.0", "3.6.0", "3.6.1", "3.7.0", "4.0.0", "4.1.1", "4.2.0", "4.3.1"]);
 });

package/tests/native-review-parity.test.ts

@@ -384,7 +384,7 @@ test("review-mode gate retains every off-source continuation and fails closed on
 	for (const [source, expected] of [
 		["clone_local", /clear this clone-local override/],
 		["global", /cannot override a global off/],
-		["default", /off by default until explicitly enabled/],
+		["default", /RDD is on by default, but this install could not resolve the review mode and failed closed to off/],
 	] as const) {
 		const native = {
 			reviewMode: async () => ({ operation: "status", scope: "clone", status: { global: source === "global" ? "off" : "", cloneLocal: source === "clone_local" ? "off" : "", effective: "off" as const, source } }),

package/tests/notification-audio-native.test.ts

@@ -1,9 +1,11 @@
 import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
 import { EventEmitter } from "node:events";
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { createServer, type Server } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { test } from "node:test";
 import { NativePulsePlayer, NATIVE_PULSE_SCHEMA, type NativePulseOptions, type NativePulseSpawnOptions } from "../lib/notification-audio-native.ts";
 
@@ -75,9 +77,12 @@ async function startFakeServer(): Promise<FakeServer> {
 class FakeChild extends EventEmitter {
 	readonly stdout = new EventEmitter();
 	readonly stderr = new EventEmitter();
+	readonly stdin = { writes: [] as string[], write(chunk: string): boolean { this.writes.push(chunk); return true; } };
 	readonly kills: string[] = [];
 	kill(signal: string): boolean { this.kills.push(signal); return true; }
 }
+const okPlay = (): string => `${JSON.stringify({ schema: NATIVE_PULSE_SCHEMA, ok: true, played: true })}\n`;
+const failPlay = (): string => `${JSON.stringify({ schema: NATIVE_PULSE_SCHEMA, ok: false })}\n`;
 function recorder(platform = "linux", overrides: Partial<NativePulseOptions> = {}) {
 	const spawned: Array<{ executable: string; args: string[]; options: NativePulseSpawnOptions }> = [];
 	const children: FakeChild[] = [];
@@ -135,11 +140,77 @@ test("play gate false prevents spawning and no async runs after it", async () =>
 	const { player: second, spawned: secondSpawned, children } = recorder();
 	const playing = second.play("/tmp/s.wav", undefined, { permit: () => true });
 	assert.equal(secondSpawned.length, 1);
-	children[0]!.stdout.emit("data", JSON.stringify({ schema: NATIVE_PULSE_SCHEMA, ok: true, played: true }));
-	children[0]!.emit("close");
+	children[0]!.stdout.emit("data", okPlay());
 	await playing;
 });
 
+/** N plays must reuse ONE persistent `serve` worker: spawn once, queue, answer one envelope per play. */
+test("persistent serve worker: N plays spawn exactly one worker and each play succeeds", async () => {
+	const { player, spawned, children } = recorder();
+	const paths = ["/tmp/a.wav", "/tmp/b.wav", "/tmp/c.wav"];
+	const plays = paths.map(path => player.play(path));
+	assert.equal(spawned.length, 1, "N plays must spawn exactly one serve worker");
+	assert.equal(spawned[0]!.args[3], "serve");
+	assert.deepEqual(spawned[0]!.options.stdio, ["pipe", "pipe", "pipe"]);
+	assert.equal(children[0]!.stdin.writes.length, 1, "queued plays must not write until the active play settles");
+	for (const write of children[0]!.stdin.writes) {
+		const request = JSON.parse(write) as { schema: string; op: string; path: string };
+		assert.equal(request.schema, NATIVE_PULSE_SCHEMA); assert.equal(request.op, "play"); assert.equal(request.path, paths[0]);
+	}
+	for (let i = 0; i < plays.length; i++) children[0]!.stdout.emit("data", okPlay());
+	await Promise.all(plays);
+	assert.equal(spawned.length, 1);
+	assert.equal(children[0]!.stdin.writes.length, 3);
+	assert.deepEqual(children[0]!.stdin.writes.map(write => (JSON.parse(write) as { path: string }).path), paths);
+});
+
+test("a crashed serve worker is replaced by a fresh spawn on the next play", async () => {
+	const { player, spawned, children } = recorder();
+	const first = player.play("/tmp/a.wav");
+	children[0]!.stdout.emit("data", okPlay());
+	await first;
+	children[0]!.emit("close"); // crash while idle
+	const second = player.play("/tmp/b.wav");
+	assert.equal(spawned.length, 2, "the next play must spawn a fresh worker after a crash");
+	assert.equal(spawned[1]!.args[3], "serve");
+	children[1]!.stdout.emit("data", okPlay());
+	await second;
+});
+
+test("a crash with a play in flight fails that play privately and the next play spawns fresh", async () => {
+	const { player, spawned, children } = recorder();
+	const failing = player.play("/tmp/a.wav");
+	children[0]!.emit("close");
+	await assert.rejects(failing, /Native pulse/);
+	const next = player.play("/tmp/b.wav");
+	assert.equal(spawned.length, 2);
+	children[1]!.stdout.emit("data", okPlay());
+	await next;
+});
+
+test("dispose kills the persistent worker, fails pending plays and the next play spawns fresh", async () => {
+	const { player, spawned, children } = recorder();
+	const playing = player.play("/tmp/a.wav");
+	player.dispose();
+	assert.deepEqual(children[0]!.kills, ["SIGKILL"]);
+	await assert.rejects(playing, /Native pulse/);
+	const next = player.play("/tmp/b.wav");
+	assert.equal(spawned.length, 2);
+	children[1]!.stdout.emit("data", okPlay());
+	await next;
+	player.dispose(); // a second dispose is a no-op
+});
+
+test("pending plays are bounded fail-closed and never grow without bound", async () => {
+	const { player, spawned, children } = recorder();
+	const plays = Array.from({ length: 10 }, (_, i) => player.play(`/tmp/${i}.wav`).catch(error => error));
+	assert.equal(spawned.length, 1);
+	assert.match(String(await plays[9]), /too many pending/);
+	for (let i = 0; i < 9; i++) children[0]!.stdout.emit("data", okPlay()); // settle active + queued
+	const settled = await Promise.all(plays);
+	assert.equal(settled.filter(value => value instanceof Error).length, 1);
+});
+
 test("malformed, oversize and error output fail privately and kill at most once", async () => {
 	const malformed = recorder();
 	const malformedProbe = malformed.player.probe();
@@ -158,9 +229,11 @@ test("malformed, oversize and error output fail privately and kill at most once"
 
 	const failure = recorder();
 	const playing = failure.player.play("/private/snapshot.wav");
-	failure.children[0]!.stdout.emit("data", JSON.stringify({ schema: NATIVE_PULSE_SCHEMA, ok: false }));
-	failure.children[0]!.emit("close");
+	failure.children[0]!.stdout.emit("data", failPlay());
+	// A private ok:false leaves the healthy worker serviceable; no kill, no restart needed.
 	await assert.rejects(playing, (error: Error) => /Native pulse/.test(error.message) && !/snapshot|cookie|\/private/.test(error.message));
+	assert.equal(failure.children[0]!.kills.length, 0);
+	assert.equal(failure.spawned.length, 1);
 });
 
 test("timeout and abort SIGKILL once and settle only on close", async () => {
@@ -181,6 +254,11 @@ test("timeout and abort SIGKILL once and settle only on close", async () => {
 	const playing = aborted.player.play("/tmp/s.wav", controller.signal);
 	controller.abort();
 	assert.deepEqual(aborted.children[0]!.kills, ["SIGKILL"]);
+	let abortSettled = false; void playing.then(() => { abortSettled = true; }, () => { abortSettled = true; });
+	aborted.children[0]!.emit("exit", null);
+	aborted.children[0]!.emit("error", new Error("kill race")); // Node emits close after error
+	await new Promise(resolve => setTimeout(resolve, 0));
+	assert.equal(abortSettled, false);
 	aborted.children[0]!.emit("close");
 	await assert.rejects(playing, /aborted|Native pulse/);
 });
@@ -210,7 +288,8 @@ test("probe never throws for offline/malformed IPC while play rejects and cleans
 	assert.deepEqual(await probing, { available: false, formats: [] });
 	const { player: playPlayer, children: playChildren } = recorder();
 	const playing = playPlayer.play("/tmp/s.wav");
-	playChildren[0]!.stdout.emit("data", JSON.stringify({ schema: "wrong", ok: true, played: true }));
+	playChildren[0]!.stdout.emit("data", `${JSON.stringify({ schema: "wrong", ok: true, played: true })}\n`);
+	assert.deepEqual(playChildren[0]!.kills, ["SIGKILL"], "a malformed serve line is a protocol violation: kill once");
 	playChildren[0]!.emit("close");
 	await assert.rejects(playing, /Native pulse/);
 });
@@ -259,13 +338,13 @@ test("real worker plays a fake PCM snapshot to a fake socket with no OS audio",
 	const snapshot = join(dir, "sound.wav");
 	writeFileSync(snapshot, bytes, { mode: 0o400 });
 	const server = await startFakeServer();
+	const player = new NativePulsePlayer({ platform: "linux", env: { PULSE_SERVER: `unix:${server.path}` }, playTimeoutMs: 8000 });
 	try {
-		const player = new NativePulsePlayer({ platform: "linux", env: { PULSE_SERVER: `unix:${server.path}` }, playTimeoutMs: 8000 });
 		await player.play(snapshot);
 		assert.deepEqual(Buffer.concat(server.pcm), dataOf(bytes));
 		assert.ok(server.seen.includes(3) && server.seen.includes(12) && server.seen.includes(4));
 		assert.ok(existsSync(snapshot), "the bridge/worker must not delete the snapshot; the owner does");
-	} finally { await server.close(); rmSync(dir, { recursive: true, force: true }); }
+	} finally { player.dispose(); await server.close(); rmSync(dir, { recursive: true, force: true }); }
 });
 
 test("real worker rejects invalid WAV before opening the socket", async () => {
@@ -273,9 +352,49 @@ test("real worker rejects invalid WAV before opening the socket", async () => {
 	const snapshot = join(dir, "sound.wav");
 	writeFileSync(snapshot, Buffer.alloc(64, 0x00), { mode: 0o400 });
 	const server = await startFakeServer();
+	const player = new NativePulsePlayer({ platform: "linux", env: { PULSE_SERVER: `unix:${server.path}` }, playTimeoutMs: 8000 });
 	try {
-		const player = new NativePulsePlayer({ platform: "linux", env: { PULSE_SERVER: `unix:${server.path}` }, playTimeoutMs: 8000 });
 		await assert.rejects(player.play(snapshot), /Native pulse/);
 		assert.deepEqual(server.seen, []);
-	} finally { await server.close(); rmSync(dir, { recursive: true, force: true }); }
+	} finally { player.dispose(); await server.close(); rmSync(dir, { recursive: true, force: true }); }
+});
+
+/** Direct serve-protocol check: bounded fail-closed requests, private per-play failures, stdin EOF teardown. */
+test("real serve worker fails closed on protocol violations and exits on stdin EOF", async () => {
+	const workerPath = fileURLToPath(new URL("../lib/notification-pulse-worker.ts", import.meta.url));
+	const serveEnv = { ...process.env, NODE_NO_WARNINGS: "1", GENTLE_PI_AGENTS_CHILD: "1" };
+	const spawnServe = () => spawn(process.execPath, ["--experimental-strip-types", workerPath, "serve"],
+		{ stdio: ["pipe", "pipe", "pipe"], env: serveEnv });
+	const collect = (child: ReturnType<typeof spawn>): string[] => {
+		const lines: string[] = []; let text = "";
+		child.stdout!.setEncoding("utf8");
+		child.stdout!.on("data", (chunk: string) => {
+			text += chunk;
+			for (let index = text.indexOf("\n"); index !== -1; index = text.indexOf("\n")) { lines.push(text.slice(0, index)); text = text.slice(index + 1); }
+		});
+		return lines;
+	};
+	const exited = (child: ReturnType<typeof spawn>): Promise<number | null> => new Promise(resolve => {
+		if (child.exitCode !== null || child.signalCode !== null) { resolve(child.exitCode); return; }
+		child.once("exit", code => resolve(code));
+	});
+	// (a) A malformed line is a protocol violation: one generic envelope, then a crash the owner restarts.
+	const crashing = spawnServe();
+	const crashingLines = collect(crashing);
+	crashing.stdin!.write("not json\n");
+	assert.equal(await exited(crashing), 1);
+	assert.deepEqual(await crashingLines, [JSON.stringify({ schema: "gentle.audio.pulse/v1", ok: false })]);
+	// (b) A schema-valid request for a missing snapshot fails privately and the worker keeps serving.
+	const serving = spawnServe();
+	const servingLines = collect(serving);
+	for (const path of ["/nonexistent/gentle-a.wav", "/nonexistent/gentle-b.wav"])
+		serving.stdin!.write(`${JSON.stringify({ schema: "gentle.audio.pulse/v1", op: "play", path })}\n`);
+	await new Promise(resolve => setTimeout(resolve, 1200));
+	assert.deepEqual(servingLines, [
+		JSON.stringify({ schema: "gentle.audio.pulse/v1", ok: false }),
+		JSON.stringify({ schema: "gentle.audio.pulse/v1", ok: false }),
+	]);
+	// (c) stdin EOF (owner death) is a clean exit.
+	serving.stdin!.end();
+	assert.equal(await exited(serving), 0);
 });

package/tests/notification-customize.test.ts

@@ -10,6 +10,15 @@ import { basename } from "node:path";
 
 const tick = () => new Promise<void>((resolve) => setImmediate(resolve));
 
+/** UI chains settle across a load-dependent number of turns: wait on the
+ * observable state instead of assuming a fixed tick count landed the async
+ * step (gentle-shell#2498). The deadline keeps a broken chain failing fast. */
+const settleUntil = async (predicate: () => boolean, what: string): Promise<void> => {
+	const deadline = Date.now() + 5000;
+	while (!predicate() && Date.now() < deadline) await tick();
+	assert.ok(predicate(), `timed out waiting for ${what}`);
+};
+
 /** Real packaged WAVs so a valid path uses an existing fixture, never a synthetic name. */
 const WAV_FIXTURE = fileURLToPath(new URL("../assets/sounds/success.wav", import.meta.url));
 const WAV_FIXTURES = {
@@ -223,7 +232,7 @@ test("an in-flight local sound validation keeps busy, blocking a second field an
 		assert.match(view.render(160).join("\n"), /Local audio path/);
 		view.handleInput(WAV_FIXTURE);
 		view.handleInput("\r");
-		await tick();
+		await settleUntil(() => validated.length === 1, "the submitted value to start validating");
 		assert.deepEqual(validated, [`file:${WAV_FIXTURE}`], "the submitted value is validated exactly once");
 		// Validation is still pending: `f` must not open a second field and Enter must not write.
 		view.handleInput("f");
@@ -233,11 +242,11 @@ test("an in-flight local sound validation keeps busy, blocking a second field an
 		assert.equal(h.writes, 0, "no write before the deferred validation resolves");
 		// Resolve: a single write, then busy releases for the next edit.
 		resolveValidation(true);
-		await tick(); await tick();
+		await settleUntil(() => h.writes === 1, "the resolved validation to write exactly once");
 		assert.equal(h.writes, 1, "the resolved validation writes exactly once");
 		assert.equal(getNotificationService()!.getState().settings.audio.events["agent.failed"], `file:${WAV_FIXTURE}`);
 		view.handleInput("f");
-		assert.match(view.render(160).join("\n"), /Local audio path/, "busy is released so the next edit opens a fresh field");
+		await settleUntil(() => view.render(160).join("\n").includes("Local audio path"), "busy released so the next edit opens a fresh field");
 	} finally { h.owner.retire(); }
 });
 
@@ -262,14 +271,17 @@ test("disposing the card while validation is in flight never writes the stale ch
 	const h = harness(); try {
 		const rows = h.rows();
 		let resolveValidation!: (value: boolean) => void;
-		getNotificationService()!.validateFile = () => new Promise<boolean>(resolve => { resolveValidation = resolve; });
+		let validationStarted = false;
+		getNotificationService()!.validateFile = () => { validationStarted = true; return new Promise<boolean>(resolve => { resolveValidation = resolve; }); };
 		const view = customizeView(rows);
 		await expandAndSelect(view, "agent.failed:");
 		view.handleInput("f");
 		view.render(160);
 		view.handleInput(WAV_FIXTURE);
 		view.handleInput("\r");
-		await tick();
+		// Disposing before the validation even starts would never observe the
+		// stale-choice guard, so wait until the deferred validation is pending.
+		await settleUntil(() => validationStarted, "the in-flight validation to start");
 		view.dispose();
 		resolveValidation(true);
 		await tick(); await tick();

package/tests/odd-routing-canonical-ratchet.test.ts

@@ -149,7 +149,8 @@ const ANCHORS: readonly RoutingAnchor[] = [
 		canonical: "run a differential check",
 		mirrors: [
 			{ surface: DELEGATION, includes: "**Differential check (PRESERVE):**" },
-			{ surface: EXTENSION, includes: "run a differential check" },
+			// weak-model-economy S2: the harness gates the check on shared code an unnamed command uses.
+			{ surface: EXTENSION, includes: "run one differential check" },
 		],
 	},
 	{

package/tests/orchestrator-budget.test.ts

@@ -33,7 +33,10 @@ const FIXTURE_PATH = join(import.meta.dirname, "fixtures", "orchestrator.pre-die
 // gentle-shell#1731 T10 (user decision): 8,192 -> 8,400 B for the narrowed high-risk items 1 and 3.
 // Verification by named risk (escalate-only rule 3) and the writer-rule fix (triggers hold only when
 // their condition holds; a unit is independent behavior over a size floor), user decision 2026-10-14: 8,400 -> 9,100 B.
-const BUDGET_BYTES = 9100;
+// Weak-model economy (small path reads one batch with no todo; item 1 excludes rebuildable dev/test data), measured in
+// gentle-shell-bench 1321c60 (DeepSeek -24-30% time on x2/x5, -70% on a dev-database rename; Sol unchanged), user decision
+// 2026-10-22: 9,100 -> 9,250 B.
+const BUDGET_BYTES = 9250;
 const MIN_CONTROLLED_LONG_ASSETS_ROOT_CHARS = 93;
 
 const LAZY_ASSET_NAMES = [
@@ -126,7 +129,7 @@ function measureOrchestratorPromptBytes(assetsDir: string): number {
 // measuring a shorter render again.
 const RDD_WORST_CASE_LINE = "Receipt-driven development: unknown (native status unavailable)";
 
-test("getOrchestratorPrompt return value stays within the canonical 9,100 B budget at a short assets root", () => {
+test("getOrchestratorPrompt return value stays within the canonical 9,250 B budget at a short assets root", () => {
 	const rendered = __testing.renderOrchestratorPrompt(representativeProductionAssetsDir);
 	assert.ok(
 		rendered.includes(RDD_WORST_CASE_LINE),