gentle-pi 2.4.0 → 2.6.0

package/tests/runtime-metrics-children.test.ts

@@ -0,0 +1,206 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { readFileSync, readdirSync } from "node:fs";
+import { stripTypeScriptTypes } from "node:module";
+import { runInNewContext } from "node:vm";
+import { parseAgentClass } from "../lib/runtime-metrics.ts";
+import { parseAgentDefinition, type AgentDefinition } from "../lib/agents-config.ts";
+import { normalizeRpcEvent, TASK_EVENT } from "../lib/agents-protocol.ts";
+import { lookupPiCatalogName } from "../lib/runtime-metrics-pi-identity.ts";
+import { ChildComposition, childEvent, classifyBuiltinAgent, launchSelection } from "../lib/runtime-metrics-children.ts";
+import { encodeNativeRuntimeEvent } from "../lib/runtime-metrics-native.ts";
+
+await lookupPiCatalogName({ provider: "openai", modelId: "gpt-4o" });
+const asset = new URL("../assets/agents/gentle-ai-worker.md", import.meta.url);
+const definition = parseAgentDefinition(readFileSync(asset, "utf8"), asset.pathname, "global");
+assert.ok("instructions" in definition);
+const workerDefinition = definition as AgentDefinition;
+const response = (model = "gpt-4o", native = "low") => {
+	const events = normalizeRpcEvent({ type: "message_end", message: { role: "assistant", provider: "openai",
+		model, responseModel: model, providerThinkingLevel: native, stopReason: "stop", usage: { input: 3, output: 2, reasoning: 1 } } }, { observeResponses: true });
+	const event = events.find(event => event.type === TASK_EVENT.RESPONSE_OBSERVATION);
+	assert.ok(event?.type === TASK_EVENT.RESPONSE_OBSERVATION);
+	return event.observation;
+};
+const launch = () => launchSelection(workerDefinition, { provider: "openai", id: "gpt-4o" }, "high");
+const event = (taskId = "local-task") => childEvent("local-session", taskId, launch(), "completed", {
+	coverage: "final_assistant_messages_only", agentSettled: true, responses: [response(), response("gpt-4o-mini", "high")], droppedResponses: 2,
+});
+
+test("installed package definitions retain classification after the actual routing transform", () => {
+	// installSddAssets/copyDirectoryFiles copies assets verbatim on first install.
+	// Isolate the real pure routing writer; do not run an installer or read user agents.
+	const source = readFileSync(new URL("../extensions/gentle-ai.ts", import.meta.url), "utf8");
+	const transform = source.match(/function updateFrontmatterRouting\([\s\S]*?\n\}/)?.[0];
+	assert.ok(transform);
+	const route = runInNewContext(`(${stripTypeScriptTypes(transform)})`);
+	for (const entry of readdirSync(new URL("../assets/agents/", import.meta.url)).filter(file => file.endsWith(".md"))) {
+		const file = entry.slice(0, -3);
+		const className = file === "sdd-proposal" ? "sdd-propose"
+			: file.startsWith("gentle-ai-") ? file.slice("gentle-ai-".length) : file;
+		const kind = parseAgentClass(className);
+		if (file === "sdd-remediate") {
+			assert.equal(kind, undefined, "remediation stays dark in the existing telemetry taxonomy");
+			const definition = parseAgentDefinition(readFileSync(new URL(`../assets/agents/${file}.md`, import.meta.url), "utf8"), file, "global");
+			assert.ok("instructions" in definition);
+			assert.equal(classifyBuiltinAgent(definition), "unknown");
+			continue;
+		}
+		assert.ok(kind, `${file}: telemetry class`);
+		const asset = new URL(`../assets/agents/${file}.md`, import.meta.url);
+		const content = readFileSync(asset, "utf8");
+		const copied = parseAgentDefinition(content, asset.pathname, "global");
+		assert.ok("instructions" in copied);
+		assert.equal(classifyBuiltinAgent(copied), kind, "verbatim first install");
+		for (const entry of [undefined, { model: "openai/gpt-4o", thinking: "high" }]) {
+			const parsed = parseAgentDefinition(route(content, entry), asset.pathname, "global");
+			assert.ok("instructions" in parsed);
+			assert.equal(classifyBuiltinAgent(parsed), kind, `${kind}: installed routing`);
+			const customizedClass = parsed.name === "sdd-proposal" ? "sdd-propose" : parseAgentClass(parsed.name) ?? "unknown";
+			assert.equal(classifyBuiltinAgent({ ...parsed, instructions: `${parsed.instructions}\nOverride` }), customizedClass);
+			assert.equal(classifyBuiltinAgent({ ...parsed, tools: ["different-tool"] }), customizedClass);
+			assert.equal(classifyBuiltinAgent({ ...parsed, description: "different description" }), customizedClass);
+			assert.equal(classifyBuiltinAgent({ ...parsed, mode: parsed.mode === "task" ? "background" : "task" }), customizedClass);
+		}
+	}
+});
+
+test("packaged sdd-proposal is encoded only as canonical sdd-propose", () => {
+	const path = new URL("../assets/agents/sdd-proposal.md", import.meta.url);
+	const packaged = parseAgentDefinition(readFileSync(path, "utf8"), path.pathname, "global");
+	assert.ok("instructions" in packaged);
+	const selection = launchSelection(packaged, { provider: "openai", id: "gpt-4o" }, "high");
+	assert.equal(selection.agentClass, "sdd-propose");
+	const completed = childEvent("local-session", "sdd-propose-task", selection, "completed", {
+		coverage: "final_assistant_messages_only", agentSettled: true, responses: [response()], droppedResponses: 0,
+	});
+	assert.ok(completed);
+	const composition = new ChildComposition();
+	assert.equal(composition.reserve(completed, "local-session"), true);
+	composition.record(completed);
+	const snapshot = composition.snapshot();
+	const payload = encodeNativeRuntimeEvent(snapshot.responses, snapshot.launches);
+	assert.ok(payload);
+	assert.equal(JSON.parse(payload).rows[0].agent_class, "sdd-propose");
+	assert.ok(!payload.includes("sdd-proposal"));
+});
+
+test("schema-approved packaged names survive customization without exposing private names", () => {
+	const path = new URL("../assets/agents/sdd-apply.md", import.meta.url);
+	const packaged = parseAgentDefinition(readFileSync(path, "utf8"), path.pathname, "global");
+	assert.ok("instructions" in packaged);
+	assert.equal(classifyBuiltinAgent({ ...packaged, instructions: "customized instructions" }), "sdd-apply");
+
+	assert.equal(classifyBuiltinAgent(workerDefinition), "worker");
+	// This is a packaged frontmatter name, but it is absent from the telemetry
+	// enum. Its exact fingerprint retains the compatibility mapping only.
+	assert.equal(classifyBuiltinAgent({ ...workerDefinition, instructions: "private override" }), "unknown");
+	assert.equal(classifyBuiltinAgent({ ...workerDefinition, tools: ["private tool"] }), "unknown");
+	assert.equal(classifyBuiltinAgent({ ...workerDefinition, name: "private-agent" }), "unknown");
+});
+
+test("launch distribution and each observed combination remain independent and privacy-filtered", () => {
+	const composition = new ChildComposition();
+	const value = event();
+	assert.ok(value);
+	assert.equal(composition.reserve(value, "local-session"), true);
+	composition.record(value);
+	const view = composition.snapshot();
+	assert.equal(view.launches[0].launches, 1);
+	assert.equal(view.launches[0].selectedEffort, "high");
+	assert.equal(view.launches[0].agentClass, "worker");
+	assert.equal(view.responses.length, 2);
+	assert.deepEqual(view.responses.map(row => row.observedModelId), ["gpt-4o", "gpt-4o-mini"]);
+	assert.ok(view.responses.every(row => row.effort === "high" && row.selectedProvider === "openai"
+		&& row.selectedModelId === "gpt-4o"));
+	assert.equal(view.responses[0].providerThinkingLevel, "low");
+	assert.equal(view.responses[0].tokens.reasoning.sum, 1);
+	const encoded = encodeNativeRuntimeEvent(view.responses, view.launches);
+	assert.ok(encoded);
+	assert.ok(JSON.parse(encoded).rows.filter((row: { responses: number | null }) => row.responses !== null)
+		.every((row: { model_evidence: string; selected_effort: string }) => row.model_evidence === "response" && row.selected_effort === "high"));
+	assert.equal(view.droppedResponses, 2);
+	assert.equal(view.settled, 1);
+	assert.equal(view.statuses.completed, 1);
+	assert.ok(!JSON.stringify(view).includes("local-"));
+	const privateLaunch = launchSelection({ ...workerDefinition, instructions: "private" }, { provider: "private", id: "private-model" }, "private-effort");
+	const filtered = childEvent("local-session", "other", privateLaunch, "failed", {
+		coverage: "final_assistant_messages_only", agentSettled: false, responses: [response("private-model", "private-native")], droppedResponses: 0,
+	});
+	assert.ok(!JSON.stringify(filtered).includes("private"));
+});
+
+test("registered child launch identity survives catalog state and missing response evidence inherits selection", () => {
+	const path = new URL("../assets/agents/sdd-explore.md", import.meta.url);
+	const agent = parseAgentDefinition(readFileSync(path, "utf8"), path.pathname, "global");
+	assert.ok("instructions" in agent);
+	const selection = launchSelection(agent, { provider: "openai-codex", id: "gpt-5.6-terra" }, "high");
+	const [observation] = normalizeRpcEvent({ type: "message_end", message: { role: "assistant", stopReason: "stop",
+		usage: { input: 3, output: 2 } } }, { observeResponses: true })
+		.filter(event => event.type === TASK_EVENT.RESPONSE_OBSERVATION);
+	assert.ok(observation?.type === TASK_EVENT.RESPONSE_OBSERVATION);
+	const completed = childEvent("local-session", "sdd-explore-task", selection, "completed", {
+		coverage: "final_assistant_messages_only", agentSettled: true,
+		responses: Array(5).fill(observation.observation), droppedResponses: 0,
+	});
+	assert.ok(completed);
+	const composition = new ChildComposition();
+	assert.equal(composition.reserve(completed, "local-session"), true);
+	composition.record(completed);
+	const snapshot = composition.snapshot();
+	const payload = encodeNativeRuntimeEvent(snapshot.responses, snapshot.launches);
+	assert.ok(payload);
+	const rows = JSON.parse(payload).rows;
+	const launchRow = rows.find((row: { launches: number | null }) => row.launches === 1);
+	const responseRow = rows.find((row: { responses: number | null }) => row.responses === 5);
+	assert.deepEqual(launchRow.model, { provider: "openai-codex", id: "gpt-5.6-terra" });
+	assert.equal(launchRow.model_evidence, "selected");
+	assert.equal(launchRow.selected_effort, "high");
+	assert.deepEqual(responseRow.model, { provider: "openai-codex", id: "gpt-5.6-terra" });
+	assert.equal(responseRow.model_evidence, "selected");
+	assert.equal(responseRow.selected_effort, "high");
+	assert.equal(responseRow.responses, 5);
+});
+
+test("dedupe reserves before async policy, rejects old sessions, and survives aggregate clearing", () => {
+	const c = new ChildComposition();
+	const e = event()!;
+	assert.equal(c.reserve(e, "other-session"), false);
+	assert.equal(c.reserve(e, "local-session"), true);
+	assert.equal(c.reserve(structuredClone(e), "local-session"), false);
+	c.record(e);
+	c.clear();
+	assert.equal(c.reserve(e, "local-session"), false);
+	assert.deepEqual(c.snapshot().responses, []);
+	for (let i = 0; i < 255; i++) assert.equal(c.reserve(event(String(i))!, "local-session"), true);
+	assert.equal(c.reserve(event("overflow")!, "local-session"), false);
+	assert.equal(c.snapshot().saturated, true);
+});
+
+test("response capacity retains launch ranking and reports excluded responses without eviction", () => {
+	const c = new ChildComposition();
+	for (let i = 0; i < 9; i++) {
+		const e = childEvent("local-session", String(i), launch(), "completed", {
+			coverage: "final_assistant_messages_only", agentSettled: true, responses: Array(128).fill(response()), droppedResponses: 0,
+		})!;
+		assert.equal(c.reserve(e, "local-session"), true);
+		c.record(e);
+		c.record(e);
+	}
+	const view = c.snapshot();
+	assert.equal(view.responses[0].responses, 1024);
+	assert.equal(view.launches[0].launches, 9);
+	assert.equal(view.droppedResponses, 128);
+	assert.equal(view.saturated, true);
+	assert.equal(view.statuses.completed, 9);
+});
+
+test("malformed and oversized events are rejected without reserving IDs", () => {
+	const c = new ChildComposition();
+	const e = event()!;
+	for (const patch of [{ schema: "old" }, { responses: Array(129).fill(e.responses[0]) }, { taskId: "x".repeat(129) },
+		{ droppedResponses: -1 }, { status: "native_success" }, { launch: { ...e.launch, agentClass: "private" } }]) {
+		assert.equal(c.reserve({ ...e, ...patch }, "local-session"), false);
+	}
+	assert.equal(c.reserve(e, "local-session"), true);
+});

package/tests/runtime-metrics-delivery.test.ts

@@ -0,0 +1,85 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import * as delivery from "../lib/runtime-metrics-delivery.ts";
+
+const tick = () => new Promise<void>(resolve => setImmediate(resolve));
+
+test("callback returns before a blocked attempt; busy events are never queued", async () => {
+	const owner = new delivery.RuntimeMetricsAttempt();
+	let calls = 0;
+	let finish!: () => void;
+	assert.equal(owner.offer(() => { calls++; return new Promise<void>(resolve => { finish = resolve; }); }), true);
+	assert.equal(calls, 0, "provider callback returns before any transport work");
+	assert.equal(owner.offer(async () => { calls++; }), false);
+	await tick();
+	assert.equal(calls, 1);
+	assert.equal(new delivery.RuntimeMetricsAttempt().offer(async () => { calls++; }), false);
+	finish(); await tick(); await tick();
+	assert.equal(calls, 1, "busy events never replay");
+	owner.dispose();
+});
+
+test("failure is silent and the next fresh event may attempt without cooldown", async () => {
+	const owner = new delivery.RuntimeMetricsAttempt();
+	let calls = 0;
+	owner.offer(async () => { calls++; throw new Error("private failure"); });
+	await tick(); await tick();
+	assert.equal(calls, 1);
+	assert.equal(owner.offer(async () => { calls++; }), true);
+	await tick(); await tick();
+	assert.equal(calls, 2);
+	owner.dispose();
+});
+
+test("replacement cancels an unstarted attempt without stale execution", async () => {
+	const owner = new delivery.RuntimeMetricsAttempt();
+	let calls = 0;
+	owner.offer(async () => { calls++; });
+	owner.dispose(); owner.dispose();
+	assert.equal(owner.offer(async () => { calls++; }), false);
+	const replacement = new delivery.RuntimeMetricsAttempt();
+	assert.equal(replacement.offer(async () => { calls++; }), true);
+	await tick(); await tick();
+	assert.equal(calls, 1);
+	replacement.dispose();
+});
+
+test("shutdown aborts immediately but cannot overlap an unsettled process", async () => {
+	const owner = new delivery.RuntimeMetricsAttempt();
+	let signal!: AbortSignal;
+	let finish!: () => void;
+	owner.offer(s => { signal = s; return new Promise<void>(resolve => { finish = resolve; }); });
+	await tick();
+	assert.equal(owner.dispose(), undefined);
+	assert.equal(signal.aborted, true);
+	const replacement = new delivery.RuntimeMetricsAttempt();
+	assert.equal(replacement.offer(async () => {}), false);
+	finish(); await tick();
+	assert.equal(replacement.offer(async () => {}), true);
+	await tick(); replacement.dispose();
+});
+
+test("bounded shutdown join waits for the accepted attempt without replaying busy work", async () => {
+	const owner = new delivery.RuntimeMetricsAttempt();
+	let calls = 0;
+	let finish!: () => void;
+	owner.offer(() => { calls++; return new Promise<void>(resolve => { finish = resolve; }); });
+	assert.equal(owner.offer(async () => { calls++; }), false);
+	await tick();
+	let joined = false;
+	const joining = owner.waitForSettled(50).then(() => { joined = true; });
+	await tick();
+	assert.equal(joined, false);
+	finish();
+	await joining;
+	assert.equal(calls, 1, "joining never queues or retries discarded work");
+	owner.dispose();
+});
+
+test("bounded shutdown join returns after its deadline", async () => {
+	const owner = new delivery.RuntimeMetricsAttempt();
+	owner.offer(() => new Promise<void>(() => {}));
+	await tick();
+	await owner.waitForSettled(5);
+	owner.dispose();
+});

package/tests/runtime-metrics-extension.test.ts

@@ -0,0 +1,187 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import runtimeMetrics from "../extensions/runtime-metrics.ts";
+import { parseAgentClass, type RuntimeMetricBucket } from "../lib/runtime-metrics.ts";
+import { createPiCatalogNameLookup, type PiCatalogName } from "../lib/runtime-metrics-pi-identity.ts";
+import { CHILD_METRICS_EVENT, childEvent } from "../lib/runtime-metrics-children.ts";
+import { normalizeRpcEvent, TASK_EVENT } from "../lib/agents-protocol.ts";
+
+const tick = () => new Promise<void>(resolve => setImmediate(resolve));
+type CatalogLookup = NonNullable<NonNullable<Parameters<typeof runtimeMetrics>[2]>["lookup"]>;
+function harness(env: NodeJS.ProcessEnv = {}, lookup?: CatalogLookup,
+	classify?: (input: unknown) => PiCatalogName, mode: "tui" | "print" = "tui", shutdownWaitMs = 1500) {
+	const handlers = new Map<string, Function>();
+	const listeners = new Map<string, Function>();
+	let session = "first";
+	let finish!: () => void;
+	let signal!: AbortSignal;
+	const sent: RuntimeMetricBucket[][] = [];
+	const launches: unknown[] = [];
+	const ctx: any = { cwd: "/fixture", mode, model: { provider: "openai", id: "gpt-4o" },
+		sessionManager: { getSessionId: () => session, getEntries: () => assert.fail("no reconstruction") } };
+	const pi: any = { on: (name: string, handler: Function) => handlers.set(name, handler),
+		getThinkingLevel: () => "high", registerCommand() {},
+		appendEntry: () => assert.fail("no metrics persistence"),
+		events: { on: (name: string, handler: Function) => { listeners.set(name, handler); return () => listeners.delete(name); } } };
+	runtimeMetrics(pi, env, { lookup, classify, now: () => 0, shutdownWaitMs, send: (rows, _cwd, deps) => {
+		sent.push(structuredClone(rows)); launches.push(structuredClone(deps?.launches)); signal = deps!.signal!;
+		return new Promise(resolve => { finish = () => resolve("discarded"); });
+	} });
+	return { sent, launches, ctx, handlers,
+		emit: (name: string, event: any = {}) => handlers.get(name)?.(event, ctx),
+		bus: (event: unknown) => listeners.get(CHILD_METRICS_EVENT)?.(event),
+		replace: () => { session = "second"; }, signal: () => signal,
+		finish: async () => { finish(); await tick(); },
+	};
+}
+const final = (input = 7) => ({ role: "assistant", provider: "openai", model: "gpt-4o", responseModel: "gpt-4o",
+	providerThinkingLevel: "low", stopReason: "stop", usage: { input, output: 3, cacheRead: 0 },
+	content: [{ text: "private response" }], errorMessage: "private error", path: "/private" });
+
+test("message classification retries a failed catalog load without awaiting it", async () => {
+	let calls = 0;
+	const publicName = Object.freeze({ classification: "catalog_public", modelId: "gpt-4o" }) satisfies PiCatalogName;
+	const catalog = new Map([[JSON.stringify(["openai", "gpt-4o"]), publicName]]);
+	const catalogLookup = createPiCatalogNameLookup(async () => {
+		calls++;
+		if (calls === 1) throw new Error("transient catalog failure");
+		return catalog;
+	});
+	const h = harness({}, catalogLookup.lookup, catalogLookup.classify);
+	h.emit("session_start");
+	await tick();
+	assert.equal(calls, 1);
+	assert.equal(h.emit("message_end", { message: final() }), undefined);
+	assert.equal(calls, 2);
+	await tick();
+	assert.equal(h.sent.length, 1);
+	assert.equal(h.sent[0][0].observedModelId, "unknown", "the racing row remains fail-closed");
+	await h.finish();
+	h.emit("message_end", { message: final(8) });
+	await tick();
+	assert.equal(h.sent[1][0].observedModelId, "gpt-4o", "a later row uses the recovered catalog");
+	await h.finish();
+	h.emit("session_shutdown");
+});
+
+test("final callback returns before blocked transport; busy and duplicate messages drop", async () => {
+	const h = harness(); await h.emit("session_start");
+	h.emit("turn_start"); h.emit("before_provider_request");
+	const message = final();
+	assert.equal(h.emit("message_end", { message }), undefined);
+	assert.equal(h.sent.length, 0);
+	h.emit("message_end", { message });
+	h.emit("message_end", { message: final(99) });
+	await tick(); assert.equal(h.sent.length, 1);
+	assert.equal(h.sent[0][0].tokens.input.sum, 7);
+	assert.equal(h.sent[0][0].effort, "high");
+	assert.equal(h.sent[0][0].providerThinkingLevel, "low");
+	assert.ok(!JSON.stringify(h.sent).includes("private"));
+	await h.finish(); await tick();
+	assert.equal(h.sent.length, 1, "no replay after failure");
+	h.emit("message_end", { message: final(2) }); await tick();
+	assert.equal(h.sent[1][0].tokens.input.sum, 2, "event usage, never cumulative totals");
+	assert.equal(h.sent[1][0].responses, 1);
+	await h.finish(); h.emit("session_shutdown");
+});
+
+test("replacement before launch cancels stale work; shutdown does not await a blocked child", async () => {
+	const h = harness(); await h.emit("session_start");
+	h.emit("message_end", { message: final() });
+	h.replace(); await h.emit("session_start"); await tick();
+	assert.equal(h.sent.length, 0);
+	h.emit("message_end", { message: final() }); await tick();
+	assert.equal(h.emit("session_shutdown"), undefined);
+	assert.equal(h.signal().aborted, true);
+	await h.finish();
+});
+
+test("print shutdown joins an accepted orchestrator delivery before disposing", async () => {
+	const h = harness({}, undefined, undefined, "print", 50); await h.emit("session_start");
+	h.emit("message_end", { message: final() }); await tick();
+	let stopped = false;
+	const shutdown = h.emit("session_shutdown").then(() => { stopped = true; });
+	await tick();
+	assert.equal(stopped, false);
+	assert.equal(h.signal().aborted, false);
+	await h.finish(); await shutdown;
+	assert.equal(stopped, true);
+});
+
+test("print shutdown joins an accepted child launch and response delivery", async () => {
+	const h = harness({}, undefined, undefined, "print", 50); await h.emit("session_start");
+	const observation = normalizeRpcEvent({ type: "message_end", message: final() }, { observeResponses: true })
+		.find(event => event.type === TASK_EVENT.RESPONSE_OBSERVATION);
+	assert.ok(observation?.type === TASK_EVENT.RESPONSE_OBSERVATION);
+	h.bus(childEvent("first", "child", {
+		agentClass: parseAgentClass("sdd-explore")!, selectedProvider: "openai", selectedModelId: "gpt-4o", selectedEffort: "high",
+	}, "completed", { coverage: "final_assistant_messages_only", agentSettled: true, droppedResponses: 0,
+		responses: [observation.observation] }, 0)!);
+	await tick();
+	const shutdown = h.emit("session_shutdown");
+	assert.equal(h.sent[0][0].agentClass, "sdd-explore");
+	assert.deepEqual(h.launches[0], [{ evidence: "launch_configuration", agentClass: "sdd-explore", selectedProvider: "openai",
+		selectedModelId: "gpt-4o", selectedEffort: "high", launches: 1 }]);
+	assert.equal(h.signal().aborted, false);
+	await h.finish(); await shutdown;
+});
+
+test("print shutdown aborts a delivery after the bounded join deadline", async () => {
+	const h = harness({}, undefined, undefined, "print", 5); await h.emit("session_start");
+	h.emit("message_end", { message: final() }); await tick();
+	await h.emit("session_shutdown");
+	assert.equal(h.signal().aborted, true);
+	await h.finish();
+});
+
+test("interactive shutdown never joins a blocked delivery", async () => {
+	const h = harness({}, undefined, undefined, "tui", 50); await h.emit("session_start");
+	h.emit("message_end", { message: final() }); await tick();
+	assert.equal(h.emit("session_shutdown"), undefined);
+	assert.equal(h.signal().aborted, true);
+	await h.finish();
+});
+
+for (const env of [{ DO_NOT_TRACK: "1" }, { GENTLE_AI_TELEMETRY: "0" }, { CI: "true" }, { GENTLE_PI_AGENTS_CHILD: "1" }]) {
+	test(`opt-out suppresses hooks and launches: ${Object.keys(env)[0]}`, async () => {
+		const h = harness(env); await h.emit("session_start");
+		h.emit("message_end", { message: final() }); await tick();
+		assert.equal(h.handlers.size, 0); assert.equal(h.sent.length, 0);
+	});
+}
+
+test("environment veto between callback and launch discards accepted event", async () => {
+	const env: NodeJS.ProcessEnv = {};
+	const h = harness(env); await h.emit("session_start");
+	h.emit("message_end", { message: final() }); env.DO_NOT_TRACK = "1";
+	await tick(); assert.equal(h.sent.length, 0); h.emit("session_shutdown");
+});
+
+test("tool and partial assistant messages are not consumed as primary usage", async () => {
+	const h = harness(); await h.emit("session_start");
+	for (const message of [{ ...final(), role: "toolResult" }, { ...final(), stopReason: "pending" }, { ...final(), stopReason: "deferred" }]) h.emit("message_end", { message });
+	await tick(); assert.equal(h.sent.length, 0); h.emit("session_shutdown");
+});
+
+test("child completion consumed once, busy children drop, and primary usage stays separate", async () => {
+	const h = harness(); await h.emit("session_start");
+	const observation = normalizeRpcEvent({ type: "message_end", message: final() }, { observeResponses: true })
+		.find(event => event.type === TASK_EVENT.RESPONSE_OBSERVATION);
+	assert.ok(observation?.type === TASK_EVENT.RESPONSE_OBSERVATION);
+	const event = (taskId: string) => childEvent("first", taskId,
+		{ agentClass: parseAgentClass("verify")!, selectedProvider: "openai", selectedModelId: "gpt-4o", selectedEffort: "high" }, "completed",
+		{ coverage: "final_assistant_messages_only", agentSettled: true, droppedResponses: 0, responses: [observation.observation] }, 0)!;
+	h.bus(event("one")); h.bus(event("one")); h.bus(event("busy"));
+	await tick(); assert.equal(h.sent.length, 1);
+	assert.equal(h.sent[0][0].agentClass, "verify");
+	assert.deepEqual(h.launches[0], [{ evidence: "launch_configuration", agentClass: "verify", selectedProvider: "openai",
+		selectedModelId: "gpt-4o", selectedEffort: "high", launches: 1 }]);
+	assert.equal(h.sent[0][0].effort, "high", "child response retains launch selection separately from response evidence");
+	assert.equal(h.sent[0][0].providerThinkingLevel, "low");
+	await h.finish(); h.bus(event("busy")); await tick();
+	assert.equal(h.sent.length, 1, "busy completion stays consumed");
+	h.emit("message_end", { message: final(2) }); await tick();
+	assert.equal(h.sent[1][0].agentClass, "orchestrator");
+	assert.equal(h.sent[1][0].tokens.input.sum, 2);
+	await h.finish(); h.emit("session_shutdown");
+});