gentle-pi 4.0.0 → 4.2.0

package/tests/package-manifest.test.ts

@@ -1,4 +1,5 @@
 import assert from "node:assert/strict";
+import { parseNpmPackResult } from "../scripts/npm-pack-result.mjs";
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import {
@@ -60,7 +61,7 @@ const V014_MANAGED_ASSETS = join(
 // gentle-ai-explore.md as their exemplar (packaged, absent from the v0.13
 // manifest) after review-refuter.md was retired together with every
 // Pi-authored adversarial review verdict.
-const MANAGED_EXEMPLAR_TOOLS = ["read", "grep", "find", "codegraph"];
+const MANAGED_EXEMPLAR_TOOLS = ["read", "grep", "find", "codegraph", "web_enable", "web_search", "source_check", "fetch_content", "get_search_content"];
 const RETIRED_ADVERSARIAL_AGENTS = ["review-refuter.md", "review-validator.md"];
 
 interface ManagedAssetsManifest {
@@ -132,13 +133,13 @@ test("public docs and metadata advertise ODD and review without retired phase wo
 
 test("technical reference declares the tested Pi minimum required for agent_settled", () => {
 	const manifest = readPackageJson();
-	assert.equal(manifest.peerDependencies?.["@earendil-works/pi-coding-agent"], ">=0.99.1");
-	assert.equal(manifest.devDependencies?.["@earendil-works/pi-coding-agent"], ">=1.0.0");
+	assert.equal(manifest.peerDependencies?.["@earendil-works/pi-coding-agent"], ">=1.2.0");
+	assert.equal(manifest.devDependencies?.["@earendil-works/pi-coding-agent"], ">=1.2.0");
 	assert.equal(manifest.peerDependenciesMeta?.["@earendil-works/pi-coding-agent"]?.optional, true);
 	assert.equal(manifest.engines?.node, ">=22.19.0");
 	for (const path of ["docs/readme-reference.md", "docs/gentle-shell.md"]) {
 		const source = readFileSync(join(PACKAGE_ROOT, path), "utf8");
-		assert.match(source, /Pi 0\.99\.1 or newer/, path);
+		assert.match(source, /Pi 1\.2\.0 or newer/, path);
 		assert.match(source, /open `>=1\.0\.0` development range/, path);
 		assert.doesNotMatch(source, /development tests pin Pi/, path);
 		// Docs name exactly the audited Vim editor releases, never a future one.
@@ -161,7 +162,7 @@ test("packed runtime uses optional Pi host peers with one open development range
 	// one exact release shared by every Pi host package.
 	const installed = new Set<string>();
 	for (const name of ["@earendil-works/pi-coding-agent", "@earendil-works/pi-ai", "@earendil-works/pi-tui"]) {
-		assert.equal(manifest.devDependencies?.[name], ">=1.0.0", name);
+		assert.equal(manifest.devDependencies?.[name], ">=1.2.0", name);
 		const metadata = JSON.parse(readFileSync(join(PACKAGE_ROOT, "node_modules", name, "package.json"), "utf8")) as { name: string; version: string };
 		assert.equal(metadata.name, name);
 		installed.add(metadata.version);
@@ -253,6 +254,25 @@ test("package verification names the native review runtime boundary and packaged
 	);
 });
 
+test("double-click installers are attached to the release only after the verified publication", () => {
+	const workflow = readFileSync(join(PACKAGE_ROOT, ".github", "workflows", "publish.yml"), "utf8");
+	const job = workflow.match(/^ {2}installers:\n([\s\S]*?)(?=^ {2}[A-Za-z0-9_-]+:\n|(?![\s\S]))/m)?.[1];
+	assert.ok(job, "publish.yml has an installers job");
+	assert.match(job, /^ {4}needs: publish$/m, "installers wait for the verified npm publication");
+	assert.match(job, /^ {4}if: github\.repository == 'Gentleman-Programming\/gentle-shell'$/m);
+	assert.match(job, /^ {6}contents: write$/m, "only this job may write the release");
+	assert.match(job, /ref: \$\{\{ github\.sha \}\}/, "the installers come from the verified release commit");
+	assert.match(job, /persist-credentials: false/);
+	assert.match(job, /node scripts\/build-installer-bundles\.mjs --out "\$\{RUNNER_TEMP\}\/installers"/);
+	assert.match(job, /RELEASE_TAG: \$\{\{ needs\.publish\.outputs\.tag \}\}/, "the tag the publish job verified, not the raw input");
+	assert.match(job, /package-manager-cache: false/);
+	assert.match(workflow, /^ {4}outputs:\n {6}tag: \$\{\{ steps\.release\.outputs\.tag \}\}$/m, "publish exports its verified tag");
+	assert.match(job, /gh release upload "\$\{RELEASE_TAG\}" "\$\{RUNNER_TEMP\}"\/installers\/\* --repo "\$\{GITHUB_REPOSITORY\}" --clobber/);
+	const publish = workflow.match(/^ {2}publish:\n([\s\S]*?)(?=^ {2}installers:\n)/m)?.[1];
+	assert.ok(publish);
+	assert.doesNotMatch(publish, /contents: write/, "the npm publication job keeps read-only contents");
+});
+
 test("npm publication is bound to the exact package tag and triggering commit", () => {
 	const workflow = readFileSync(join(PACKAGE_ROOT, ".github", "workflows", "publish.yml"), "utf8");
 	const packageJson = readPackageJson();
@@ -411,20 +431,20 @@ test("package manifest installs pi-pretty through a wrapper without bundling nat
 	);
 });
 
-test("package verification binds the published Gentle AI v4.0.0 runtime pin", () => {
+test("package verification binds the published Gentle AI v4.1.1 runtime pin", () => {
 	const installer = readFileSync(join(PACKAGE_ROOT, "scripts", "gentle-ai-installer.mjs"), "utf8");
 	const binary = readFileSync(join(PACKAGE_ROOT, "lib", "gentle-ai-binary.ts"), "utf8");
 	const verifier = readFileSync(join(PACKAGE_ROOT, "scripts", "verify-package-files.mjs"), "utf8");
 
-	assert.match(installer, /INSTALLER_VERSION = "4\.0\.0"/);
+	assert.match(installer, /INSTALLER_VERSION = "4\.1\.1"/);
 	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_PACKAGE.*GENTLE_AI_WINDOWS_SOURCE_MODULE/);
-	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:pZ\/XZ2Pk3U9lgXigOTY62zlxxFOHnc9CjQhLgaV\/Hfc="/);
+	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:\+WmZ2IvIOiJ8qtHa7wsjnYKNasem\+PByeOZ6HIjoAL8="/);
 	assert.match(installer, /GOTOOLCHAIN: "local"/);
 	assert.match(installer, /GOSUMDB: "sum\.golang\.org"/);
 	assert.match(binary, /GENTLE_AI_VERSION = INSTALLER_VERSION/);
 	assert.match(binary, /GO_SUMDB_SOURCE_BUILD/);
 	assert.match(binary, /GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM/);
-	assert.match(verifier, /v4\.0\.0/);
+	assert.match(verifier, /v4\.1\.1/);
 });
 
 
@@ -550,7 +570,7 @@ function readMarkdownSection(source: string, heading: string): string {
 
 function assertWorkerFallbackRouting(section: string, sectionName: string): void {
 	const boundedWriterPolicy = section.match(
-		/For bounded multi-file writes,[\s\S]*?(?=\n\n|\n\s*\d+\.|$)/,
+		/For a large task's bounded writes,[\s\S]*?(?=\n\n|\n\s*\d+\.|$)/,
 	)?.[0];
 	assert.ok(boundedWriterPolicy, `${sectionName} must define bounded writer routing`);
 
@@ -847,6 +867,42 @@ test("selective review migration adopts only untouched legacy copies and preserv
 	}
 });
 
+test("native pulse audio ships owned TypeScript sources without new dependencies or addons", () => {
+	const manifest = readPackageJson();
+	const verifier = readFileSync(join(PACKAGE_ROOT, "scripts", "verify-package-files.mjs"), "utf8");
+	const sources = [
+		"lib/notification-pulse-protocol.ts", "lib/notification-pulse-client.ts",
+		"lib/notification-pulse-stream.ts", "lib/notification-audio-native.ts",
+		"lib/notification-pulse-worker.ts",
+	];
+	for (const source of sources) {
+		assert.ok(existsSync(join(PACKAGE_ROOT, source)), `${source} must exist`);
+		assert.ok(verifier.includes(`"${source}"`), `${source} must be a required package resource`);
+	}
+	assert.ok(!manifest.files?.includes("native/"), "no native addon directory may ship");
+	for (const name of Object.keys(manifest.dependencies ?? {})) assert.doesNotMatch(name, /pulse|audio|sound|native/i, name);
+	for (const name of Object.keys(manifest.scripts ?? {})) assert.doesNotMatch(name, /pulse|native:build|audio:install/i, name);
+	for (const path of ["lib/notification-pulse-worker.ts", "lib/notification-audio-native.ts"]) {
+		const source = readFileSync(join(PACKAGE_ROOT, path), "utf8");
+		assert.doesNotMatch(source, /@earendil-works|\.node["']|addon/i, path);
+		assert.doesNotMatch(source, /postinstall|installer|download/i, path);
+	}
+});
+
+test("native windows audio ships an owned encoded-command adapter without scripts or dependencies", () => {
+	const manifest = readPackageJson();
+	const verifier = readFileSync(join(PACKAGE_ROOT, "scripts", "verify-package-files.mjs"), "utf8");
+	const path = "lib/notification-audio-windows.ts";
+	assert.ok(existsSync(join(PACKAGE_ROOT, path)), `${path} must exist`);
+	assert.ok(verifier.includes(`"${path}"`), `${path} must be a required package resource`);
+	for (const dependency of Object.keys(manifest.dependencies ?? {})) assert.doesNotMatch(dependency, /audio|sound|windows|powershell|native/i, dependency);
+	for (const script of Object.keys(manifest.scripts ?? {})) assert.doesNotMatch(script, /windows:build|powershell|audio:install/i, script);
+	const source = readFileSync(join(PACKAGE_ROOT, path), "utf8");
+	assert.match(source, /-EncodedCommand/, "the adapter must drive the trusted built-in PowerShell host with an encoded command");
+	assert.doesNotMatch(source, /\.ps1|ExecutionPolicy|\.node["']|addon/i, path);
+	assert.doesNotMatch(source, /postinstall|installer|download/i, path);
+});
+
 test("packed tarball excludes retired workflow paths while source retains legacy migration proof", () => {
 	const fixture = "tests/fixtures/legacy/sdd-research-v2.5.0.md";
 	assert.ok(existsSync(join(PACKAGE_ROOT, fixture)), "the historical source fixture must remain available to migration tests");
@@ -857,9 +913,22 @@ test("packed tarball excludes retired workflow paths while source retains legacy
 			encoding: "utf8",
 			maxBuffer: 8 * 1024 * 1024,
 		});
-		const [packed] = JSON.parse(output) as [{ files: { path: string }[] }];
+		const [packed] = parseNpmPackResult(output);
 		assert.ok(packed?.files?.length, "npm pack must return a nonempty tar manifest");
 		assert.ok(packed.files.some(file => file.path === "tests/package-manifest.test.ts"), "other tests remain packed");
+		for (const path of [
+			"extensions/gentle-notifications.ts",
+			"lib/notification-audio.ts", "lib/notification-customize.ts", "lib/notification-events.ts", "lib/notification-policy.ts",
+			"lib/notification-scheduler.ts", "lib/notification-service.ts", "lib/notification-ui.ts",
+			"assets/sounds/success.wav", "assets/sounds/error.wav", "assets/sounds/attention.wav",
+			"assets/sounds/LICENSE.md", "docs/sound-notifications.md", "docs/sound-notifications-proposal.md",
+			"lib/notification-pulse-protocol.ts", "lib/notification-pulse-client.ts", "lib/notification-pulse-stream.ts",
+			"lib/notification-audio-native.ts", "lib/notification-pulse-worker.ts",
+			"lib/notification-audio-windows.ts",
+			"scripts/npm-pack-result.mjs",
+		]) {
+			assert.ok(packed.files.some(file => file.path === path), `${path} must be packed`);
+		}
 		assert.deepEqual(packed.files.filter(file => /sdd|openspec/i.test(file.path)).map(file => file.path), []);
 	} finally {
 		rmSync(destination, { recursive: true, force: true });
@@ -1441,7 +1510,7 @@ test("gentle-ai-worker packages the exact scoped writer contract", () => {
 	const testDiscipline = readMarkdownSection(source, "Test discipline");
 	assert.match(testDiscipline, /Apply the ODD test-first policy by default for behavior changes with applicable runnable deterministic tests and a clear expected outcome/);
 	assert.match(testDiscipline, /Test presence alone does not establish applicability; no TUI toggle or per-task chat choice is needed/);
-	assert.match(testDiscipline, /RED[\s\S]*GREEN[\s\S]*TRIANGULATE[\s\S]*REFACTOR/);
+	assert.match(testDiscipline, /RED[\s\S]*GREEN[\s\S]*PRESERVE[\s\S]*REFACTOR/);
 	assert.match(testDiscipline, /no meaningful RED[\s\S]*proportionate ordinary functional or structural verification/);
 	assert.match(testDiscipline, /Never claim RED\/GREEN evidence that was not observed/);
 	assert.match(
@@ -1604,7 +1673,7 @@ test("global model routing uses PI_CODING_AGENT_DIR for package-installed agents
 test("normal and forced installation copy generic agents with complete role contracts", () => {
 	const previousAgentHome = process.env.GENTLE_PI_AGENT_HOME;
 	const expectedTools = {
-		"gentle-ai-explore": ["read", "grep", "find", "codegraph"],
+		"gentle-ai-explore": ["read", "grep", "find", "codegraph", "web_enable", "web_search", "source_check", "fetch_content", "get_search_content"],
 		"gentle-ai-verify": ["read", "grep", "find", "bash"],
 	} as const;
 
@@ -1636,7 +1705,7 @@ test("normal and forced installation copy generic agents with complete role cont
 					assert.match(source, /compressed (?:handoff|evidence handoff)/);
 					assert.match(source, /Do not use review lenses\. RDD review remains independent and parent-owned\./);
 					if (name === "gentle-ai-verify") {
-						assert.match(source, /exact test, build, or lint commands explicitly authorized by the parent/);
+						assert.match(source, /exact test, build, lint, or spec example commands explicitly authorized by the parent/);
 						assert.match(source, /only outputs the parent explicitly identified as expected/);
 						assert.match(source, /unexpected mutation as a blocker/);
 						assert.match(source, /do not clean it up or fix it/);
@@ -1652,16 +1721,30 @@ test("normal and forced installation copy generic agents with complete role cont
 	}
 });
 
-test("bounded implementation routing uses the same explicit fallback in both policy sections", () => {
+test("bounded implementation routing resolves the explicit canonical fallback reference", () => {
 	const routing = readFileSync(
 		join(PACKAGE_ROOT, "assets", "orchestrator-delegation.md"),
 		"utf8",
 	);
-	const simpleDelegation = readMarkdownSection(routing, "2. Simple Delegation");
+	const reference = "For bounded writes, follow the canonical Writer rule under Mandatory Delegation Triggers.";
+	const resolveSimpleDelegation = (source: string): string => {
+		const simpleDelegation = readMarkdownSection(source, "2. Simple Delegation");
+		assert.ok(simpleDelegation.split("\n").includes(reference), "Simple Delegation must name the exact canonical Writer rule");
+		const canonical = readMarkdownSection(source, "Mandatory Delegation Triggers");
+		assertWorkerFallbackRouting(canonical, "resolved Simple Delegation");
+		return canonical;
+	};
 	const mandatoryDelegation = readMarkdownSection(routing, "Mandatory Delegation Triggers");
 
-	assertWorkerFallbackRouting(simpleDelegation, "Simple Delegation");
+	assertWorkerFallbackRouting(resolveSimpleDelegation(routing), "Simple Delegation");
 	assertWorkerFallbackRouting(mandatoryDelegation, "Mandatory Delegation Triggers");
+	assert.throws(() => resolveSimpleDelegation(routing.replace(reference, "")), /must name the exact canonical Writer rule/);
+	assert.throws(() => resolveSimpleDelegation(routing.replace(reference, reference.replace("Mandatory Delegation Triggers", "Other Rule"))),
+		/must name the exact canonical Writer rule/);
+	assert.throws(() => resolveSimpleDelegation(routing.replace("#### Mandatory Delegation Triggers", "#### Missing Canonical Rule")),
+		/exactly one Mandatory Delegation Triggers section/);
+	assert.throws(() => resolveSimpleDelegation(routing.replace("user-configured `worker`", "unspecified worker")),
+		/must prefer the package-owned worker before a user-configured worker/);
 	assert.doesNotMatch(
 		routing,
 		/non-normative compatibility quotation|former wording is retained|no-runtime inline exception|superseded by the stop requirement/,
@@ -1680,8 +1763,9 @@ test("orchestrator routes generic roles without static RDD lens routing", () =>
 		assert.match(routing, /`gentle-ai-explore`/);
 		assert.match(routing, /`gentle-ai-worker`/);
 		assert.match(routing, /`gentle-ai-verify`/);
-		assert.match(routing, /read-only check within the evidence budget/);
-		assert.match(routing, /(?:verification that |verification commands →).*executes? or delegates?|executing\/delegating verification commands/);
+		assert.match(routing, /focused test and (?:the )?suite/);
+		// The Verification rule line itself must route high risk to the verifier.
+		assert.match(routing, /^\d\. \*\*Verification rule\*\*[^\n]*high[- ]risk[^\n]*`gentle-ai-verify`/m);
 		assert.match(routing, /missing(?: or |\/)unusable[\s\S]*native `Agent`[\s\S]*(?:the )?same read-only/);
 		assert.match(routing, /report (?:the )?fallback/);
 		assert.doesNotMatch(routing, /review lenses? (?:inside|only inside)|review lens routing/i);
@@ -1705,9 +1789,9 @@ test("pi-pretty wrapper uses cached ESM loading for compiled and pnpm symlink in
 	assert.match(wrapper, /quietToolsEnabled/);
 });
 
-test("Gentle Shell v4.0.0 package manifest declares the release version", () => {
+test("Gentle Shell v4.2.0 package manifest declares the release version", () => {
 	const packageJson = readPackageJson();
-	assert.equal(packageJson.version, "4.0.0", "the release manifest must be explicitly pinned to v4.0.0");
+	assert.equal(packageJson.version, "4.2.0", "the release manifest must be explicitly pinned to v4.2.0");
 	assert.equal(packageJson.scripts?.test, "node scripts/run-test-suite.mjs");
 	assert.ok(packageJson.files?.includes("assets/"));
 	assert.ok(packageJson.files?.includes("contracts/"));

package/tests/packed-runner-owned-path.test.ts

@@ -1,9 +1,10 @@
 import assert from "node:assert/strict";
 import { mkdtempSync, mkdirSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { join, resolve, sep } from "node:path";
 import test from "node:test";
 import { resolveInstalledJitiStaticEntry } from "../scripts/test-packed-runner.mjs";
+import * as packedRunner from "../scripts/test-packed-runner.mjs";
 
 function withAliasedConsumer(run: (consumer: string, sdkManifest: string, jitiRoot: string) => void): void {
 	const disposable = mkdtempSync(join(tmpdir(), "packed-owned-path-"));
@@ -24,6 +25,39 @@ function withAliasedConsumer(run: (consumer: string, sdkManifest: string, jitiRo
 	}
 }
 
+test("hooked consumer approves only the canonical local tarball file spec", () => {
+	const disposable = mkdtempSync(join(tmpdir(), "packed-approval-"));
+	try {
+		const consumer = join(disposable, "install");
+		const pack = join(disposable, "pack");
+		mkdirSync(consumer);
+		mkdirSync(pack);
+		const tarball = join(pack, "gentle-pi-4.0.0.tgz");
+		writeFileSync(tarball, "owned tarball fixture");
+		const manifest = packedRunner.createHookedPackedConsumerManifest(consumer, tarball);
+		assert.deepEqual(manifest, {
+			name: "gentle-pi-packed-runner-test", private: true,
+			allowScripts: {
+				"file:../pack/gentle-pi-4.0.0.tgz": true,
+				[`file:${realpathSync.native(tarball).split(sep).join("/")}`]: true,
+			},
+		});
+		assert.equal(manifest.allowScripts["gentle-pi"], undefined);
+		assert.equal(manifest.allowScripts["*"], undefined);
+		for (const spec of Object.keys(manifest.allowScripts)) {
+			const filePath = spec.slice(5);
+			assert.equal(realpathSync.native(resolve(consumer, filePath)), realpathSync.native(tarball));
+		}
+		symlinkSync(consumer, join(disposable, "consumer-alias"), "dir");
+		assert.deepEqual(packedRunner.createHookedPackedConsumerManifest(join(disposable, "consumer-alias"), tarball), manifest);
+		symlinkSync("gentle-pi-4.0.0.tgz", join(pack, "alias.tgz"));
+		assert.throws(() => packedRunner.createHookedPackedConsumerManifest(consumer, join(pack, "alias.tgz")), /symbolic link/);
+		assert.throws(() => packedRunner.createHookedPackedConsumerManifest(consumer, pack), /regular file/);
+	} finally {
+		rmSync(disposable, { recursive: true, force: true });
+	}
+});
+
 const checks = { sdkManifest: "sdk-manifest", sdkVersion: "sdk-version", jitiManifest: "jiti-manifest-owned", jitiStaticExport: "jiti-static-export", jitiEntry: "jiti-entry-owned", jitiVersion: "jiti-version" };
 
 test("accepts a canonical Jiti manifest beneath an aliased ancestor", () => {

package/tests/parallel-reason-contract.test.ts

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+
+// gentle-shell#1731 T29 (L66): in the targeted bench (B, pi --mode json,
+// background policy off) the parallelism reason fired for two independent
+// features, but the writers ran one after the other in task mode: no
+// parallelism, only subagent overhead (x5 took 10.9 min vs 4.5 inline). The
+// lazy writer module already voided serial launches, but it loads only after
+// the core rule fires, so the condition must live in the core Writer rule.
+const core = readFileSync(join(import.meta.dirname, "..", "assets/orchestrator.md"), "utf8");
+
+test("T29: the core parallelism reason requires launching the units together in background", () => {
+	const rule = core.split("\n").find((line) => line.includes("5. **Writer rule**"));
+	assert.ok(rule, "core Writer rule is missing");
+	assert.ok(
+		rule.includes("launched together in background, else inline"),
+		"parallelism must require background launches in the same turn",
+	);
+});

package/tests/parallel-writer-admission.test.ts

@@ -0,0 +1,210 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { AGENT_MODE, type AgentDefinition } from "../lib/agents-config.ts";
+import { TASK_STATUS, TaskStore } from "../lib/agents-protocol.ts";
+import { AgentRunner, type TaskRequest } from "../lib/agents-runner.ts";
+import { fakeChild, type FakeChild } from "./agents-fake-child.ts";
+
+// gentle-shell#1731 T4 (S2, AC6): the runner admits a writer only while no
+// queued or running writer in the same worktree root claims an overlapping
+// `## Allowed edit surfaces` entry. Admission and registration happen in the
+// same synchronous run() call, and every terminal path releases the claim.
+
+const worker: AgentDefinition = { name: "gentle-ai-worker", description: "writes", filePath: "/a/worker.md", scope: "global", instructions: "You write.", model: undefined, thinking: undefined, mode: undefined, tools: ["read", "edit", "write"] };
+const explorer: AgentDefinition = { ...worker, name: "explore", description: "maps", tools: ["read"] };
+
+function writer(surfaces: string[], overrides: Partial<TaskRequest> = {}): TaskRequest {
+	return { agent: worker, prompt: `Write.\n\n## Allowed edit surfaces\n${surfaces.join("\n")}\n`, label: undefined, context: undefined, mode: AGENT_MODE.BACKGROUND, cwd: "/repo", parentSessionId: "s1", model: undefined, thinking: undefined, sessionDir: "/sessions", resumeSessionPath: undefined, env: {}, writerSurfaces: surfaces, ...overrides };
+}
+
+function harness(maxConcurrency = 5) {
+	const children: FakeChild[] = [];
+	const timers: Array<{ fn: () => void; cancelled: boolean }> = [];
+	const store = new TaskStore();
+	const runner = new AgentRunner(store, { maxConcurrency, stallTimeoutMs: 10_000 }, {
+		spawn: () => {
+			const fake = fakeChild();
+			children.push(fake);
+			return fake.child;
+		},
+		now: () => Date.now(),
+		schedule: (fn) => {
+			const timer = { fn, cancelled: false };
+			timers.push(timer);
+			return () => { timer.cancelled = true; };
+		},
+		pi: { command: "pi", args: [] },
+	}, { askUser: async () => ({ cancelled: true }) });
+	const fireTimers = () => { for (const timer of timers.splice(0)) if (!timer.cancelled) timer.fn(); };
+	return { store, runner, children, fireTimers };
+}
+
+const tick = () => new Promise((resolve) => setImmediate(resolve));
+
+async function complete(h: ReturnType<typeof harness>, index: number, id: string): Promise<void> {
+	h.children[index].emit({ type: "agent_end", messages: [{ role: "assistant", content: [{ type: "text", text: "done" }] }] });
+	h.children[index].emit({ type: "agent_settled" });
+	await h.runner.waitFor(id);
+}
+
+test("writers with disjoint surfaces run concurrently in one worktree", async () => {
+	const h = harness();
+	const a = h.runner.run(writer(["lib/a.ts", "tests/a.test.ts"]));
+	const b = h.runner.run(writer(["lib/b.ts", "tests/b.test.ts"]));
+	await tick();
+	assert.equal(h.children.length, 2);
+	assert.equal(h.store.get(a.id)?.status, TASK_STATUS.RUNNING);
+	assert.equal(h.store.get(b.id)?.status, TASK_STATUS.RUNNING);
+	h.runner.cancelAll();
+});
+
+test("an overlapping writer is rejected before any task, queue entry or spawn exists", async () => {
+	const h = harness();
+	const a = h.runner.run(writer(["lib/a.ts", "tests/a.test.ts"]));
+	await tick();
+	assert.throws(() => h.runner.run(writer(["lib/*.ts"])), (error: Error) => {
+		assert.match(error.message, new RegExp(`task ${a.id}`));
+		assert.match(error.message, /`lib\/\*\.ts` overlaps `lib\/a\.ts`/);
+		assert.match(error.message, /isolated worktree/);
+		return true;
+	});
+	assert.equal(h.store.list("s1").length, 1, "the rejected writer leaves no task record");
+	await tick();
+	assert.equal(h.children.length, 1, "the rejected writer never spawns");
+	h.runner.cancelAll();
+});
+
+test("a queued writer already holds its surfaces", async () => {
+	const h = harness(1);
+	h.runner.run(writer(["lib/a.ts"]));
+	const queued = h.runner.run(writer(["lib/b.ts"]));
+	await tick();
+	assert.equal(h.store.get(queued.id)?.status, TASK_STATUS.QUEUED);
+	assert.throws(() => h.runner.run(writer(["lib/b.ts"])), new RegExp(`task ${queued.id}`));
+	h.runner.cancelAll();
+});
+
+test("completion releases the claim", async () => {
+	const h = harness();
+	const a = h.runner.run(writer(["lib/a.ts"]));
+	await tick();
+	await complete(h, 0, a.id);
+	assert.equal(h.store.get(a.id)?.status, TASK_STATUS.COMPLETED);
+	const next = h.runner.run(writer(["lib/a.ts"]));
+	assert.ok(next.id);
+	h.runner.cancelAll();
+});
+
+test("failure releases the claim", async () => {
+	const h = harness();
+	const a = h.runner.run(writer(["lib/a.ts"]));
+	await tick();
+	h.children[0].exit(1);
+	await h.runner.waitFor(a.id);
+	assert.equal(h.store.get(a.id)?.status, TASK_STATUS.FAILED);
+	assert.doesNotThrow(() => h.runner.run(writer(["lib/a.ts"])));
+	h.runner.cancelAll();
+});
+
+test("a spawn failure releases the claim", async () => {
+	const h = harness();
+	const a = h.runner.run(writer(["lib/a.ts"], { beforeSpawn: () => { throw new Error("session changed"); } }));
+	await h.runner.waitFor(a.id);
+	assert.equal(h.store.get(a.id)?.status, TASK_STATUS.FAILED);
+	assert.doesNotThrow(() => h.runner.run(writer(["lib/a.ts"])));
+	h.runner.cancelAll();
+});
+
+test("cancelling a running or queued writer releases its claim", async () => {
+	const h = harness(1);
+	const running = h.runner.run(writer(["lib/a.ts"]));
+	const queued = h.runner.run(writer(["lib/b.ts"]));
+	await tick();
+	assert.equal(h.runner.cancel(queued.id), true);
+	assert.equal(h.store.get(queued.id)?.status, TASK_STATUS.CANCELLED);
+	assert.doesNotThrow(() => h.runner.run(writer(["lib/b.ts"])));
+	assert.equal(h.runner.cancel(running.id), true);
+	await h.runner.waitFor(running.id);
+	assert.equal(h.store.get(running.id)?.status, TASK_STATUS.CANCELLED);
+	assert.doesNotThrow(() => h.runner.run(writer(["lib/a.ts"])));
+	h.runner.cancelAll();
+});
+
+test("a stall timeout releases the claim", async () => {
+	const h = harness();
+	const a = h.runner.run(writer(["lib/a.ts"]));
+	await tick();
+	h.fireTimers();
+	await h.runner.waitFor(a.id);
+	assert.equal(h.store.get(a.id)?.status, TASK_STATUS.TIMED_OUT);
+	assert.doesNotThrow(() => h.runner.run(writer(["lib/a.ts"])));
+	h.runner.cancelAll();
+});
+
+// Verify m1: a quarantined writer may still be alive, so its claim lives as
+// long as its reserved concurrency slot and is released only on proven exit.
+test("a quarantined writer keeps its claim until its exit is confirmed", async () => {
+	const store = new TaskStore();
+	const timers: Array<{ fn: () => void; ms: number; cancelled: boolean }> = [];
+	let now = 0;
+	let groupGone = false;
+	const child = fakeChild({ exitOnKill: false, pid: 71 });
+	const runner = new AgentRunner(store, { maxConcurrency: 5, stallTimeoutMs: 10_000 }, {
+		spawn: () => child.child,
+		now: () => now,
+		schedule: (fn, ms) => {
+			const timer = { fn, ms, cancelled: false };
+			timers.push(timer);
+			return () => { timer.cancelled = true; };
+		},
+		pi: { command: "pi", args: [] },
+		process: { platform: "linux", kill: (_pid, signal) => {
+			if (signal === 0) throw Object.assign(new Error("group probe"), { code: groupGone ? "ESRCH" : "EPERM" });
+		} },
+	}, { askUser: async () => ({ cancelled: true }) });
+	const first = runner.run(writer(["lib/a.ts"]));
+	await tick();
+	runner.cancel(first.id);
+	timers.find((timer) => timer.ms === 250)!.fn();
+	now = 2_000;
+	timers.filter((timer) => timer.ms === 25).at(-1)!.fn();
+	await tick();
+	assert.match(store.get(first.id)?.error ?? "", /capacity quarantined/);
+	assert.throws(() => runner.run(writer(["lib/a.ts"])), new RegExp(`task ${first.id}`), "the quarantined writer still holds its surfaces");
+	groupGone = true;
+	child.exit(0);
+	await tick();
+	assert.doesNotThrow(() => runner.run(writer(["lib/a.ts"])), "proven exit releases the claim");
+	runner.cancelAll();
+});
+
+// Second verify A1: the claim key is the canonical worktree root supplied by
+// the parent, not the spawn cwd, so a subdirectory cwd and the root conflict.
+test("writers keyed to the same canonical root conflict whatever their cwd", async () => {
+	const h = harness();
+	const first = h.runner.run(writer(["lib/a.ts"], { cwd: "/repo/sub", writerRoot: "/repo" }));
+	assert.throws(() => h.runner.run(writer(["lib/a.ts"], { cwd: "/repo", writerRoot: "/repo" })), new RegExp(`task ${first.id}`));
+	assert.doesNotThrow(() => h.runner.run(writer(["lib/a.ts"], { cwd: "/repo-worktrees/feature", writerRoot: "/repo-worktrees/feature" })));
+	h.runner.cancelAll();
+});
+
+test("writers in different worktree roots never conflict", async () => {
+	const h = harness();
+	h.runner.run(writer(["lib/a.ts"], { cwd: "/repo" }));
+	assert.doesNotThrow(() => h.runner.run(writer(["lib/a.ts"], { cwd: "/repo-worktrees/feature" })));
+	await tick();
+	assert.equal(h.children.length, 2);
+	h.runner.cancelAll();
+});
+
+test("read-only agents are never registered and never blocked", async () => {
+	const h = harness();
+	h.runner.run(writer(["lib/**"]));
+	const reader = h.runner.run(writer([], { agent: explorer, prompt: "Map lib/", writerSurfaces: undefined }));
+	const second = h.runner.run(writer([], { agent: explorer, prompt: "Map lib/ again", writerSurfaces: undefined }));
+	await tick();
+	assert.equal(h.store.get(reader.id)?.status, TASK_STATUS.RUNNING);
+	assert.equal(h.store.get(second.id)?.status, TASK_STATUS.RUNNING);
+	assert.doesNotThrow(() => h.runner.run(writer(["tests/a.ts"])), "a reader holds no surfaces");
+	h.runner.cancelAll();
+});