gentle-pi 2.5.0 → 2.6.1

package/lib/runtime-metrics-children.ts

@@ -0,0 +1,197 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { parseAgentDefinition, type AgentDefinition, type ModelRef } from "./agents-config.ts";
+import type { ChildObservationSnapshot } from "./agents-runner.ts";
+import { FINISHED_STATUSES, type TaskStatus } from "./agents-protocol.ts";
+import { classifyRuntimeModelId, EFFORTS, normalizeRuntimeProvider, parseAgentClass, RuntimeMetrics, UNKNOWN_AGENT_CLASS, validRuntimeResponse, type AgentClass, type FinalResponse, type RuntimeMetricBucket } from "./runtime-metrics.ts";
+export const CHILD_METRICS_EVENT = "gentle:runtime-metrics:child/v1";
+// Local revocation notification invalidates active observations. Contains only
+// the local session join, never policy output.
+export const CHILD_METRICS_REVOKED = "gentle:runtime-metrics:revoked/v1";
+const missing = { state: "unavailable" } as const;
+const tokenFields = ["input", "output", "cacheRead", "cacheWrite", "reasoning", "totalTokens"] as const;
+/** Recognize only names from this package's fixed assets and the transport's
+ * closed agent_class enum. Customized packaged agents retain their schema name;
+ * user-defined names never enter telemetry. Exact fingerprints preserve the
+ * worker/explore/verify compatibility mapping whose packaged names are prefixed.
+ * Model/thinking routing is excluded from fingerprints because installation
+ * rewrites it. No installed files are read; this class is not execution/review authority.
+ * Only the fixed package catalog is cached; runtime instructions are not retained.
+ */
+let definitions: Array<{ name: string; fingerprint: string; fingerprintClass?: AgentClass }> | undefined;
+const packagedAgentClassAliases = new Map([["sdd-proposal", "sdd-propose"]] as const);
+function fingerprintAgentClassName(name: string): string {
+	const compatibilityName = name.startsWith("gentle-ai-") ? name.slice("gentle-ai-".length) : name;
+	return packagedAgentClassAliases.get(compatibilityName) ?? compatibilityName;
+}
+function fingerprint(agent: AgentDefinition): string {
+	return JSON.stringify([agent.name, agent.description, agent.instructions, agent.tools, agent.mode]);
+}
+export function classifyBuiltinAgent(agent: AgentDefinition): AgentClass {
+	try {
+		definitions ??= readdirSync(new URL("../assets/agents/", import.meta.url))
+			.filter(file => file.endsWith(".md")).map(file => {
+			const path = new URL(`../assets/agents/${file}`, import.meta.url);
+			const parsed = parseAgentDefinition(readFileSync(path, "utf8"), path.pathname, "global");
+			if (!("instructions" in parsed)) throw new Error("Invalid packaged definition");
+			return { name: parsed.name, fingerprint: fingerprint(parsed),
+				fingerprintClass: parseAgentClass(fingerprintAgentClassName(parsed.name)) };
+		});
+		const namedClass = parseAgentClass(packagedAgentClassAliases.get(agent.name) ?? agent.name);
+		if (namedClass && definitions.some(entry => entry.name === agent.name)) return namedClass;
+		return definitions.find(entry => entry.fingerprintClass && entry.fingerprint === fingerprint(agent))?.fingerprintClass ?? UNKNOWN_AGENT_CLASS;
+	} catch { return UNKNOWN_AGENT_CLASS; }
+}
+function provider(value: unknown): FinalResponse["provider"] {
+	return normalizeRuntimeProvider(value);
+}
+function modelId(namespace: unknown, value: unknown): string {
+	if (value === "unknown" || value === undefined) return "unknown";
+	return classifyRuntimeModelId(namespace, value);
+}
+function effort(value: unknown): FinalResponse["effort"] {
+	return EFFORTS.includes(value as FinalResponse["effort"]) ? value as FinalResponse["effort"] : "unavailable";
+}
+export interface LaunchSelection {
+	agentClass: AgentClass;
+	selectedProvider: FinalResponse["provider"];
+	selectedModelId: string;
+	selectedEffort: FinalResponse["effort"];
+}
+export interface ChildLaunchBucket extends LaunchSelection {
+	evidence: "launch_configuration";
+	launches: number;
+}
+export function launchSelection(agent: AgentDefinition, model: ModelRef | undefined, thinking: unknown): LaunchSelection {
+	return { agentClass: classifyBuiltinAgent(agent), selectedProvider: provider(model?.provider),
+		selectedModelId: modelId(model?.provider, model?.id), selectedEffort: effort(thinking) };
+}
+/** LOCAL event only: these two bounded join IDs must never enter output/export. */
+export interface ChildMetricsEvent {
+	schema: typeof CHILD_METRICS_EVENT;
+	parentSessionId: string;
+	taskId: string;
+	launchedAt: number;
+	launch: LaunchSelection;
+	status: TaskStatus;
+	agentSettled: boolean;
+	coverage: "final_assistant_messages_only";
+	droppedResponses: number;
+	responses: FinalResponse[];
+}
+export function childEvent(parentSessionId: string, taskId: string, launch: LaunchSelection, status: TaskStatus,
+	snapshot: ChildObservationSnapshot, launchedAt = 0): ChildMetricsEvent | undefined {
+	const result: ChildMetricsEvent = { schema: CHILD_METRICS_EVENT, parentSessionId, taskId, launchedAt, launch: { ...launch }, status,
+		agentSettled: snapshot.agentSettled, coverage: snapshot.coverage, droppedResponses: snapshot.droppedResponses,
+		responses: snapshot.responses.slice(0, 128).map((row, index) => {
+			const namespace = row.provider.state === "observed" ? row.provider.value : undefined;
+			const name = (value: typeof row.model) => value.state === "observed" ? modelId(namespace, value.value) : undefined;
+			return { kind: "final_assistant_response", responseId: String(index), agentClass: launch.agentClass,
+				executor: "worker", provider: provider(namespace), modelFamily: "unknown", observedModelId: name(row.model),
+				responseModelId: name(row.responseModel), providerThinkingLevel: effort(row.providerThinkingLevel.state === "observed" ? row.providerThinkingLevel.value : undefined),
+				selectedProvider: launch.selectedProvider, selectedModelId: launch.selectedModelId, effort: launch.selectedEffort,
+				error: row.stopReason === "error" ? "unknown" : row.stopReason === "aborted" ? "aborted" : "none",
+				tokens: Object.fromEntries(tokenFields.map(field => [field, { ...row.tokens[field] }])) as FinalResponse["tokens"],
+				responseHeadersMs: missing, fullResponseMs: missing };
+		}) };
+	return validEvent(result) ? result : undefined;
+}
+function validEvent(value: unknown): value is ChildMetricsEvent {
+	if (!value || typeof value !== "object") return false;
+	const e = value as ChildMetricsEvent;
+	const id = (value: unknown) => typeof value === "string" && value.length > 0 && value.length <= 128;
+	const l = e.launch;
+	return e.schema === CHILD_METRICS_EVENT && id(e.taskId) && id(e.parentSessionId)
+		&& Number.isFinite(e.launchedAt) && e.launchedAt >= 0
+		&& e.coverage === "final_assistant_messages_only" && typeof e.agentSettled === "boolean"
+		&& FINISHED_STATUSES.includes(e.status) && Number.isSafeInteger(e.droppedResponses) && e.droppedResponses >= 0
+		&& e.droppedResponses <= Number.MAX_SAFE_INTEGER && !!l && !!parseAgentClass(l.agentClass) && l.agentClass !== "orchestrator"
+		&& provider(l.selectedProvider) === l.selectedProvider && modelId(l.selectedProvider, l.selectedModelId) === l.selectedModelId
+		&& effort(l.selectedEffort) === l.selectedEffort && Array.isArray(e.responses) && e.responses.length <= 128
+		&& e.responses.every(row => validRuntimeResponse(row) && row.agentClass === l.agentClass
+			&& row.executor === "worker" && row.effort === l.selectedEffort && row.selectedProvider === l.selectedProvider && row.selectedModelId === l.selectedModelId
+			&& provider(row.provider) === row.provider && effort(row.providerThinkingLevel) === row.providerThinkingLevel
+			&& (row.observedModelId === undefined || modelId(row.provider, row.observedModelId) === row.observedModelId)
+			&& (row.responseModelId === undefined || modelId(row.provider, row.responseModelId) === row.responseModelId)
+			&& row.fullResponseMs.state === "unavailable" && row.responseHeadersMs.state === "unavailable");
+}
+/** Copy only validated local fields at the completion callback.
+ * Do not clone arbitrary event properties or retain a caller-mutable bus object.
+ */
+export function snapshotChildEvent(value: unknown): ChildMetricsEvent | undefined {
+	if (!validEvent(value)) return undefined;
+	const l = value.launch;
+	return { schema: CHILD_METRICS_EVENT, parentSessionId: value.parentSessionId, taskId: value.taskId, launchedAt: value.launchedAt,
+		launch: { agentClass: l.agentClass, selectedProvider: l.selectedProvider, selectedModelId: l.selectedModelId, selectedEffort: l.selectedEffort },
+		status: value.status, agentSettled: value.agentSettled, coverage: value.coverage, droppedResponses: value.droppedResponses,
+		responses: value.responses.map((row, index) => ({ kind: "final_assistant_response", responseId: String(index),
+			agentClass: row.agentClass, executor: "worker", provider: row.provider, observedModelId: row.observedModelId,
+			responseModelId: row.responseModelId, providerThinkingLevel: row.providerThinkingLevel, modelFamily: "unknown",
+			selectedProvider: l.selectedProvider, selectedModelId: l.selectedModelId, effort: l.selectedEffort, error: row.error,
+			tokens: Object.fromEntries(tokenFields.map(field => {
+				const t = row.tokens[field];
+				return [field, t?.state === "reported" ? { state: "reported", value: t.value } : { state: t?.state ?? "unavailable" }];
+			})) as FinalResponse["tokens"], responseHeadersMs: missing, fullResponseMs: missing })) };
+}
+
+/** Export-facing shape: no IDs, paths, task labels, or raw agent/model names.
+ * Rankings are descending counts, NOT quality/success comparisons. Native
+ * transport is deliberately absent. Response buckets retain selected launch
+ * identity and effort separately from effective response evidence.
+ */
+export interface ChildCompositionSnapshot {
+	launches: ChildLaunchBucket[];
+	responses: RuntimeMetricBucket[];
+	settled: number;
+	statuses: Record<"completed" | "failed" | "cancelled" | "timed_out", number>;
+	droppedResponses: number;
+	saturated: boolean;
+}
+export class ChildComposition {
+	#seen = new Set<string>();
+	#pending = new WeakSet<object>();
+	#metrics = new RuntimeMetrics();
+	#launches = new Map<string, ChildLaunchBucket>();
+	#count = 0;
+	#settled = 0;
+	#statuses = { completed: 0, failed: 0, cancelled: 0, timed_out: 0 };
+	#dropped = 0;
+	#saturated = false;
+	reserve(value: unknown, session: string): value is ChildMetricsEvent {
+		if (!validEvent(value) || value.parentSessionId !== session || this.#seen.has(value.taskId)) return false;
+		if (this.#seen.size >= 256) { this.#saturated = true; return false; }
+		this.#seen.add(value.taskId);
+		this.#pending.add(value);
+		return true;
+	}
+	record(event: ChildMetricsEvent): void {
+		if (!this.#pending.delete(event) || !validEvent(event)) return;
+		const key = JSON.stringify(event.launch);
+		let bucket = this.#launches.get(key);
+		if (!bucket && this.#launches.size < 64) {
+			bucket = { ...event.launch, evidence: "launch_configuration", launches: 0 };
+			this.#launches.set(key, bucket);
+		}
+		if (bucket) bucket.launches++;
+		else this.#saturated = true;
+		this.#settled += Number(event.agentSettled);
+		this.#statuses[event.status as keyof ChildCompositionSnapshot["statuses"]]++;
+		this.#dropped = Math.min(Number.MAX_SAFE_INTEGER, this.#dropped + event.droppedResponses);
+		for (const row of event.responses) {
+			if (this.#metrics.record({ ...row, responseId: String(this.#count + 1) }) === "recorded") this.#count++;
+			else { this.#dropped = Math.min(Number.MAX_SAFE_INTEGER, this.#dropped + 1); this.#saturated = true; }
+		}
+	}
+	clear(): void {
+		this.#metrics = new RuntimeMetrics();
+		this.#pending = new WeakSet();
+		this.#launches.clear();
+		this.#count = this.#settled = this.#dropped = 0;
+		this.#statuses = { completed: 0, failed: 0, cancelled: 0, timed_out: 0 };
+		// Bounded tombstones survive revocation; denied tasks cannot replay.
+	}
+	snapshot(): ChildCompositionSnapshot {
+		return structuredClone({ launches: [...this.#launches.values()].sort((a, b) => b.launches - a.launches),
+			responses: this.#metrics.snapshot().sort((a, b) => b.responses - a.responses),
+			settled: this.#settled, statuses: this.#statuses, droppedResponses: this.#dropped, saturated: this.#saturated });
+	}
+}

package/lib/runtime-metrics-delivery.ts

@@ -0,0 +1,68 @@
+// Shared across extension instances, including a cancelled process still exiting.
+let busy = false;
+
+/** One accepted attempt, never a queue. Defer resolver/process work beyond the
+ * provider callback. Busy events are discarded rather than captured for later.
+ * The transport must settle only after its process exits. Print-mode shutdown
+ * may join the one accepted attempt for a bounded deadline; it never queues or
+ * retries work. Every other disposal remains immediate.
+ */
+export class RuntimeMetricsAttempt {
+	#closed = false;
+	#scheduled?: ReturnType<typeof setImmediate>;
+	#abort?: AbortController;
+	#settled?: Promise<void>;
+	#release?: () => void;
+	offer(work: (signal: AbortSignal) => Promise<unknown>): boolean {
+		if (this.#closed || busy) return false;
+		busy = true;
+		const abort = new AbortController();
+		this.#abort = abort;
+		let release!: () => void;
+		const settled = new Promise<void>(resolve => { release = resolve; });
+		this.#settled = settled;
+		this.#release = release;
+		this.#scheduled = setImmediate(() => {
+			this.#scheduled = undefined;
+			void (async () => {
+				try { if (!abort.signal.aborted) await work(abort.signal); }
+				catch { /* An attempt is always best effort; never retry or report. */ }
+				finally {
+					this.#abort = undefined;
+					busy = false;
+					if (this.#settled === settled) {
+						this.#settled = undefined;
+						this.#release = undefined;
+					}
+					release();
+				}
+			})();
+		});
+		return true;
+	}
+	/** Await only the already accepted attempt, up to the caller's deadline. */
+	async waitForSettled(timeoutMs: number): Promise<void> {
+		const settled = this.#settled;
+		if (!settled) return;
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		try {
+			await Promise.race([settled, new Promise<void>(resolve => { timer = setTimeout(resolve, timeoutMs); })]);
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
+	}
+	dispose(): void {
+		if (this.#closed) return;
+		this.#closed = true;
+		if (this.#scheduled) {
+			clearImmediate(this.#scheduled);
+			this.#scheduled = undefined;
+			busy = false;
+			this.#settled = undefined;
+			this.#release?.();
+			this.#release = undefined;
+		}
+		this.#abort?.abort();
+		this.#abort = undefined;
+	}
+}

package/lib/runtime-metrics-native.ts

@@ -0,0 +1,174 @@
+import { spawn, type ChildProcessWithoutNullStreams, type SpawnOptionsWithoutStdio } from "node:child_process";
+import { resolveGentleAiBinary } from "./gentle-ai-binary.ts";
+import { runtimeMetricsEnvAllows } from "./runtime-metrics-policy.ts";
+import { isPublicRuntimeModelId, normalizeRuntimeModel, type RuntimeMetricBucket } from "./runtime-metrics.ts";
+import type { ChildLaunchBucket } from "./runtime-metrics-children.ts";
+
+import schema from "../contracts/telemetry/runtime-aggregate-v1.schema.json" with { type: "json" };
+
+export type NativeRuntimeResult = "stored" | "duplicate" | "discarded" | "disabled";
+export const NATIVE_SEND_ACK_SCHEMA = "gentle-ai.telemetry-runtime-send/v1";
+const MAX_METRIC = schema.$defs.count.maximum;
+const count = (value: number) => Number.isSafeInteger(value) && value >= 0 && value <= MAX_METRIC;
+// Re-derives through the same schema-driven normalizer used at record time so
+// an already-classified (provider, id) pair is re-validated against the
+// transport's anyOf shape before it ever leaves the machine.
+function publicModel(provider: string, id: string) {
+	return normalizeRuntimeModel(provider, id);
+}
+
+/** Closed field projection of one event, not a session snapshot. Oversized or
+ * invalid events discard whole; never split into queued sends or invent IDs.
+ */
+export function encodeNativeRuntimeEvent(source: readonly RuntimeMetricBucket[], launches: readonly ChildLaunchBucket[] = []): string | undefined {
+	if (!Array.isArray(source) || !Array.isArray(launches) || source.length < 1
+		|| source.length + launches.length > schema.properties.rows.maxItems) return undefined;
+	try {
+		const rows: Array<Record<string, unknown>> = source.map(row => {
+			if (!count(row.responses)) throw new Error("Invalid occurrence coverage");
+			const token = (field: keyof RuntimeMetricBucket["tokens"]) => {
+				const t = row.tokens[field];
+				const coverage = { reported: t.reported, unavailable: t.unavailable, unsupported: t.unsupported, sum: t.sum };
+				if (!Object.values(coverage).every(count) || (!coverage.reported && coverage.sum !== 0)) throw new Error("Invalid coverage");
+				return coverage;
+			};
+			const agentClass = schema.$defs.row.properties.agent_class.enum.includes(row.agentClass) ? row.agentClass : "unknown";
+			const effort = (value: string) => schema.$defs.effort.enum.includes(value) ? value : "unavailable";
+			// Evidence order: an actually-dispatched response model wins; otherwise
+			// the caller's own selection; otherwise the SDK-observed model the
+			// selection never captured (still labeled "selected" evidence, since
+			// the transport has no separate "observed" category). Never response
+			// evidence unless the response model itself normalizes to a public id.
+			const response = isPublicRuntimeModelId(row.responseModelId);
+			const selected = !response && isPublicRuntimeModelId(row.selectedModelId);
+			const observed = !response && !selected && isPublicRuntimeModelId(row.observedModelId);
+			const model = response ? publicModel(row.provider, row.responseModelId)
+				: selected ? publicModel(row.selectedProvider, row.selectedModelId)
+				: observed ? publicModel(row.provider, row.observedModelId)
+				: { provider: "unknown", id: "unknown" };
+			const time = row.fullResponseMs;
+			if (!count(time.measured) || !Number.isFinite(time.sum) || time.sum < 0 || time.sum > MAX_METRIC
+				|| (!time.measured && time.sum !== 0)) throw new Error("Invalid duration");
+			return { model, model_evidence: response ? "response" : (selected || observed) ? "selected" : "unknown",
+				agent_kind: agentClass === "orchestrator" || agentClass === "unknown" ? agentClass : "built_in", agent_class: agentClass,
+				selected_effort: effort(row.effort), effective_effort: effort(row.providerThinkingLevel),
+				launches: null, responses: row.responses,
+				input_tokens: token("input"), output_tokens: token("output"), cache_read_tokens: token("cacheRead"),
+				cache_creation_tokens: token("cacheWrite"), reasoning_tokens: token("reasoning"), total_tokens: token("totalTokens"),
+				error_category: row.error === "authentication" ? "auth" : ["none", "aborted", "rate_limit"].includes(row.error) ? row.error : "unknown",
+				duration: time.measured > 0 ? { kind: "request", measured_count: time.measured, sum_ms: time.sum }
+					: { kind: "unavailable", measured_count: 0, sum_ms: null } };
+		});
+		for (const launch of launches) {
+			if (!count(launch.launches) || launch.evidence !== "launch_configuration") return undefined;
+			const agentClass = schema.$defs.row.properties.agent_class.enum.includes(launch.agentClass) ? launch.agentClass : "unknown";
+			const empty = { reported: 0, unavailable: 0, unsupported: 0, sum: 0 };
+			rows.push({ model: publicModel(launch.selectedProvider, launch.selectedModelId), model_evidence: "selected",
+				agent_kind: agentClass === "orchestrator" || agentClass === "unknown" ? agentClass : "built_in", agent_class: agentClass,
+				selected_effort: schema.$defs.effort.enum.includes(launch.selectedEffort) ? launch.selectedEffort : "unavailable",
+				effective_effort: "unavailable", launches: launch.launches, responses: null,
+				input_tokens: empty, output_tokens: empty, cache_read_tokens: empty, cache_creation_tokens: empty,
+				reasoning_tokens: empty, total_tokens: empty, error_category: "unknown",
+				duration: { kind: "unavailable", measured_count: 0, sum_ms: null } });
+		}
+		const payload = JSON.stringify({ schema: schema.properties.schema.const, registry: schema.properties.registry.const, host: "pi", rows });
+		return Buffer.byteLength(payload) <= 16384 ? payload : undefined;
+	} catch { return undefined; }
+}
+export interface NativeRuntimeTransportDeps {
+	/** Observed launch occurrence accompanying this child completion, not totals. */
+	launches?: readonly ChildLaunchBucket[];
+	env?: NodeJS.ProcessEnv;
+	signal?: AbortSignal;
+	current?: () => boolean;
+	/** Injected test seams; production uses the verified pin or validated dev override. */
+	resolve?: () => string;
+	encode?: typeof encodeNativeRuntimeEvent;
+	spawn?: (file: string, args: string[], options: SpawnOptionsWithoutStdio) => ChildProcessWithoutNullStreams;
+}
+let busy = false;
+
+/** Native owns fresh policy and exactly one POST. No policy/capability probe,
+ * disk intake, flush, queue or retry. Call via RuntimeMetricsAttempt so binary
+ * verification is outside the provider callback. Cancellation requests a kill;
+ * the slot stays occupied until close, never permitting overlapping processes.
+ */
+export async function sendNativeRuntimeEvent(rows: readonly RuntimeMetricBucket[], cwd: string,
+	deps: NativeRuntimeTransportDeps = {}): Promise<NativeRuntimeResult> {
+	const env = deps.env ?? process.env;
+	if (!runtimeMetricsEnvAllows(env)) return "disabled";
+	if (busy || deps.signal?.aborted || deps.current?.() === false) return "discarded";
+	busy = true;
+	try {
+		const payload = (deps.encode ?? encodeNativeRuntimeEvent)(rows, deps.launches);
+		if (!payload || Buffer.byteLength(payload) > 16384) return "discarded";
+		const file = (deps.resolve ?? resolveGentleAiBinary)();
+		if (!runtimeMetricsEnvAllows(env)) return "disabled";
+		if (deps.signal?.aborted || deps.current?.() === false) return "discarded";
+		return await sendProcess(file, cwd, payload, env, deps.spawn ?? spawn, deps.signal);
+	} catch { return "discarded"; }
+	finally { busy = false; }
+}
+
+function sendProcess(file: string, cwd: string, payload: string, env: NodeJS.ProcessEnv,
+	launch: NonNullable<NativeRuntimeTransportDeps["spawn"]>, signal?: AbortSignal): Promise<NativeRuntimeResult> {
+	return new Promise(done => {
+		let child: ChildProcessWithoutNullStreams | undefined;
+		let output = "";
+		let rejected = false;
+		let settled = false;
+		const ignore = () => {};
+		const finish = (result: NativeRuntimeResult) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", cancel);
+			output = "";
+			if (child) {
+				for (const stream of [child.stdin, child.stdout, child.stderr]) {
+					stream.on("error", ignore);
+					try { stream.destroy(); } catch { /* Best effort cleanup. */ }
+				}
+				try { child.unref(); } catch { /* No diagnostics. */ }
+			}
+			done(result);
+		};
+		const cancel = () => {
+			if (rejected || settled) return;
+			rejected = true;
+			output = "";
+			try { child?.kill("SIGKILL"); } catch { /* Keep busy until close. */ }
+		};
+		const timer = setTimeout(cancel, 1000);
+		timer.unref();
+		try {
+			child = launch(file, ["telemetry", "runtime", "send", "--json"],
+				{ cwd, env, shell: false, windowsHide: true, stdio: ["pipe", "pipe", "pipe"] });
+			child.on("error", cancel);
+			for (const stream of [child.stdin, child.stdout, child.stderr]) stream.on("error", cancel);
+			child.stdout.on("data", (chunk: Buffer) => {
+				if (rejected || settled) return;
+				if (Buffer.byteLength(output) + chunk.length > 2048) { cancel(); return; }
+				output += chunk.toString("utf8");
+			});
+			child.stderr.on("data", cancel); // Do not retain or expose raw errors.
+			child.on("close", (code: number | null, exitSignal: NodeJS.Signals | null) => {
+				let result: NativeRuntimeResult = "discarded";
+				if (!rejected && code === 0 && exitSignal === null) {
+					try {
+						const value = JSON.parse(output);
+						if (Object.keys(value).sort().join(",") === "decision,schema" && value.schema === NATIVE_SEND_ACK_SCHEMA
+							&& ["stored", "duplicate", "discarded", "disabled"].includes(value.decision)) result = value.decision;
+					} catch { /* Invalid/old acknowledgements discard. */ }
+				}
+				finish(result);
+			});
+			signal?.addEventListener("abort", cancel, { once: true });
+			if (signal?.aborted) cancel();
+			if (!rejected) child.stdin.end(payload, "utf8");
+		} catch {
+			if (child) cancel();
+			else finish("discarded");
+		}
+	});
+}

package/lib/runtime-metrics-policy.ts

@@ -0,0 +1,51 @@
+import { gentleAiDevBinaryOverrideConfigured, resolveGentleAiBinary } from "./gentle-ai-binary.ts";
+import { createNodeExecFileAdapter, type ExecFileAdapter } from "./native-review-cli.ts";
+
+export interface RuntimeMetricsPolicyDeps { resolve?: () => string; exec?: ExecFileAdapter }
+
+export function runtimeMetricsEnvAllows(env: NodeJS.ProcessEnv): boolean {
+	// Unknown nonempty spellings veto too: never weaken a native environment veto.
+	const truthy = (value: string | undefined) => !["", "0", "false", "no", "off"].includes(value?.trim().toLowerCase() ?? "");
+	return !truthy(env.DO_NOT_TRACK) && !truthy(env.CI) && !truthy(env.GITHUB_ACTIONS)
+		&& env.GENTLE_AI_TELEMETRY?.trim() !== "0";
+}
+
+function publishedBinary(): string {
+	// This feature must not select an unpublished development binary or install one.
+	if (gentleAiDevBinaryOverrideConfigured()) throw new Error("Policy binary unavailable");
+	return resolveGentleAiBinary();
+}
+
+/** Only a validated boolean crosses this boundary; never raw stdout or errors.
+ * The shared adapter and outer timer bound asynchronous process waiting, NOT
+ * end-to-end time: the supported resolver synchronously reads/hashes the binary
+ * on every check. It exposes no supported validation cache. Keep verification
+ * intact rather than cache an unchecked path or invent stat-based trust.
+ * No retries, status/preview fallback, enrollment, installation or polling.
+ */
+export async function readRuntimeMetricsPolicy(cwd: string,
+	{ resolve = publishedBinary, exec = createNodeExecFileAdapter() }: RuntimeMetricsPolicyDeps = {}): Promise<boolean> {
+	const controller = new AbortController();
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	try {
+		const deadline = new Promise<false>(done => {
+			timer = setTimeout(() => { controller.abort(); done(false); }, 1000);
+		});
+		const probe = async () => {
+			const result = await exec({ file: resolve(), arguments: ["telemetry", "policy", "--json"],
+				cwd, timeoutMs: 1000, maxBufferBytes: 2048, signal: controller.signal });
+			if (result.exitCode !== 0 || result.signal !== null || result.timedOut !== false
+				|| result.outputLimitExceeded !== false || result.stderr !== ""
+				|| typeof result.stdout !== "string" || Buffer.byteLength(result.stdout) > 2048) return false;
+			const value: unknown = JSON.parse(result.stdout);
+			if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+			const row = value as Record<string, unknown>;
+			return Object.keys(row).sort().join(",") === "enabled,operation,reason,schema,source"
+				&& row.schema === "gentle-ai.telemetry-policy/v1" && row.operation === "policy"
+				&& typeof row.enabled === "boolean" && row.enabled && row.reason === "enabled"
+				&& ["DO_NOT_TRACK", "GENTLE_AI_TELEMETRY", "CI", "state", "default"].includes(row.source as string);
+		};
+		return await Promise.race([probe(), deadline]);
+	} catch { return false; }
+	finally { clearTimeout(timer); }
+}