gentle-pi 2.4.0 → 2.6.0

package/lib/review-session-standing-permission.ts

@@ -0,0 +1,240 @@
+import { execFile, execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { realpathSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { promisify } from "node:util";
+
+export const REVIEW_SESSION_PERMISSION_REGISTRY_SCHEMA = "gentle-pi.review-session-standing-permission/v1";
+export const REVIEW_SESSION_PERMISSION_REGISTRY_SYMBOL = Symbol.for(REVIEW_SESSION_PERMISSION_REGISTRY_SCHEMA);
+
+const execFileAsync = promisify(execFile);
+
+export interface GitCommandOptions {
+	encoding: "utf8";
+	timeout: number;
+	maxBuffer: number;
+	windowsHide?: boolean;
+}
+
+export type GitAsyncRunner = (command: string, args: readonly string[], options: GitCommandOptions) => Promise<{ stdout: string }>;
+export type GitSyncRunner = (command: string, args: readonly string[], options: GitCommandOptions) => string;
+
+export interface ReviewSessionManager {
+	getSessionId(): unknown;
+}
+
+export interface ReviewSessionContext {
+	cwd: string;
+	mode?: string;
+	hasUI: boolean;
+	ui?: { getAllThemes?: () => readonly unknown[] };
+	sessionManager: ReviewSessionManager;
+}
+
+export interface ReviewSessionIdentity {
+	readonly sessionManager: ReviewSessionManager;
+	readonly sessionId: string;
+	readonly worktreeRoot: string;
+	// A SHA-256 digest of the canonical Git common directory. It is stable for
+	// sibling worktrees of one clone without serializing a filesystem path.
+	readonly repositoryIdentity: string;
+}
+
+interface ReviewSessionPermissionRegistry {
+	readonly schema: typeof REVIEW_SESSION_PERMISSION_REGISTRY_SCHEMA;
+	readonly permissions: WeakMap<object, Map<string, Set<string>>>;
+	readonly revocationEpochs: WeakMap<object, Map<string, number>>;
+}
+
+type GlobalRegistry = Record<symbol, unknown>;
+
+function registry(): ReviewSessionPermissionRegistry | undefined {
+	const globalRegistry = globalThis as GlobalRegistry;
+	const current = globalRegistry[REVIEW_SESSION_PERMISSION_REGISTRY_SYMBOL];
+	if (current === undefined) {
+		const created: ReviewSessionPermissionRegistry = {
+			schema: REVIEW_SESSION_PERMISSION_REGISTRY_SCHEMA,
+			permissions: new WeakMap(),
+			revocationEpochs: new WeakMap(),
+		};
+		globalRegistry[REVIEW_SESSION_PERMISSION_REGISTRY_SYMBOL] = created;
+		return created;
+	}
+	if (
+		typeof current !== "object" ||
+		current === null ||
+		(current as { schema?: unknown }).schema !== REVIEW_SESSION_PERMISSION_REGISTRY_SCHEMA ||
+		!((current as { permissions?: unknown }).permissions instanceof WeakMap) ||
+		!((current as { revocationEpochs?: unknown }).revocationEpochs instanceof WeakMap)
+	) return undefined;
+	return current as ReviewSessionPermissionRegistry;
+}
+
+function exactSessionId(sessionManager: ReviewSessionManager): string | undefined {
+	try {
+		const value = sessionManager.getSessionId();
+		return typeof value === "string" && value.length > 0 ? value : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function canonicalRepositoryIdentity(commonDir: string): string {
+	return `sha256:${createHash("sha256").update(commonDir).digest("hex")}`;
+}
+
+function validAbsoluteGitPath(value: string): boolean {
+	return isAbsolute(value) && value.length > 0 && !value.includes("\n") && !value.includes("\r");
+}
+
+export async function resolveCanonicalGitWorktreeRoot(
+	cwd: string,
+	run: GitAsyncRunner = execFileAsync as unknown as GitAsyncRunner,
+): Promise<string | undefined> {
+	try {
+		const result = await run("git", ["-C", cwd, "rev-parse", "--show-toplevel"], {
+			encoding: "utf8",
+			timeout: 5_000,
+			maxBuffer: 64 * 1024,
+			windowsHide: true,
+		});
+		const output = result.stdout.trim();
+		if (!validAbsoluteGitPath(output)) return undefined;
+		return await realpath(output);
+	} catch {
+		return undefined;
+	}
+}
+
+/** Resolves a non-secret, clone-stable identity from Git's canonical common dir. */
+export async function resolveCanonicalGitRepositoryIdentity(
+	cwd: string,
+	run: GitAsyncRunner = execFileAsync as unknown as GitAsyncRunner,
+): Promise<string | undefined> {
+	try {
+		const result = await run("git", ["-C", cwd, "rev-parse", "--git-common-dir"], {
+			encoding: "utf8",
+			timeout: 5_000,
+			maxBuffer: 64 * 1024,
+			windowsHide: true,
+		});
+		const output = result.stdout.trim();
+		if (output.length === 0 || output.includes("\n") || output.includes("\r")) return undefined;
+		return canonicalRepositoryIdentity(await realpath(resolve(cwd, output)));
+	} catch {
+		return undefined;
+	}
+}
+
+/** The parent AgentRunner binds a child task to this same digest at spawn time. */
+export function resolveCanonicalGitRepositoryIdentitySync(
+	cwd: string,
+	run: GitSyncRunner = execFileSync as unknown as GitSyncRunner,
+): string | undefined {
+	try {
+		const output = run("git", ["-C", cwd, "rev-parse", "--git-common-dir"], { encoding: "utf8", timeout: 5_000, maxBuffer: 64 * 1024, windowsHide: true }).trim();
+		if (output.length === 0 || output.includes("\n") || output.includes("\r")) return undefined;
+		return canonicalRepositoryIdentity(realpathSync(resolve(cwd, output)));
+	} catch {
+		return undefined;
+	}
+}
+
+function hasInteractiveTui(context: ReviewSessionContext): boolean {
+	if (context.mode !== undefined) return context.mode === "tui";
+	try {
+		// Pi 0.85 exposes ctx.mode in the documented SDK surface, while its
+		// compatibility runner omits that property. In the latter, the real TUI
+		// has themes and RPC's deliberately unsupported TUI surface returns none.
+		return (context.ui?.getAllThemes?.().length ?? 0) > 0;
+	} catch {
+		return false;
+	}
+}
+
+export async function captureReviewSessionIdentity(
+	context: ReviewSessionContext,
+	processEnv: NodeJS.ProcessEnv = process.env,
+	resolveRoot: (cwd: string) => Promise<string | undefined> = resolveCanonicalGitWorktreeRoot,
+	resolveRepositoryIdentity: (cwd: string) => Promise<string | undefined> = resolveCanonicalGitRepositoryIdentity,
+): Promise<ReviewSessionIdentity | undefined> {
+	if (processEnv.GENTLE_PI_AGENTS_CHILD === "1" || context.hasUI !== true || !hasInteractiveTui(context)) return undefined;
+	const sessionManager = context.sessionManager;
+	if (typeof sessionManager !== "object" || sessionManager === null) return undefined;
+	const sessionId = exactSessionId(sessionManager);
+	if (sessionId === undefined) return undefined;
+	const [worktreeRoot, repositoryIdentity] = await Promise.all([resolveRoot(context.cwd), resolveRepositoryIdentity(context.cwd)]);
+	if (worktreeRoot === undefined || repositoryIdentity === undefined) return undefined;
+	return { sessionManager, sessionId, worktreeRoot, repositoryIdentity };
+}
+
+export function sameReviewSessionIdentity(left: ReviewSessionIdentity, right: ReviewSessionIdentity): boolean {
+	return left.sessionManager === right.sessionManager && left.sessionId === right.sessionId && left.repositoryIdentity === right.repositoryIdentity;
+}
+
+function epochFor(state: ReviewSessionPermissionRegistry, sessionManager: object, sessionId: string): number {
+	return state.revocationEpochs.get(sessionManager)?.get(sessionId) ?? 0;
+}
+
+function advanceEpoch(state: ReviewSessionPermissionRegistry, sessionManager: object, sessionId: string): void {
+	let sessions = state.revocationEpochs.get(sessionManager);
+	if (sessions === undefined) {
+		sessions = new Map();
+		state.revocationEpochs.set(sessionManager, sessions);
+	}
+	sessions.set(sessionId, epochFor(state, sessionManager, sessionId) + 1);
+}
+
+export function reviewSessionPermissionEpoch(identity: ReviewSessionIdentity): number | undefined {
+	const state = registry();
+	return state === undefined ? undefined : epochFor(state, identity.sessionManager, identity.sessionId);
+}
+
+export function grantReviewSessionPermission(identity: ReviewSessionIdentity, expectedEpoch?: number): boolean {
+	const state = registry();
+	if (state === undefined || (expectedEpoch !== undefined && epochFor(state, identity.sessionManager, identity.sessionId) !== expectedEpoch)) return false;
+	let sessions = state.permissions.get(identity.sessionManager);
+	if (sessions === undefined) {
+		sessions = new Map();
+		state.permissions.set(identity.sessionManager, sessions);
+	}
+	let roots = sessions.get(identity.sessionId);
+	if (roots === undefined) {
+		roots = new Set();
+		sessions.set(identity.sessionId, roots);
+	}
+	roots.add(identity.repositoryIdentity);
+	return true;
+}
+
+// A grant belongs to one live session and one Git clone. It follows sibling
+// worktrees through their common directory, never an unrelated repository.
+export function hasReviewSessionPermission(identity: ReviewSessionIdentity): boolean {
+	return registry()?.permissions.get(identity.sessionManager)?.get(identity.sessionId)?.has(identity.repositoryIdentity) === true;
+}
+
+export function revokeReviewSessionPermission(identity: ReviewSessionIdentity): boolean {
+	const state = registry();
+	if (state === undefined) return false;
+	advanceEpoch(state, identity.sessionManager, identity.sessionId);
+	const sessions = state.permissions.get(identity.sessionManager);
+	const roots = sessions?.get(identity.sessionId);
+	if (sessions === undefined || roots === undefined) return false;
+	const removed = roots.delete(identity.repositoryIdentity);
+	if (roots.size === 0) sessions.delete(identity.sessionId);
+	if (sessions.size === 0) state.permissions.delete(identity.sessionManager);
+	return removed;
+}
+
+export function revokeReviewSessionPermissionsForSession(sessionManager: object, sessionId: string): boolean {
+	if (sessionId.length === 0) return false;
+	const state = registry();
+	if (state === undefined) return false;
+	advanceEpoch(state, sessionManager, sessionId);
+	const sessions = state.permissions.get(sessionManager);
+	if (sessions === undefined) return false;
+	const removed = sessions.delete(sessionId);
+	if (sessions.size === 0) state.permissions.delete(sessionManager);
+	return removed;
+}

package/lib/runtime-metrics-children.ts

@@ -0,0 +1,199 @@
+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, parseAgentClass, RuntimeMetrics, UNKNOWN_AGENT_CLASS, validRuntimeResponse, type AgentClass, type FinalResponse, type RuntimeMetricBucket } from "./runtime-metrics.ts";
+import { classifyPiCatalogName } from "./runtime-metrics-pi-identity.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 providers = ["anthropic", "openai", "openai-codex", "google", "google-vertex", "amazon-bedrock", "openrouter", "custom", "unknown"];
+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 providers.includes(value as string) ? value as FinalResponse["provider"] : value ? "custom" : "unknown";
+}
+function modelId(namespace: unknown, value: unknown): string {
+	if (value === "unknown" || value === undefined) return "unknown";
+	return classifyRuntimeModelId(namespace, value, classifyPiCatalogName);
+}
+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,166 @@
+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 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;
+function publicModel(provider: string, id: string) {
+	const matches = (rule: { const?: string; enum?: string[] }, value: string) => rule.const === value || rule.enum?.includes(value);
+	if (schema.$defs.model.oneOf.some(({ properties }) => matches(properties.provider, provider) && matches(properties.id, id))) return { provider, id };
+	const kind = !id || id === "unknown" ? "unknown" : "custom";
+	return { provider: kind, id: kind };
+}
+
+/** 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";
+			const response = typeof row.responseModelId === "string" && row.responseModelId !== "unknown" && row.responseModelId !== "";
+			const selected = typeof row.selectedModelId === "string" && row.selectedModelId !== "unknown" && row.selectedModelId !== "";
+			const model = response ? publicModel(row.provider, row.responseModelId)
+				: selected ? publicModel(row.selectedProvider, row.selectedModelId) : { 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 ? "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");
+		}
+	});
+}