gentle-pi 4.0.0 → 4.2.0

package/tests/status-timing-diagnostics.test.ts

@@ -0,0 +1,283 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+import type { ExtensionAPI, ExtensionContext, ExtensionToolContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { createGentleAiExtension } from "../extensions/gentle-ai.ts";
+import { createReviewSidebarPublisher } from "../lib/review-sidebar-state.ts";
+import {
+	StatusTimingDiagnostics, observeNativeStatus, measureStatusSync, measureStatusAsync, measureStatusSidebar,
+} from "../lib/status-timing-diagnostics.ts";
+import { NativeReviewCliV216, createNodeExecFileAdapter, type ExecFileAdapter, type ExecFileRequest } from "../lib/native-review-cli.ts";
+
+function context() {
+	let id = "private-session";
+	const notices: string[] = [];
+	const ctx = {
+		cwd: process.cwd(),
+		sessionManager: { getSessionId: () => id },
+		ui: { notify: (message: string) => notices.push(message) },
+	} as unknown as ExtensionToolContext;
+	return { ctx, notices, replace: () => { id = "replacement-session"; } };
+}
+
+function wrapped<T>(timing: StatusTimingDiagnostics, run: () => Promise<T>) {
+	const definition = { name: "gentle_review", execute: run } as unknown as ToolDefinition;
+	return (ctx: ExtensionToolContext) => timing.tool(definition).execute("private-call", { operation: "inspect" }, undefined, undefined, ctx);
+}
+
+function summary(timing: StatusTimingDiagnostics, host: ReturnType<typeof context>) {
+	timing.command("show", host.ctx);
+	return JSON.parse(host.notices.at(-1)!) as {
+		host_total_ms: number; dispatch_ms: number; sidebar_ms: number; completion_ms: number;
+		truncated: boolean; statuses: Array<{ timeout_ms: number; total_ms: number; resolution_ms: number; adapter_ms: number; decode_ms: number; outcome: Record<string, unknown> }>;
+	};
+}
+
+const statusBytes = readFileSync(join(process.cwd(), "tests/fixtures/devbinary/status-v5.captured.json"), "utf8");
+
+test("disabled diagnostics do not consult the clock or alter protocol, invocations, or deadlines", async () => {
+	const host = context();
+	let clockCalls = 0;
+	const timing = new StatusTimingDiagnostics(() => { clockCalls++; throw new Error("observer failed"); });
+	const requests: ExecFileRequest[] = [];
+	const adapter: ExecFileAdapter = async (request) => {
+		requests.push(request);
+		return { stdout: statusBytes, stderr: "", exitCode: 0, signal: null, timedOut: false, outputLimitExceeded: false };
+	};
+	const cli = new NativeReviewCliV216(adapter, process.execPath, 30_000);
+	const baseline = await cli.targetStatus({ cwd: process.cwd(), agent: "pi" });
+	const actual = await wrapped(timing, () => cli.targetStatus({ cwd: process.cwd(), agent: "pi" }))(host.ctx);
+	assert.deepEqual(actual, baseline);
+	assert.equal(clockCalls, 0);
+	assert.deepEqual(requests[1], requests[0]);
+	timing.command("show", host.ctx);
+	assert.match(host.notices.at(-1)!, /No completed STATUS timing/);
+});
+
+test("opt-in captures monotonic stage durations once and excludes all identifying or raw data", async () => {
+	const host = context();
+	let now = 0;
+	const timing = new StatusTimingDiagnostics(() => now);
+	timing.reset(host.ctx);
+	timing.command("enable", host.ctx);
+	const value = { details: { secret: "raw-output" } };
+	const actual = await wrapped(timing, async () => {
+		now += 7;
+		await observeNativeStatus(30_000, async () => {
+			measureStatusSync("resolution", () => { now += 3; });
+			await measureStatusAsync("adapter", async () => { now += 19; });
+			measureStatusSync("decode", () => { now += 5; });
+		});
+		measureStatusSidebar(() => { now += 2; });
+		now += 11;
+		return value;
+	})(host.ctx);
+	assert.equal(actual, value);
+	assert.deepEqual(summary(timing, host), {
+		schema: "gentle-pi.status-timing/v1", host_total_ms: 47, dispatch_ms: 7,
+		sidebar_ms: 2, completion_ms: 13, truncated: false,
+		statuses: [{ timeout_ms: 30_000, total_ms: 27, resolution_ms: 3, adapter_ms: 19, decode_ms: 5, outcome: { kind: "success" } }],
+	});
+	await wrapped(timing, () => observeNativeStatus(99, async () => { now += 99; }))(host.ctx);
+	assert.equal(summary(timing, host).statuses[0].timeout_ms, 30_000, "arming is consumed without retrying anything");
+	const report = host.notices.at(-1)!;
+	for (const forbidden of [host.ctx.cwd, "private-session", "private-call", "raw-output"]) assert.equal(report.includes(forbidden), false);
+});
+
+test("enabled fake adapter preserves success and typed failure bytes without extra execution", async () => {
+	for (const fail of [false, true]) {
+		const host = context();
+		const timing = new StatusTimingDiagnostics();
+		const failure = { schema: "gentle-ai.review-integration.failure/v2", contract: "gentle-ai.review-integration/v2", required_inputs: [], operation: "review.status", code: "operation_timeout", phase: "pre_native", message: "private raw error", cause: "/private/path", mutation_outcome: "not_started", authority_applicability: "not_evaluated", retry_safe: false, replayability: "manual_action_required", next_action: "stop" };
+		const requests: ExecFileRequest[] = [];
+		const adapter: ExecFileAdapter = async (request) => {
+			requests.push(request);
+			return { stdout: fail ? JSON.stringify(failure) : statusBytes, stderr: "", exitCode: fail ? 1 : 0, signal: null, timedOut: false, outputLimitExceeded: false };
+		};
+		const cli = new NativeReviewCliV216(adapter, process.execPath, 321);
+		const invoke = () => cli.targetStatus({ cwd: process.cwd(), agent: "pi" });
+		let expected: unknown;
+		try { expected = await invoke(); } catch (error) { expected = error; }
+		timing.command("enable", host.ctx);
+		let actual: unknown;
+		try { actual = await wrapped(timing, invoke)(host.ctx); } catch (error) { actual = error; }
+		assert.deepEqual(actual, expected);
+		assert.deepEqual(requests[1], requests[0]);
+		assert.equal(requests.length, 2);
+		const report = summary(timing, host);
+		assert.equal(report.statuses[0].timeout_ms, 321);
+		assert.equal(report.statuses[0].outcome.kind, fail ? "native_failure" : "success");
+		if (fail) {
+			assert.deepEqual(report.statuses[0].outcome, { kind: "native_failure", code: "operation_timeout", phase: "pre_native", mutation_outcome: "not_started", retry_safe: false, next_action: "stop" });
+			assert.equal(host.notices.at(-1)!.includes("private"), false);
+		}
+	}
+});
+
+test("public plain STATUS facade consumes the arm and measures resolution without changing execution", async () => {
+	const host = context();
+	let now = 0;
+	const timing = new StatusTimingDiagnostics(() => now);
+	const requests: ExecFileRequest[] = [];
+	const body = {
+		schema: "gentle-ai.review-authority-status/v1", operation: "review/status", repository: process.cwd(),
+		complete: true, authoritative: true, status: "clean", entries: [], locks: [], diagnostics: [],
+	};
+	const cli = new NativeReviewCliV216(async (request) => {
+		requests.push(request);
+		now += 17;
+		return { stdout: JSON.stringify(body), stderr: "", exitCode: 0, signal: null, timedOut: false, outputLimitExceeded: false };
+	}, () => { now += 5; return process.execPath; }, 321, 654);
+	const signal = new AbortController().signal;
+	const baseline = await cli.reviewStatus({ cwd: process.cwd(), signal });
+	timing.command("enable", host.ctx);
+	const actual = await wrapped(timing, () => cli.reviewStatus({ cwd: process.cwd(), signal }))(host.ctx);
+	assert.deepEqual(actual, baseline);
+	assert.deepEqual(requests[1], requests[0]);
+	assert.equal(requests.length, 2);
+	assert.deepEqual(requests[1].arguments, ["review", "status", "--cwd", process.cwd()]);
+	assert.equal(requests[1].signal, signal);
+	assert.equal(requests[1].timeoutMs, 321);
+	assert.equal(requests[1].maxBufferBytes, 654);
+	const report = summary(timing, host);
+	assert.equal(report.statuses.length, 1);
+	assert.equal(report.statuses[0].resolution_ms, 5);
+	assert.equal(report.statuses[0].adapter_ms, 17);
+	assert.equal(report.statuses[0].timeout_ms, 321);
+	assert.deepEqual(report.statuses[0].outcome, { kind: "success" });
+	await wrapped(timing, () => cli.reviewStatus({ cwd: process.cwd(), signal }))(host.ctx);
+	assert.deepEqual(summary(timing, host), report, "the facade consumes the arm only once");
+});
+
+test("observer clock failures cannot hide a result or original thrown error", async () => {
+	const host = context();
+	const timing = new StatusTimingDiagnostics(() => { throw new Error("clock failed"); });
+	timing.command("enable", host.ctx);
+	const sentinel = new Error("original error");
+	await assert.rejects(wrapped(timing, () => observeNativeStatus(30, () => measureStatusAsync("adapter", async () => { throw sentinel; })))(host.ctx), (error) => error === sentinel);
+	timing.command("enable", host.ctx);
+	const value = { ok: true };
+	assert.equal(await wrapped(timing, () => observeNativeStatus(30, async () => measureStatusSync("decode", () => value)))(host.ctx), value);
+});
+
+test("disable, shutdown, and replacement clear retained and late observations", async () => {
+	for (const action of ["disable", "shutdown", "replacement"] as const) {
+		const host = context();
+		const timing = new StatusTimingDiagnostics();
+		timing.command("enable", host.ctx);
+		let release!: () => void;
+		const gate = new Promise<void>((resolve) => { release = resolve; });
+		const run = wrapped(timing, () => observeNativeStatus(30, () => measureStatusAsync("adapter", () => gate)))(host.ctx);
+		if (action === "disable") timing.command("disable", host.ctx);
+		if (action === "shutdown") timing.reset();
+		if (action === "replacement") host.replace();
+		release();
+		await run;
+		timing.command("show", host.ctx);
+		assert.match(host.notices.at(-1)!, /No completed STATUS timing/);
+	}
+});
+
+test("overlapping calls claim only one armed capture and never mix stages", async () => {
+	const host = context();
+	let now = 0;
+	const timing = new StatusTimingDiagnostics(() => now);
+	timing.command("enable", host.ctx);
+	let release!: () => void;
+	const gate = new Promise<void>((resolve) => { release = resolve; });
+	const first = wrapped(timing, async () => {
+		await gate;
+		return observeNativeStatus(11, async () => measureStatusSync("decode", () => { now += 3; }));
+	})(host.ctx);
+	await wrapped(timing, () => observeNativeStatus(22, () => measureStatusAsync("adapter", async () => { now += 9; })))(host.ctx);
+	release();
+	await first;
+	assert.equal(summary(timing, host).statuses.length, 1);
+	assert.equal(summary(timing, host).statuses[0].timeout_ms, 22);
+	assert.equal(summary(timing, host).statuses[0].decode_ms, 0);
+});
+
+test("summaries are bounded and commands never invoke native or persist settings", async () => {
+	const host = context();
+	const timing = new StatusTimingDiagnostics();
+	timing.command("invalid", host.ctx);
+	assert.match(host.notices.at(-1)!, /Use enable, disable, or show/);
+	timing.command("enable", host.ctx);
+	await wrapped(timing, async () => {
+		for (let index = 0; index < 100; index++) await observeNativeStatus(30, async () => {});
+	})(host.ctx);
+	const report = summary(timing, host);
+	assert.equal(report.statuses.length, 8);
+	assert.equal(report.truncated, true);
+	timing.command("disable", host.ctx);
+	timing.command("show", host.ctx);
+	assert.match(host.notices.at(-1)!, /No completed STATUS timing/);
+});
+
+test("registered command observes controller dispatch and sidebar without changing its result", async () => {
+	const host = context();
+	const commands = new Map<string, { handler: (args: string, ctx: ExtensionContext) => Promise<void> }>();
+	const tools = new Map<string, ToolDefinition>();
+	const hooks = new Map<string, Array<(event: unknown, ctx: ExtensionContext) => unknown>>();
+	let calls = 0;
+	const cli = new NativeReviewCliV216(async () => {
+		calls++;
+		return { stdout: statusBytes, stderr: "", exitCode: 0, signal: null, timedOut: false, outputLimitExceeded: false };
+	}, process.execPath);
+	createGentleAiExtension({ nativeReviewCli: cli })({
+		on: (name: string, handler: (event: unknown, ctx: ExtensionContext) => unknown) => hooks.set(name, [...(hooks.get(name) ?? []), handler]),
+		registerTool: (definition: ToolDefinition) => tools.set(definition.name, definition),
+		registerCommand: (name: string, definition: { handler: (args: string, ctx: ExtensionContext) => Promise<void> }) => commands.set(name, definition),
+		events: { emit: () => { throw new Error("sidebar observer failed"); } },
+	} as unknown as ExtensionAPI);
+	const command = commands.get("gentle:status-timing")!;
+	assert.ok(command);
+	await command.handler("enable", host.ctx);
+	assert.equal(calls, 0, "arming never runs native STATUS");
+	const tool = tools.get("gentle_review")!;
+	const actual = await tool.execute("private-call", { operation: "inspect" }, undefined, undefined, host.ctx);
+	assert.equal(calls, 1);
+	assert.equal(typeof actual.details, "object");
+	await command.handler("show", host.ctx);
+	const report = JSON.parse(host.notices.at(-1)!);
+	assert.equal(report.statuses.length, 1);
+	assert.equal(report.statuses[0].outcome.kind, "success");
+	assert.equal(typeof report.sidebar_ms, "number");
+	assert.equal(calls, 1, "consulting never runs another STATUS");
+	for (const handler of hooks.get("session_tree") ?? []) await handler({}, host.ctx);
+	await command.handler("show", host.ctx);
+	assert.match(host.notices.at(-1)!, /No completed STATUS timing/);
+	assert.equal(calls, 1);
+});
+
+test("real sidebar publication is timed and throwing listeners cannot hide results", async () => {
+	const host = context();
+	let now = 0;
+	const timing = new StatusTimingDiagnostics(() => now);
+	const publisher = createReviewSidebarPublisher({ events: { emit: () => { now += 4; throw new Error("listener failed"); } } } as unknown as ExtensionAPI);
+	publisher.reset(host.ctx);
+	timing.command("enable", host.ctx);
+	const value = { content: [], details: {} };
+	const definition = { name: "gentle_review", execute: () => observeNativeStatus(30, async () => value) } as unknown as ToolDefinition;
+	const actual = await timing.tool(publisher.tool(definition)).execute("private-call", { operation: "inspect" }, undefined, undefined, host.ctx);
+	assert.equal(actual, value);
+	assert.equal(summary(timing, host).sidebar_ms, 8);
+});
+
+test("isolated Node child measures adapter settlement separately from host completion", async () => {
+	const host = context();
+	const timing = new StatusTimingDiagnostics();
+	timing.command("enable", host.ctx);
+	const adapter = createNodeExecFileAdapter();
+	const actual = await wrapped(timing, async () => {
+		const result = await observeNativeStatus(2000, () => measureStatusAsync("adapter", () => adapter({ file: process.execPath, arguments: ["-e", "setTimeout(() => process.stdout.write('isolated-child'), 30)"], cwd: process.cwd(), timeoutMs: 2000, maxBufferBytes: 1024 })));
+		await new Promise((resolve) => setTimeout(resolve, 50));
+		return result;
+	})(host.ctx);
+	assert.equal((actual as unknown as { stdout: string }).stdout, "isolated-child");
+	const report = summary(timing, host);
+	assert.ok(report.statuses[0].adapter_ms >= 20);
+	assert.ok(report.completion_ms >= 35);
+	assert.ok(report.host_total_ms >= report.statuses[0].adapter_ms + 35);
+});

package/tests/support/orchestrator-modules.ts

@@ -0,0 +1,19 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// gentle-shell#1494 split the lazy delegation detail into per-mechanism
+// modules. Contract tests that assert delegation-scoped clauses read the union
+// so a moved clause stays pinned instead of silently disappearing.
+export const DELEGATION_MODULES = [
+	"orchestrator-delegation.md",
+	"orchestrator-tracking.md",
+	"orchestrator-verification.md",
+	"orchestrator-writer.md",
+	"orchestrator-prompts.md",
+] as const;
+
+const DEFAULT_ASSETS_DIR = join(import.meta.dirname, "..", "..", "assets");
+
+export function readDelegationDetail(assetsDir: string = DEFAULT_ASSETS_DIR): string {
+	return DELEGATION_MODULES.map((file) => readFileSync(join(assetsDir, file), "utf8")).join("\n\n");
+}

package/tests/task-size-routing-contract.test.ts

@@ -0,0 +1,241 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+import { __testing } from "../extensions/gentle-ai.ts";
+import { readDelegationDetail } from "./support/orchestrator-modules.ts";
+
+// gentle-shell#1494: task size is decided by understanding, risk, and whether
+// the work can be resumed from the diff, never by counting files, commands,
+// fixes, or a requested todo list. Each mechanism (ask, explore, verify,
+// track, writer) turns on only by its own trigger.
+
+const REPO_ROOT = join(import.meta.dirname, "..");
+const read = (relative: string): string => readFileSync(join(REPO_ROOT, relative), "utf8");
+
+const core = read("assets/orchestrator.md");
+const delegation = readDelegationDetail();
+const skill = read("skills/gentle-ai/SKILL.md");
+const extension = read("extensions/gentle-ai.ts");
+
+function sectionOf(text: string, heading: string): string {
+	const start = text.indexOf(heading);
+	assert.ok(start !== -1, `missing section: ${heading}`);
+	const next = text.indexOf("\n## ", start + heading.length);
+	return next === -1 ? text.slice(start) : text.slice(start, next);
+}
+
+test("AC1: the always-on core defines task size once with the three criteria", () => {
+	const size = sectionOf(core, "## Task Size");
+	for (const clause of [
+		"**Understood**",
+		"no product or design decision is open",
+		"one bounded read batch (at most 3 calls, ~10k tokens",
+		"**Contained risk**",
+		"**Resumable from the diff**",
+		"the original request and `git diff` alone",
+		"A task is **large** only when the resume test fails",
+	]) {
+		assert.ok(size.includes(clause), `task size section is missing: ${clause}`);
+	}
+	for (const [path, text] of Object.entries({ delegation, skill })) {
+		assert.ok(!text.includes("**Resumable from the diff**"), `${path} restates the task-size criteria instead of referencing them`);
+		assert.ok(text.includes("Task Size"), `${path} must reference the always-on Task Size section`);
+	}
+});
+
+test("AC2: counts never classify, and the step-count classifier is gone", () => {
+	const size = sectionOf(core, "## Task Size");
+	assert.ok(
+		size.includes("The number of files, commands or tests, fixes, or a requested `todo` list never decides size"),
+		"task size must say counts never classify",
+	);
+	for (const [path, text] of Object.entries({ core, delegation, skill, extension, readme: read("docs/readme-reference.md") })) {
+		assert.ok(!text.includes("two or more meaningful implementation steps"), `${path} keeps the step-count classifier`);
+	}
+	const prompt = __testing.buildGentlePrompt("gentleman");
+	const classify = prompt.slice(prompt.indexOf("4. **Classify.**"), prompt.indexOf("5. **Track before the first write.**"));
+	assert.ok(classify.includes("Task Size"), "ODD step 4 must classify by the Task Size section");
+});
+
+test("AC3: small work runs its checks inline and keeps test-first", () => {
+	const size = sectionOf(core, "## Task Size");
+	for (const clause of [
+		"run the focused test and the suite inline, once each",
+		"observe RED inline before the fix",
+		"No explore, worker, or verifier",
+		"no feature document, mirror, or commits unless the user asks",
+		"needs no lazy asset",
+	]) {
+		assert.ok(size.includes(clause), `small path is missing: ${clause}`);
+	}
+	for (const [path, text] of Object.entries({ core, delegation, skill })) {
+		assert.ok(!text.includes("only a read-only check within the evidence budget stays inline"), `${path} keeps the read-only-only inline check`);
+		assert.ok(!text.includes("Only a truly local read-only check within the evidence budget stays inline"), `${path} keeps the read-only-only inline check`);
+		assert.ok(!text.includes("running focused tests/builds"), `${path} still delegates focused test runs`);
+		assert.ok(!text.includes("command-running verification → `gentle-ai-verify`"), `${path} still routes every command-running check to a verifier`);
+	}
+});
+
+test("AC4: each mechanism turns on only by its own trigger and size is re-evaluated after", () => {
+	const triggers = sectionOf(core, "## Mechanisms");
+	for (const clause of [
+		"each mechanism turns on only by its own trigger",
+		"re-evaluate task size",
+		"1. **Ask**",
+		"2. **Evidence-budget rule**",
+		"3. **Verification rule**",
+		"4. **Track**",
+		"5. **Writer rule**",
+		"6. **Incident rule**",
+		"7. **Context backstop**",
+		"open product or design decision",
+		"high risk",
+		"never by file count",
+		// gentle-shell#1731: the writer fires on reasons, not on size alone.
+		"never by file count or a large task alone",
+	]) {
+		assert.ok(triggers.includes(clause), `mechanism list is missing: ${clause}`);
+	}
+	for (const [path, text] of Object.entries({ core, delegation, skill })) {
+		assert.ok(!/2\+ non-trivial files|2 or more non-trivial files|Multi-file write rule/.test(text), `${path} keeps the file-count writer trigger`);
+	}
+});
+
+test("AC5: the high-risk list lives once in the core, native tier wins, unclear is bounded", () => {
+	const size = sectionOf(core, "## Task Size");
+	for (const clause of [
+		"**High risk**",
+		"hard to detect, hard to undo, or reaches beyond the change",
+		"(1) data or irreversible effects",
+		// gentle-shell#1731 T10: items 1 and 3 cover changing or breaking existing things, not adding.
+		"rewriting or deleting stored data, format changes, writing data without validation; not saving new records",
+		"(2) security",
+		"(3) changing or removing contracts others already consume",
+		"; not adding a flag, command or optional field",
+		"(4) concurrency",
+		"(5) delivery or environment",
+		"(6) no test would catch a regression",
+		"only when a bounded look cannot tell whether (1)-(5) apply",
+		"When RDD is on and native assess returns a tier, that tier wins",
+	]) {
+		assert.ok(size.includes(clause), `high-risk definition is missing: ${clause}`);
+	}
+	for (const broad of ["(1) data or irreversible effects (migrations, persisted data or formats)", "(3) contracts others consume"]) {
+		assert.ok(!size.includes(broad), `high-risk list keeps the broad form: ${broad}`);
+	}
+	for (const [path, text] of Object.entries({ delegation, skill })) {
+		assert.ok(!text.includes("(1) data or irreversible effects"), `${path} restates the high-risk list`);
+	}
+});
+
+// AC7 (S7): the small path reads no lazy rule file, and each lazy module stays
+// small enough that one mechanism costs one bounded read instead of 49 KB.
+const MODULE_BUDGETS: Record<string, number> = {
+	// gentle-shell#1731 merge with main: main's session subject/state guidance plus the reason-based Writer rule (20,000 -> 20,500 B).
+	// gentle-shell#1269: capability-compatible routing rule checked before delegation (20,500 -> 20,800 B).
+	"orchestrator-delegation.md": 20_800,
+	// gentle-shell#1731 T23: Close gate accepts one Needs your decision result as a stop (12,500 -> 12,600 B).
+	"orchestrator-tracking.md": 12_600,
+	// gentle-shell#1731 T3: parallel review protocol; lazy (delegation or high risk only), core and normative rule untouched.
+	// gentle-shell#1731 T11/T12: verify-per-unit timing and the every-S# verify handoff (6,000 -> 6,400 B).
+	// gentle-shell#1731 T15: one end-of-feature verify for same-model inline deliveries (6,400 -> 6,500 B).
+	// gentle-shell#1731 T23: bounded self-review and partial/blocked writer -> Needs your decision (7,000 -> 7,300 B).
+	"orchestrator-verification.md": 7_300,
+	"orchestrator-writer.md": 4_500,
+	"orchestrator-prompts.md": 13_000,
+};
+
+test("AC7: each delegation module stays under its byte budget and is loaded by its mechanism only", () => {
+	for (const [file, budget] of Object.entries(MODULE_BUDGETS)) {
+		const bytes = Buffer.byteLength(read(`assets/${file}`), "utf8");
+		assert.ok(bytes <= budget, `${file} is ${bytes} B, over its ${budget} B budget`);
+		assert.ok(core.includes(`\`${file}\``), `the always-on core must point at ${file}`);
+		assert.ok(read("scripts/verify-package-files.mjs").includes(`assets/${file}`), `${file} must be a required package file`);
+	}
+	const smallPath = sectionOf(core, "## Task Size").split("\n").find((line) => line.startsWith("Small path:")) ?? "";
+	assert.ok(smallPath.includes("It needs no lazy asset"), "the small path must say it needs no lazy asset");
+	assert.doesNotMatch(smallPath, /`orchestrator-[a-z]+\.md`/, "the small path must not point at any lazy module");
+	const mechanisms = sectionOf(core, "## Mechanisms");
+	for (const [label, file] of [
+		["3. **Verification rule**", "orchestrator-verification.md"],
+		["4. **Track**", "orchestrator-tracking.md"],
+		["5. **Writer rule**", "orchestrator-writer.md"],
+	] as const) {
+		const line = mechanisms.split("\n").find((entry) => entry.startsWith(label)) ?? "";
+		assert.ok(line.includes(`\`${file}\``), `${label} must load ${file}`);
+	}
+});
+
+// gentle-shell#1269/#1598: the capability rule is the substantive part of the fix,
+// so losing it must fail a test instead of quietly passing the AC7 budget gate.
+// Focused on the two claims that carry the fix, not on the exact wording around them.
+test("delegation reports a capability gap instead of substituting inline work for a fired trigger", () => {
+	assert.match(delegation, /declared `tools` in `subagent_list_agents` before launching/);
+	assert.match(delegation, /never give a read-only explorer shell, HTTP or MCP work/);
+	assert.match(delegation, /report the capability gap; a fired trigger is never replaced by inline work/);
+	assert.equal(delegation.split("report the capability gap").length - 1, 1);
+});
+
+test("work usage stays complete in the human guide while routing precedence stays canonical", () => {
+	const asset = read("assets/orchestrator-delegation.md");
+	const guide = read("docs/gentle-agents-activity.md");
+	assert.ok(asset.includes("tool schemas and `docs/gentle-agents-activity.md`"));
+	for (const clause of [
+		'`{"area":"Auth","topic":"Login","tags":["Review"],"refs":[{"kind":"issue","repository":"github.com/Owner/Repo","id":"12"}]}`',
+		'`filter: {"related_to":{"session_id":"<stable owner ID>"}}`',
+		"Never publish private history as metadata.",
+		"not inherited. Keep the returned actual task ID: it is **not** a child session ID.",
+		"never automatically page. Source unavailable means no related rows, not refusal.",
+		"confer no ownership, consent or permission. Querying needs no helper/model call.",
+	]) assert.ok(guide.includes(clause), `human guide must retain: ${clause}`);
+	assert.equal(asset.split("For a large task's bounded writes, prefer").length - 1, 1);
+	assert.equal(asset.split("Route generic exploration first to the installed package-owned `gentle-ai-explore`").length - 1, 1);
+	assert.ok(asset.includes("Judgment Day phase roles are never generic fallbacks."));
+	assert.ok(asset.includes("same read-only mapping task and report the fallback."));
+});
+
+// S7 axis 2 (more input than output): tracking writes are mechanical; the
+// model edits instead of rewriting and never re-emits the whole document just
+// to mirror it.
+test("T4: tracking updates edit in place and mirror without re-emitting the document", () => {
+	const memory = read("assets/orchestrator-memory.md");
+	for (const clause of [
+		"Update the feature document with targeted edits; never rewrite the whole file to change a task line or append a log entry.",
+		"When a code-execution tool such as `codemode` is available, refresh the Engram mirror inside one script that reads the file and saves its content, so the document is never re-emitted as output tokens.",
+		"projection for large ODD,",
+	]) {
+		assert.ok(memory.includes(clause), `orchestrator-memory.md is missing: ${clause}`);
+	}
+	assert.ok(!memory.includes("For substantial authorized organic implementation"), "memory detail must size by Task Size, not 'substantial'");
+});
+
+// RDD follow-ups (lineages review-6d2889a73f541791, review-* slice 2): every
+// module must be self-contained for the mechanism that loads it, and each
+// moved clause must live in the module its pointer names.
+test("T6: each delegation module carries its own clauses and names the modules it depends on", () => {
+	const placement: Record<string, readonly string[]> = {
+		"orchestrator-tracking.md": ["#### Authorization and progress", "Delivery follows work units", "Raise a candidate you know is high risk"],
+		"orchestrator-verification.md": [
+			"| Native risk tier | Verification (any RDD state) |",
+			"## Agent escalation (gentle-shell#1494)",
+			"## Parallel review protocol (gentle-shell#1731)",
+		],
+		"orchestrator-writer.md": ["#### Allowed edit surfaces (MANDATORY)", "#### Judgment Day fix dispatch"],
+		"orchestrator-prompts.md": ["### Lossless Blocking Prompts (MANDATORY)", "#### Gentle AI Provider Defect Handoff (MANDATORY)"],
+	};
+	for (const [file, clauses] of Object.entries(placement)) {
+		const text = read(`assets/${file}`);
+		for (const clause of clauses) assert.ok(text.includes(clause), `${file} must carry: ${clause}`);
+	}
+	const writer = read("assets/orchestrator-writer.md");
+	assert.ok(!/Lossless Blocking Prompts rules above/.test(writer), "the writer module must not point at rules 'above' that live in another module");
+	assert.ok(writer.includes("`orchestrator-prompts.md`"), "the writer module must name the module that holds the blocking-prompt rules");
+	assert.ok(!delegation.includes("precedence in rule 2"), "cross-references name rules, not ambiguous numbers");
+});
+
+test("T6: the readme no longer sends every suite to a verifier or tracks 'substantial' work", () => {
+	const readme = read("docs/readme-reference.md");
+	assert.ok(!readme.includes("send full suites and builds to a verifier"), "readme still delegates every suite");
+	assert.ok(!/track substantial work|for substantial work|substantial authorized implementation/i.test(readme), "readme still sizes by 'substantial'");
+});

package/tests/telemetry-trigger.test.ts

@@ -1,11 +1,12 @@
 import assert from "node:assert/strict";
 import test, { after, before } from "node:test";
-import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { __testing, createGentleAiExtension } from "../extensions/gentle-ai.ts";
 import type { ExecFileAdapter, ExecFileResult } from "../lib/native-review-cli.ts";
+import { setBundledInstallForTesting } from "../lib/gentle-shell-bundled.ts";
 import {
 	decodeTelemetryTriggerDecision,
 	shouldTriggerTelemetry,
@@ -410,3 +411,28 @@ test("/gentle:telemetry rejects an unknown sub-action without calling the binary
 	assert.equal(notifications.length, 1);
 	assert.equal(notifications[0].severity, "warning");
 });
+
+// S9: this package running from a bundled install (the testing overlay stands
+// in for its location; the detection itself is tested with real installs in
+// gentle-ai-binary-isolation.test.ts) and the launcher's GENTLE_SHELL_PREFIX.
+function bundledIsolation(t: { after: (fn: () => void) => void }): { prefix: string; env: NodeJS.ProcessEnv } {
+	const prefix = realpathSync(mkdtempSync(join(tmpdir(), "gentle-ai-isolation-site-")));
+	setBundledInstallForTesting({ root: prefix });
+	t.after(() => {
+		setBundledInstallForTesting(undefined);
+		rmSync(prefix, { recursive: true, force: true });
+	});
+	return { prefix, env: { PATH: "/usr/bin", GENTLE_SHELL_PREFIX: prefix } };
+}
+
+test("spawnTelemetryTrigger: gentle-ai gets Gentle AI's isolation variables only in a bundled install", (t) => {
+	const { prefix, env } = bundledIsolation(t);
+	const bundled = fakeSpawn();
+	spawnTelemetryTrigger({ executable: "/opt/gentle-ai/gentle-ai", cwd: "/work", env, spawn: bundled.spawn });
+	assert.equal(bundled.calls[0].options.env?.GENTLE_AI_HOME, join(prefix, "gentle-ai"));
+	assert.equal(bundled.calls[0].options.env?.GENTLE_AI_NO_SELF_UPDATE, "1");
+	const ordinary = fakeSpawn();
+	const plain = { PATH: "/usr/bin" };
+	spawnTelemetryTrigger({ executable: "/opt/gentle-ai/gentle-ai", cwd: "/work", env: plain, spawn: ordinary.spawn });
+	assert.equal(ordinary.calls[0].options.env, plain);
+});