@capxul/cli 4.20.0-beta.2 → 4.20.0-beta.4

package/dist/main.mjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-import process$1, { exit, platform, versions } from "node:process";
-import { Cause, Clock, Config, Console, Context, Crypto, Data, Deferred, Duration, Effect, Exit, Fiber, FiberSet, FileSystem, Layer, Logger, Metric, Option, Path, Queue, Redacted, Ref, Result, Schedule, Schema, SchemaGetter, SchemaIssue, SchemaParser, Scope, Stdio, Stream, Tracer } from "effect";
+import process$1, { arch, exit, platform, versions } from "node:process";
+import { Cause, Clock, Config, Console, Context, Crypto, Data, Deferred, Duration, Effect, Exit, Fiber, FiberSet, FileSystem, Layer, LogLevel, Logger, Metric, Option, Path, Queue, Redacted, Ref, References, Result, Schedule, Schema, SchemaGetter, SchemaIssue, SchemaParser, Scope, Stdio, Stream, Tracer } from "effect";
 import { NodeRuntime, NodeServices } from "@effect/platform-node";
 import { CliConfig, CliError, Command, Flag, GlobalFlag, Primitive } from "effect/unstable/cli";
 import * as nc from "node:crypto";
-import { FetchHttpClient, Headers, HttpBody, HttpClient, HttpClientRequest, HttpClientResponse, HttpTraceContext } from "effect/unstable/http";
+import { FetchHttpClient, Headers, HttpBody, HttpClient, HttpClientError, HttpClientRequest, HttpClientResponse, HttpTraceContext } from "effect/unstable/http";
 import { OtlpExporter, OtlpLogger, OtlpMetrics, OtlpSerialization, OtlpTracer } from "effect/unstable/observability";
 import { resolve } from "path";
 import util from "util";
@@ -473,7 +473,12 @@ const CREDENTIAL_FIELDS = /* @__PURE__ */ new Set([
 	"authcode",
 	"authorizationcode",
 	"oauthcode",
-	"codeverifier"
+	"codeverifier",
+	"devicecode",
+	"usercode",
+	"continuitytoken",
+	"refreshattemptid",
+	"revocationtoken"
 ]);
 /** Match credential fields by meaning, without hiding token addresses or replay IDs. */
 function isCredentialField(name, context) {
@@ -2398,6 +2403,8 @@ const COUNTRY_CODE_RE = /^[A-Z]{2}$/;
 const ACCOUNT_ID_RE = /^account_[0-9A-Za-z]+$/;
 const PARTY_ID_RE$1 = /^party_[0-9A-Za-z]+$/;
 const APP_ID_RE = /^app_[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+const CLIENT_REQUEST_ID_RE = /^creq_[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+const CLIENT_GRANT_ID_RE = /^cgrant_[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
 const TX_HASH_RE = /^0x[0-9a-f]{64}$/i;
 const WEI_RE = /^[0-9]+$/;
 Math.floor(Number.MAX_SAFE_INTEGER / 1e3);
@@ -6531,6 +6538,91 @@ const ContactActionProps = {
 	reason_code: OptionalReasonCode
 };
 /** One completed online CLI diagnostic. No command input or provider text. */
+const CLI_COMMAND_NAMES = [
+	"capxul",
+	"doctor",
+	"telemetry",
+	"telemetry.status",
+	"telemetry.enable",
+	"telemetry.disable",
+	"unknown"
+];
+const CLI_CAPABILITIES = [
+	"cli",
+	"diagnostics",
+	"collection"
+];
+const CLI_INVOCATION_KINDS = [
+	"command",
+	"help",
+	"version",
+	"completion",
+	"parse_refusal",
+	"collection_control"
+];
+const CliRelease = Schema.String.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._+-]{0,127}$/u));
+const CliInvocationProps = {
+	...TelemetryEnvelopeProps,
+	schema_version: Schema.Literal(1),
+	command: Schema.Literals(CLI_COMMAND_NAMES),
+	capability: Schema.Literals(CLI_CAPABILITIES),
+	invocation_kind: Schema.Literals(CLI_INVOCATION_KINDS),
+	invocation_id: Schema.String.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u)),
+	cli_identity_kind: Schema.optional(Schema.Literal("anonymous")),
+	anonymous_id: Schema.optional(Schema.String.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u))),
+	occurred_at: Schema.Number,
+	cli_version: CliRelease,
+	sdk_version: CliRelease,
+	release: CliRelease,
+	platform: Schema.Literals([
+		"darwin",
+		"linux",
+		"unknown"
+	]),
+	architecture: Schema.Literals([
+		"arm64",
+		"x64",
+		"unknown"
+	]),
+	ci: Schema.Boolean,
+	tty: Schema.Boolean,
+	output_mode: Schema.Literals(["human", "json"])
+};
+const CliFirstUsedTelemetryEventSchema = Schema.Struct({
+	name: Schema.Literal("cli_first_used"),
+	props: Schema.Struct(CliInvocationProps)
+});
+const CliCommandStartedTelemetryEventSchema = Schema.Struct({
+	name: Schema.Literal("cli_command_started"),
+	props: Schema.Struct({
+		...CliInvocationProps,
+		invocation_kind: Schema.Literals([
+			"command",
+			"help",
+			"version"
+		])
+	})
+});
+const CliCommandCompletedTelemetryEventSchema = Schema.Struct({
+	name: Schema.Literal("cli_command_completed"),
+	props: Schema.Struct({
+		...CliInvocationProps,
+		outcome: Schema.Literals([
+			"succeeded",
+			"refused",
+			"failed",
+			"cancelled"
+		]),
+		duration_ms: Schema.Number,
+		error_code: Schema.optional(Schema.Literals([
+			...CAPXUL_ERROR_CODES,
+			"CLI_USAGE",
+			"CLI_CONFIG",
+			"CLI_STORAGE",
+			"CLI_DEFECT"
+		]))
+	})
+});
 const CliDiagnosticCompletedTelemetryEventSchema = Schema.Struct({
 	name: Schema.Literal("cli_diagnostic_completed"),
 	props: Schema.Struct({
@@ -6832,6 +6924,9 @@ const TELEMETRY_EVENT_SCHEMAS = {
 	}),
 	ui_contact_action_completed: UiContactActionCompletedTelemetryEventSchema,
 	cli_diagnostic_completed: CliDiagnosticCompletedTelemetryEventSchema,
+	cli_first_used: CliFirstUsedTelemetryEventSchema,
+	cli_command_started: CliCommandStartedTelemetryEventSchema,
+	cli_command_completed: CliCommandCompletedTelemetryEventSchema,
 	activity_annotation_saved: ActivityAnnotationSavedTelemetryEventSchema,
 	ui_activity_action_completed: UiActivityActionCompletedTelemetryEventSchema,
 	auth_otp_requested: AuthOtpRequestedTelemetryEventSchema,
@@ -7540,6 +7635,30 @@ const PAYMENT_DOCUMENT_KINDS = [
 	"receipt",
 	"withdrawal"
 ];
+/** Native browser projection, distinct from the issuer's persisted request state. */
+const CLIENT_AUTHORIZATION_PHASE = {
+	OTP_REQUIRED: "otp_required",
+	REVIEW: "review",
+	PROCESSING: "processing",
+	CONNECTED: "connected",
+	REFUSED: "refused"
+};
+CLIENT_AUTHORIZATION_PHASE.OTP_REQUIRED, CLIENT_AUTHORIZATION_PHASE.REVIEW, CLIENT_AUTHORIZATION_PHASE.PROCESSING, CLIENT_AUTHORIZATION_PHASE.CONNECTED, CLIENT_AUTHORIZATION_PHASE.REFUSED;
+/** Closed native refusals; existing Capxul error codes retain their own meaning. */
+const CLIENT_AUTHORIZATION_REFUSALS = [
+	"signup_required",
+	"setup_required",
+	"already_signed_up",
+	"identity_mismatch",
+	"invalid_request",
+	"request_expired",
+	"request_denied",
+	"cancelled",
+	"grant_revoked",
+	"grant_expired",
+	"refresh_reused",
+	"revoke_unconfirmed"
+];
 //#endregion
 //#region ../../packages/wire/src/financial-ops.ts
 const MINOR_UNIT_STRING_RE = /^[0-9]+$/;
@@ -9241,6 +9360,251 @@ function isSafeField(field, value) {
 	return value.length > 0 && value.length <= rule.maxLength && value === value.trim() && !value.includes("://") && !containsSensitiveMaterial(value) && rule.pattern.test(value);
 }
 //#endregion
+//#region ../../packages/wire/src/client-authorization.ts
+const NATIVE_CLIENT_ID = "capxul-cli";
+const NATIVE_CLIENT_SCOPE = "account:read";
+const NATIVE_CLIENT_LIMITS = {
+	accessMs: 36e5,
+	renewalMs: 2592e6,
+	absoluteMs: 7776e6,
+	requestMs: 6e5,
+	pollSeconds: 5,
+	imageBytes: 5242880
+};
+const strict = { parseOptions: { onExcessProperty: "error" } };
+const text$2 = (max) => Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(max));
+const nonNegativeInt = Schema.Number.check(Schema.makeFilter((n) => Number.isSafeInteger(n) && n >= 0));
+const normalize = (f) => Schema.String.pipe(Schema.decodeTo(Schema.String, {
+	decode: SchemaGetter.transform(f),
+	encode: SchemaGetter.transform((s) => s)
+}));
+const ClientRequestIdSchema = Schema.String.pipe(Schema.refine((s) => CLIENT_REQUEST_ID_RE.test(s)));
+const ClientGrantIdSchema = Schema.String.pipe(Schema.refine((s) => CLIENT_GRANT_ID_RE.test(s)));
+const authUserId = Schema.String.pipe(Schema.refine((s) => s.length > 0));
+const keyId = Schema.String.pipe(Schema.refine((s) => s.length > 0));
+const email = normalize((s) => s.toLowerCase()).pipe(Schema.refine((s) => EMAIL_RE$1.test(s))).check(Schema.isMaxLength(254));
+const handle = Schema.String.pipe(Schema.refine((s) => HANDLE_RE$1.test(s)));
+const country = normalize((s) => s.toUpperCase()).pipe(Schema.refine((s) => COUNTRY_CODE_RE.test(s)));
+const credential = Schema.RedactedFromValue(Schema.String.check(Schema.isMinLength(32), Schema.isMaxLength(8192), Schema.isPattern(/^[A-Za-z0-9._~-]+$/u)), { label: "native authorization credential" });
+const otp = Schema.RedactedFromValue(Schema.String.check(Schema.isPattern(/^[0-9]{6}$/u)), { label: "OTP" });
+const scopes = Schema.Tuple([Schema.Literal(NATIVE_CLIENT_SCOPE)]);
+/** Exact HTTPS origin, no credentials/path/query and no retired cloud deployment. */
+const NativeHttpsOriginSchema = Schema.String.check(Schema.makeFilter((value) => {
+	try {
+		const url = new URL(value);
+		const host = url.hostname.toLowerCase().replace(/\.$/u, "");
+		return url.protocol === "https:" && value === url.origin && !url.username && !url.password && !url.search && !url.hash && host !== "convex.cloud" && !host.endsWith(".convex.cloud") && host !== "convex.site" && !host.endsWith(".convex.site");
+	} catch {
+		return false;
+	}
+}, { message: "must be a canonical credential-free HTTPS origin outside retired Convex cloud hosts" }));
+const NativeClientConfigurationSchema = Schema.Struct({
+	clientId: Schema.Literal(NATIVE_CLIENT_ID),
+	applicationId: AppIdSchema,
+	keyId,
+	environment: Schema.Literals([
+		"development",
+		"staging",
+		"production"
+	]),
+	keyEnvironment: Schema.Literals(["test", "live"]),
+	issuer: NativeHttpsOriginSchema,
+	verificationOrigin: NativeHttpsOriginSchema
+}).annotate(strict).check(Schema.makeFilter((c) => c.keyEnvironment === (c.environment === "production" ? "live" : "test"), { message: "key environment must match the configured deployment" })).annotate(strict);
+const NativeSignupProfileSchema = Schema.Struct({
+	displayName: normalize((s) => s.trim()).check(Schema.isMinLength(1), Schema.isMaxLength(200)),
+	country,
+	handle,
+	payoutAddresses: Schema.optional(Schema.Array(Schema.Struct({
+		chain: Schema.Literals([
+			"evm",
+			"solana",
+			"starknet"
+		]),
+		address: text$2(256)
+	}).annotate(strict)).check(Schema.isMaxLength(10))),
+	image: Schema.optional(Schema.Struct({
+		mediaType: Schema.Literals([
+			"image/jpeg",
+			"image/png",
+			"image/webp"
+		]),
+		byteLength: Schema.Number.check(Schema.isInt(), Schema.isBetween({
+			minimum: 1,
+			maximum: NATIVE_CLIENT_LIMITS.imageBytes
+		})),
+		sha256: Schema.String.check(Schema.isPattern(/^[0-9a-f]{64}$/u))
+	}).annotate(strict))
+}).annotate(strict);
+const ClientAuthorizationIntentSchema = Schema.Union([Schema.Struct({ mode: Schema.Literal("login") }).annotate(strict), Schema.Struct({
+	mode: Schema.Literal("signup"),
+	profile: NativeSignupProfileSchema
+}).annotate(strict)]).annotate(strict);
+Schema.Struct({
+	clientId: Schema.Literal(NATIVE_CLIENT_ID),
+	email,
+	intent: ClientAuthorizationIntentSchema,
+	waitMs: Schema.Number.check(Schema.isInt(), Schema.isBetween({
+		minimum: 1,
+		maximum: NATIVE_CLIENT_LIMITS.requestMs
+	})),
+	continuityToken: Schema.optional(credential)
+}).annotate(strict);
+const request = {
+	requestId: ClientRequestIdSchema,
+	revision: nonNegativeInt,
+	expiresAt: EpochMsSchema
+};
+const principal = {
+	authUserId,
+	email
+};
+const profileSummary = {
+	displayName: text$2(200),
+	handle,
+	country
+};
+Schema.Union([
+	Schema.Struct({
+		...request,
+		phase: Schema.Literal(CLIENT_AUTHORIZATION_PHASE.OTP_REQUIRED),
+		email,
+		resendAt: EpochMsSchema
+	}).annotate(strict),
+	Schema.Struct({
+		...request,
+		phase: Schema.Literal(CLIENT_AUTHORIZATION_PHASE.REVIEW),
+		...principal,
+		clientLabel: Schema.Literal("Capxul CLI"),
+		scopes,
+		intent: ClientAuthorizationIntentSchema,
+		setupState: Schema.Literals([
+			"not_required",
+			"new",
+			"resumable"
+		])
+	}).annotate(strict).check(Schema.makeFilter((v) => v.intent.mode === "login" === (v.setupState === "not_required"), { message: "login review cannot permit account setup" })),
+	Schema.Struct({
+		...request,
+		phase: Schema.Literal(CLIENT_AUTHORIZATION_PHASE.PROCESSING),
+		...principal,
+		purpose: Schema.Literals(["login", "signup"]),
+		step: Schema.Literals([
+			"profile",
+			"wallet",
+			"account",
+			"delivery"
+		])
+	}).annotate(strict).check(Schema.makeFilter((v) => v.purpose === "signup" || v.step === "delivery", { message: "login may wait for delivery but cannot enter signup processing" })),
+	Schema.Struct({
+		...request,
+		phase: Schema.Literal(CLIENT_AUTHORIZATION_PHASE.CONNECTED),
+		...principal,
+		...profileSummary,
+		accountId: AccountIdSchema,
+		grantId: ClientGrantIdSchema
+	}).annotate(strict),
+	Schema.Struct({
+		...request,
+		phase: Schema.Literal(CLIENT_AUTHORIZATION_PHASE.REFUSED),
+		reason: Schema.Literals(CLIENT_AUTHORIZATION_REFUSALS),
+		code: Schema.Literals(CAPXUL_ERROR_CODES),
+		field: Schema.optional(Schema.Literals([
+			"email",
+			"displayName",
+			"country",
+			"handle",
+			"image",
+			"payoutAddresses"
+		])),
+		retryable: Schema.Boolean
+	}).annotate(strict)
+]).annotate(strict);
+Schema.Struct({
+	requestId: ClientRequestIdSchema,
+	revision: nonNegativeInt
+}).annotate(strict);
+Schema.Struct({
+	requestId: ClientRequestIdSchema,
+	code: otp
+}).annotate(strict);
+Schema.Struct({
+	client_id: Schema.Literal(NATIVE_CLIENT_ID),
+	grant_type: Schema.Literal("refresh_token"),
+	refresh_token: credential,
+	refreshAttemptId: Schema.RedactedFromValue(Schema.String.check(Schema.isPattern(/^[A-Za-z0-9_-]{32,128}$/u)), { label: "refresh attempt" })
+}).annotate(strict);
+Schema.Struct({
+	client_id: Schema.Literal(NATIVE_CLIENT_ID),
+	applicationId: AppIdSchema,
+	resource: text$2(2048),
+	token_type: Schema.Literal("Bearer"),
+	access_token: credential,
+	refresh_token: credential,
+	scope: Schema.Literal(NATIVE_CLIENT_SCOPE),
+	expires_in: Schema.Number.check(Schema.isInt(), Schema.isBetween({
+		minimum: 1,
+		maximum: NATIVE_CLIENT_LIMITS.accessMs / 1e3
+	})),
+	grantId: ClientGrantIdSchema,
+	...principal,
+	accountId: AccountIdSchema,
+	issuedAt: EpochMsSchema,
+	grantCreatedAt: EpochMsSchema,
+	accessExpiresAt: EpochMsSchema,
+	renewalExpiresAt: EpochMsSchema,
+	absoluteExpiresAt: EpochMsSchema,
+	revision: nonNegativeInt
+}).annotate(strict).check(Schema.makeFilter((t) => t.grantCreatedAt <= t.issuedAt && t.absoluteExpiresAt - t.grantCreatedAt === NATIVE_CLIENT_LIMITS.absoluteMs && t.renewalExpiresAt <= Math.min(t.issuedAt + NATIVE_CLIENT_LIMITS.renewalMs, t.absoluteExpiresAt) && t.accessExpiresAt <= Math.min(t.issuedAt + NATIVE_CLIENT_LIMITS.accessMs, t.renewalExpiresAt) && t.expires_in === Math.floor((t.accessExpiresAt - t.issuedAt) / 1e3), { message: "native credentials must obey the approved access, renewal and absolute deadlines" })).annotate(strict);
+/** One endpoint mapping; consumers cannot substitute callback or resource URLs. */
+function nativeClientEndpoints(config) {
+	const resource = `${config.issuer}/api/auth/native`;
+	return {
+		resource,
+		device_authorization_endpoint: `${resource}/device/code`,
+		token_endpoint: `${resource}/token`,
+		revocation_endpoint: `${resource}/revoke`,
+		session_endpoint: `${resource}/session`,
+		verification_uri: `${config.verificationOrigin}/connect`
+	};
+}
+Schema.Struct({
+	protocol: Schema.Literal("capxul.client-authorization"),
+	version: Schema.Literal(1),
+	configuration: NativeClientConfigurationSchema,
+	scopes_supported: scopes,
+	grant_types_supported: Schema.Tuple([Schema.Literal("urn:ietf:params:oauth:grant-type:device_code"), Schema.Literal("refresh_token")]),
+	resource: text$2(2048),
+	device_authorization_endpoint: text$2(2048),
+	token_endpoint: text$2(2048),
+	revocation_endpoint: text$2(2048),
+	session_endpoint: text$2(2048),
+	verification_uri: text$2(2048)
+}).annotate(strict).check(Schema.makeFilter((m) => {
+	const expected = nativeClientEndpoints(m.configuration);
+	return m.resource === expected.resource && m.device_authorization_endpoint === expected.device_authorization_endpoint && m.token_endpoint === expected.token_endpoint && m.revocation_endpoint === expected.revocation_endpoint && m.session_endpoint === expected.session_endpoint && m.verification_uri === expected.verification_uri;
+}, { message: "native endpoints must match their configured issuer and verification origin" })).annotate(strict);
+Schema.Struct({
+	client_id: Schema.Literal(NATIVE_CLIENT_ID),
+	grant_type: Schema.Literal("urn:ietf:params:oauth:grant-type:device_code"),
+	device_code: credential
+}).annotate(strict);
+Schema.Struct({
+	requestId: ClientRequestIdSchema,
+	device_code: credential,
+	user_code: Schema.RedactedFromValue(Schema.String.check(Schema.isPattern(/^[A-Z0-9]{4}-[A-Z0-9]{4}$/u)), { label: "device user code" }),
+	continuityToken: credential,
+	verification_uri: text$2(2048),
+	expires_in: Schema.Number.check(Schema.isInt(), Schema.isBetween({
+		minimum: 1,
+		maximum: NATIVE_CLIENT_LIMITS.requestMs / 1e3
+	})),
+	interval: Schema.Number.check(Schema.isInt(), Schema.isBetween({
+		minimum: NATIVE_CLIENT_LIMITS.pollSeconds,
+		maximum: NATIVE_CLIENT_LIMITS.requestMs / 1e3
+	}))
+}).annotate(strict);
+//#endregion
 //#region ../../packages/sdk/src/internal/invocation-observation.ts
 const INVOCATION_OBSERVATION = Symbol("capxul.invocation-observation");
 const FAILURE_INVOCATION_SNAPSHOT = Symbol("capxul.failure-invocation-snapshot");
@@ -11693,7 +12057,7 @@ function subscribeActivity(deps, actor, controls, onChange) {
 }
 //#endregion
 //#region ../../packages/sdk/package.json
-var version$1 = "4.20.0-beta.2";
+var version$1 = "4.20.0-beta.4";
 //#endregion
 //#region ../../packages/sdk/src/telemetry/exception-projection.ts
 /** Fixed fallback for failures that have no safe message. */
@@ -13753,6 +14117,381 @@ async function recoverRawDigestSigner(input) {
 	}
 }
 //#endregion
+//#region ../../packages/observability/src/engineering-delivery.ts
+/** Fixed admission limits for one CLI invocation and its SDK client. */
+const CLI_ENGINEERING_LIMITS = Object.freeze({
+	records: 80,
+	ordinaryRecords: 64,
+	recordBytes: 16384,
+	requests: 5,
+	ordinaryRequests: 2,
+	requestBytes: 1572864,
+	metricSeries: 16,
+	requestTimeoutMs: 1e3
+});
+const metricNames = /* @__PURE__ */ new Set(["capxul.cli.command.count", "capxul.cli.command.duration"]);
+const metricValues = {
+	command: CLI_COMMAND_NAMES,
+	capability: CLI_CAPABILITIES,
+	invocation_kind: CLI_INVOCATION_KINDS,
+	outcome: [
+		"succeeded",
+		"refused",
+		"failed",
+		"cancelled"
+	],
+	capxul_env: [
+		"development",
+		"staging",
+		"production",
+		"local"
+	],
+	unit: [
+		"1",
+		"s",
+		"ms"
+	]
+};
+/** Only this bounded registry is supplied to the CLI's metric producers. */
+var CliMetricRegistry = class extends Map {
+	dropped;
+	enabled;
+	constructor(dropped, enabled = true) {
+		super();
+		this.dropped = dropped;
+		this.enabled = enabled;
+	}
+	set(key, entry) {
+		if (!this.enabled || !metricNames.has(entry.id) || !this.has(key) && this.size >= CLI_ENGINEERING_LIMITS.metricSeries) {
+			this.dropped();
+			return this;
+		}
+		const labels = Object.entries(entry.attributes ?? {});
+		const state = entry.hooks.get(Context.empty());
+		const buckets = typeof state === "object" && state !== null && "buckets" in state ? state.buckets : void 0;
+		if (!["Counter", "Histogram"].includes(entry.type) || (entry.description?.length ?? 0) > 128 || labels.length > 6 || labels.some(([name, value]) => !metricValues[name]?.includes(String(value))) || entry.type === "Histogram" && (!Array.isArray(buckets) || buckets.length > 32)) {
+			this.dropped();
+			return this;
+		}
+		return super.set(key, entry);
+	}
+};
+/** Shared, closure-owned admission state; no queue or mutable counters are exposed. */
+function makeCliEngineeringBudget() {
+	let records = 0, peakRecords = 0, activeRequests = 0, requestBytes = 0;
+	let peakRequests = 0, peakRequestBytes = 0, dropped = 0;
+	const drop = () => {
+		dropped += 1;
+	};
+	const metricRegistry = new CliMetricRegistry(drop);
+	return Object.freeze({
+		metricRegistry,
+		emptyMetricRegistry: () => new CliMetricRegistry(drop, false),
+		drop,
+		admitRecord(terminal) {
+			if (records >= (terminal ? CLI_ENGINEERING_LIMITS.records : CLI_ENGINEERING_LIMITS.ordinaryRecords)) {
+				drop();
+				return;
+			}
+			records += 1;
+			peakRecords = Math.max(peakRecords, records);
+			let released = false;
+			return () => {
+				if (!released) {
+					released = true;
+					records -= 1;
+				}
+			};
+		},
+		admitRequest(bytes, terminal) {
+			if (bytes > CLI_ENGINEERING_LIMITS.requestBytes || activeRequests >= (terminal ? CLI_ENGINEERING_LIMITS.requests : CLI_ENGINEERING_LIMITS.ordinaryRequests)) {
+				drop();
+				return;
+			}
+			activeRequests += 1;
+			requestBytes += bytes;
+			peakRequests = Math.max(peakRequests, activeRequests);
+			peakRequestBytes = Math.max(peakRequestBytes, requestBytes);
+			return () => {
+				activeRequests -= 1;
+				requestBytes -= bytes;
+			};
+		},
+		snapshot() {
+			return {
+				records,
+				reservedRecordBytes: records * CLI_ENGINEERING_LIMITS.recordBytes,
+				peakRecords,
+				peakReservedRecordBytes: peakRecords * CLI_ENGINEERING_LIMITS.recordBytes,
+				activeRequests,
+				requestBytes,
+				peakRequests,
+				peakRequestBytes,
+				dropped,
+				metricSeries: metricRegistry.size
+			};
+		}
+	});
+}
+const text$1 = (value) => typeof value === "string" ? value.slice(0, 128) : "capxul.engineering";
+const attributes = (input, limit = 32) => {
+	const out = {};
+	let count = 0;
+	let bytes = 0;
+	try {
+		for (const key in input) {
+			if (count++ >= limit) break;
+			if (key.length > 64) continue;
+			const value = Object.getOwnPropertyDescriptor(input, key)?.value;
+			const scalar = typeof value === "string" ? value.slice(0, 128) : typeof value === "boolean" || typeof value === "number" && Number.isFinite(value) ? value : void 0;
+			if (scalar === void 0) continue;
+			bytes += new TextEncoder().encode(JSON.stringify([key, scalar])).length;
+			if (bytes > (limit >= 24 ? 2e3 : 300)) break;
+			out[key] = scalar;
+		}
+	} catch {}
+	return out;
+};
+const terminalName = (name) => name === "cli.command.completed" || CLI_COMMAND_NAMES.some((command) => name === `cli.command.${command}`);
+/** Native exporters retain their serialization and scheduling; this owns admission only. */
+function cliEngineeringDelivery(budget, ownsMetrics) {
+	const closed = Deferred.makeUnsafe();
+	let isClosed = false;
+	let metricsRunning = false;
+	const logs = [];
+	const spans = /* @__PURE__ */ new Map();
+	const terminalBodies = /* @__PURE__ */ new WeakSet();
+	const bodyLeases = /* @__PURE__ */ new WeakMap();
+	const pendingBodies = /* @__PURE__ */ new Set();
+	const holdBody = (body, releases) => {
+		if (releases.length === 0) return;
+		const lease = {
+			started: false,
+			release: () => {
+				if (!pendingBodies.delete(lease)) return;
+				bodyLeases.delete(body);
+				for (const release of releases) release();
+			}
+		};
+		bodyLeases.set(body, lease);
+		pendingBodies.add(lease);
+	};
+	const discardBody = (body) => bodyLeases.get(body)?.release();
+	const drainLogs = () => {
+		for (const release of logs.splice(0)) release();
+	};
+	const close = () => {
+		isClosed = true;
+		Deferred.doneUnsafe(closed, Effect.void);
+		for (const lease of pendingBodies) if (!lease.started) lease.release();
+		drainLogs();
+		for (const release of spans.values()) release();
+		spans.clear();
+		if (ownsMetrics) budget.metricRegistry.clear();
+	};
+	return {
+		close,
+		discardBody,
+		metrics(run) {
+			return Effect.suspend(() => {
+				if (isClosed || metricsRunning) return Effect.void;
+				metricsRunning = true;
+				return run.pipe(Effect.ensuring(Effect.sync(() => {
+					metricsRunning = false;
+				})));
+			});
+		},
+		logger(delegate) {
+			return Logger.make((options) => {
+				if (isClosed) return;
+				let release;
+				try {
+					const message = text$1(Array.isArray(options.message) ? Object.getOwnPropertyDescriptor(options.message, "0")?.value : options.message);
+					release = budget.admitRecord(terminalName(message));
+					if (release === void 0) return;
+					const context = Context.add(options.fiber.context, References.CurrentLogAnnotations, attributes(options.fiber.getRef(References.CurrentLogAnnotations)));
+					const fiber = Object.create(options.fiber);
+					Object.defineProperty(fiber, "getRef", { value: (ref) => Context.get(context, ref) });
+					logs.push(release);
+					delegate.log({
+						...options,
+						message,
+						cause: Cause.empty,
+						fiber
+					});
+				} catch {
+					if (release !== void 0) {
+						const index = logs.indexOf(release);
+						if (index !== -1) logs.splice(index, 1);
+						release();
+					}
+					budget.drop();
+				}
+			});
+		},
+		tracer(delegate) {
+			return Tracer.make({
+				span(options) {
+					const name = text$1(options.name);
+					const release = isClosed ? void 0 : budget.admitRecord(terminalName(name));
+					const spanOptions = {
+						...options,
+						name,
+						annotations: Context.empty(),
+						links: []
+					};
+					const span = release === void 0 ? new Tracer.NativeSpan({
+						...spanOptions,
+						sampled: false
+					}) : delegate.span(spanOptions);
+					if (release !== void 0) spans.set(span.spanId, release);
+					const wrapped = Object.create(span);
+					let fields = 0, events = 0, links = 0, attributeBytes = 0;
+					let ended = false;
+					Object.defineProperties(wrapped, {
+						attribute: { value: (key, value) => {
+							if (fields >= 32 && !span.attributes.has(key)) {
+								budget.drop();
+								return;
+							}
+							const safe = attributes({ [key]: value }, 1);
+							if (!Object.hasOwn(safe, key)) return;
+							const previous = span.attributes.has(key) ? new TextEncoder().encode(JSON.stringify([key, span.attributes.get(key)])).length : 0;
+							const next = new TextEncoder().encode(JSON.stringify([key, safe[key]])).length;
+							if (attributeBytes - previous + next > 2e3) {
+								budget.drop();
+								return;
+							}
+							attributeBytes += next - previous;
+							if (!span.attributes.has(key)) fields += 1;
+							span.attribute(key, safe[key]);
+						} },
+						event: { value: (eventName, time, attrs) => {
+							if (events++ >= 2) {
+								budget.drop();
+								return;
+							}
+							span.event(text$1(eventName), time, attributes(attrs ?? {}, 4));
+						} },
+						addLinks: { value: (items) => {
+							for (const item of items.slice(0, Math.max(0, 2 - links))) {
+								if (!/^[a-f0-9]{32}$/u.test(item.span.traceId) || !/^[a-f0-9]{16}$/u.test(item.span.spanId)) {
+									budget.drop();
+									continue;
+								}
+								span.addLinks([{
+									span: Tracer.externalSpan({
+										traceId: item.span.traceId,
+										spanId: item.span.spanId,
+										sampled: item.span.sampled
+									}),
+									attributes: attributes(item.attributes, 4)
+								}]);
+								links += 1;
+							}
+						} },
+						end: { value: (time, exit) => {
+							if (ended) return;
+							ended = true;
+							span.end(time, Exit.isFailure(exit) ? Exit.fail("CLI operation failed") : Exit.void);
+						} }
+					});
+					wrapped.addLinks(options.links ?? []);
+					return wrapped;
+				},
+				...delegate.context === void 0 ? {} : { context: delegate.context.bind(delegate) }
+			});
+		},
+		serialization(delegate) {
+			return {
+				logs(data) {
+					const releases = logs.splice(0);
+					try {
+						const body = delegate.logs(data);
+						if (data.resourceLogs.some((r) => r.scopeLogs.some((s) => s.logRecords?.some((l) => l.body?.stringValue === "cli.command.completed")))) terminalBodies.add(body);
+						holdBody(body, releases);
+						return body;
+					} catch (error) {
+						for (const release of releases) release();
+						throw error;
+					}
+				},
+				traces(data) {
+					const releases = [];
+					for (const resource of data.resourceSpans) for (const scope of resource.scopeSpans) for (const span of scope.spans) {
+						const release = spans.get(span.spanId);
+						if (release !== void 0) releases.push(release);
+						spans.delete(span.spanId);
+					}
+					try {
+						const body = delegate.traces(data);
+						if (data.resourceSpans.some((r) => r.scopeSpans.some((s) => s.spans.some((span) => terminalName(span.name))))) terminalBodies.add(body);
+						holdBody(body, releases);
+						return body;
+					} catch (error) {
+						for (const release of releases) release();
+						throw error;
+					}
+				},
+				metrics(data) {
+					const body = delegate.metrics(data);
+					terminalBodies.add(body);
+					return body;
+				}
+			};
+		},
+		transport(client, enabled = () => true) {
+			const retrying = HttpClient.transform(client, (response, request) => Effect.suspend(() => {
+				if (enabled()) return response;
+				budget.drop();
+				return Effect.succeed(HttpClientResponse.fromWeb(request, new Response(null)));
+			})).pipe(HttpClient.transformResponse((response) => Effect.tap(response, (result) => {
+				let received = 0;
+				return Stream.runForEach(result.stream, (chunk) => Effect.sync(() => {
+					received += chunk.byteLength;
+					if (received > 65536) throw new Error("Engineering response limit exceeded");
+				})).pipe(Effect.catchTag("HttpClientError", (error) => error.reason._tag === "EmptyBodyError" ? Effect.void : Effect.fail(error)));
+			}))).pipe(HttpClient.filterStatusOk, HttpClient.retryTransient({
+				times: 1,
+				schedule: Schedule.spaced("100 millis").pipe(Schedule.addDelay(({ input }) => Effect.map(Clock.currentTimeMillis, (now) => {
+					if (!HttpClientError.isHttpClientError(input) || input.reason._tag !== "StatusCodeError" || input.reason.response.status !== 429) return Duration.zero;
+					const header = input.reason.response.headers["retry-after"];
+					const numeric = Number(header);
+					const delay = header === void 0 ? 2e3 : Number.isFinite(numeric) ? numeric * 1e3 : Date.parse(header) - now;
+					return Duration.millis(Number.isFinite(delay) ? Math.min(2e3, Math.max(0, delay)) : 2e3);
+				})))
+			}));
+			return HttpClient.transform(retrying, (response, request) => Effect.suspend(() => {
+				if (isClosed) {
+					discardBody(request.body);
+					return Effect.succeed(HttpClientResponse.fromWeb(request, new Response(null)));
+				}
+				const droppedResponse = () => HttpClientResponse.fromWeb(request, new Response(null, { status: 200 }));
+				if (request.body._tag === "Empty") {
+					discardBody(request.body);
+					return Effect.succeed(droppedResponse());
+				}
+				const bytes = request.body.contentLength;
+				const release = budget.admitRequest(bytes ?? Number.POSITIVE_INFINITY, terminalBodies.has(request.body));
+				if (release === void 0) {
+					discardBody(request.body);
+					return Effect.succeed(droppedResponse());
+				}
+				const lease = bodyLeases.get(request.body);
+				if (lease !== void 0) lease.started = true;
+				return response.pipe(Effect.asVoid, Effect.timeoutOption(CLI_ENGINEERING_LIMITS.requestTimeoutMs), Effect.raceFirst(Deferred.await(closed).pipe(Effect.andThen(Effect.interrupt))), Effect.tap((result) => Effect.sync(() => {
+					if (Option.isNone(result)) budget.drop();
+				})), Effect.catchCause(() => Effect.sync(() => {
+					budget.drop();
+				})), Effect.as(droppedResponse()), Effect.ensuring(Effect.sync(() => {
+					release();
+					discardBody(request.body);
+				})));
+			}));
+		}
+	};
+}
+//#endregion
 //#region ../../packages/observability/src/engineering.ts
 const ENGINEERING_CAPXUL_ENVS = [
 	"development",
@@ -13927,10 +14666,13 @@ const MINIMAL_NUMBERS = /* @__PURE__ */ new Set([
 const MINIMAL_CORRELATIONS = /* @__PURE__ */ new Set([
 	"correlation_id",
 	"journey_id",
-	"invocation_id"
+	"invocation_id",
+	"posthogDistinctId"
 ]);
 const MINIMAL_METRIC_LABELS = /* @__PURE__ */ new Set([
 	"command",
+	"capability",
+	"invocation_kind",
 	"outcome",
 	"capxul_env",
 	"unit"
@@ -13938,7 +14680,7 @@ const MINIMAL_METRIC_LABELS = /* @__PURE__ */ new Set([
 const MINIMAL_METRIC_NAMES = /* @__PURE__ */ new Set(["capxul.cli.command.count", "capxul.cli.command.duration"]);
 const traceId = (value) => typeof value === "string" && /^(?!0+$)[0-9a-f]{32}$/u.test(value);
 const spanId = (value) => typeof value === "string" && /^(?!0+$)[0-9a-f]{16}$/u.test(value);
-const minimalName = (value) => typeof value === "string" && (MINIMAL_LOG_NAMES.has(value) || isCapxulOperation(value)) ? value : "capxul.engineering";
+const minimalName = (value) => typeof value === "string" && (MINIMAL_LOG_NAMES.has(value) || isCapxulOperation(value) || CLI_COMMAND_NAMES.some((command) => value === `cli.command.${command}`)) ? value : "capxul.engineering";
 const MINIMAL_ENUM_VALUES = /* @__PURE__ */ new Map([
 	["outcome", [
 		"succeeded",
@@ -13951,7 +14693,10 @@ const MINIMAL_ENUM_VALUES = /* @__PURE__ */ new Map([
 	["failure_mode", FAILURE_MODES$1],
 	["capxul_env", ENGINEERING_CAPXUL_ENVS],
 	["producer", ["browser", "server"]],
-	["command", ["doctor"]],
+	["command", CLI_COMMAND_NAMES],
+	["capability", CLI_CAPABILITIES],
+	["invocation_kind", CLI_INVOCATION_KINDS],
+	["cli_identity_kind", ["anonymous"]],
 	["output_mode", ["human", "json"]],
 	["unit", [
 		"1",
@@ -14169,10 +14914,17 @@ function minimalSerialization(config) {
 }
 /** Attempt to drain all engineering signals; completion does not prove ingestion. */
 const flushEngineeringTelemetry = Effect.flatMap(OtlpExporter.Flusher, (flusher) => flusher.flush);
+var EngineeringLog = class extends Context.Service()("capxul/EngineeringLog") {};
+/** Deliver an owned engineering record without changing the caller's console verbosity. */
+const logEngineeringInfo = (message, attributes) => {
+	const record = Effect.logInfo(message).pipe(Effect.annotateLogs(attributes));
+	return Effect.flatMap(LogLevel.isEnabled("Info"), (visible) => visible ? record : Effect.flatMap(EngineeringLog, (logger) => record.pipe(Effect.provideService(Logger.CurrentLoggers, /* @__PURE__ */ new Set([logger])), Effect.provideService(References.MinimumLogLevel, "All"))));
+};
 /** Shared browser/server OTLP layer. OtlpLogger merges with incumbent loggers once. */
 const makeEngineeringTelemetryLayer = (config) => {
 	const validated = validateEngineeringTelemetryConfig(config);
 	return Layer.suspend(() => {
+		const bounded = validated.deliveryBudget === void 0 ? void 0 : cliEngineeringDelivery(validated.deliveryBudget, validated.serviceName === "capxul-cli");
 		const endpoints = postHogOtlpEndpoints(validated.host);
 		let disabled = false;
 		const enabled = () => {
@@ -14186,7 +14938,12 @@ const makeEngineeringTelemetryLayer = (config) => {
 		};
 		const delivery = {
 			...validated.shutdownTimeout === void 0 ? {} : { shutdownTimeout: validated.shutdownTimeout },
-			...validated.exportInterval === void 0 ? {} : { exportInterval: validated.exportInterval }
+			...validated.exportInterval === void 0 ? {} : { exportInterval: validated.exportInterval },
+			...bounded === void 0 ? {} : {
+				maxBatchSize: Number.MAX_SAFE_INTEGER,
+				exportInterval: 1e3,
+				shutdownTimeout: validated.serviceName === "capxul-cli" ? 0 : 500
+			}
 		};
 		const resource = {
 			serviceName: validated.serviceName ?? "capxul-sdk",
@@ -14202,22 +14959,38 @@ const makeEngineeringTelemetryLayer = (config) => {
 			headers: validated.headers,
 			resource,
 			...delivery
-		}).pipe(Effect.map((tracer) => makeLeakSafeEngineeringTracer(tracer, enabled)))).pipe(Layer.provideMerge(OtlpExporter.layerFlusher));
-		const logging = Logger.layer([OtlpLogger.make({
+		}).pipe(Effect.map((tracer) => makeLeakSafeEngineeringTracer(bounded?.tracer(tracer) ?? tracer, enabled)))).pipe(Layer.provideMerge(OtlpExporter.layerFlusher));
+		const ownedLogging = Layer.effect(EngineeringLog, OtlpLogger.make({
 			url: endpoints.logs,
 			headers: validated.headers,
 			resource,
-			...delivery
-		}).pipe(Effect.map((logger) => Logger.make((options) => {
-			if (enabled()) logger.log(options);
-		})))], { mergeWithExisting: true }).pipe(Layer.provideMerge(OtlpExporter.layerFlusher));
-		const metrics = OtlpMetrics.layer({
+			...delivery,
+			...bounded === void 0 ? {} : { excludeLogSpans: true }
+		}).pipe(Effect.map((nativeLogger) => {
+			const logger = bounded?.logger(nativeLogger) ?? nativeLogger;
+			return Logger.make((options) => {
+				if (enabled()) logger.log(options);
+			});
+		}))).pipe(Layer.provideMerge(OtlpExporter.layerFlusher));
+		const logging = Logger.layer([EngineeringLog], { mergeWithExisting: true }).pipe(Layer.provideMerge(ownedLogging));
+		const metricConfig = {
 			url: endpoints.metrics,
 			headers: validated.headers,
 			resource,
 			temporality: "delta",
 			...delivery
-		});
+		};
+		const metrics = bounded === void 0 ? OtlpMetrics.layer(metricConfig) : validated.serviceName !== "capxul-cli" ? Layer.empty : Layer.effectDiscard(Effect.gen(function* () {
+			const flusher = yield* OtlpExporter.Flusher;
+			yield* OtlpMetrics.make({
+				...metricConfig,
+				exportInterval: Number.POSITIVE_INFINITY,
+				shutdownTimeout: 0
+			}).pipe(Effect.provideService(OtlpExporter.Flusher, {
+				...flusher,
+				register: (run) => flusher.register(bounded.metrics(run))
+			}));
+		})).pipe(Layer.provideMerge(OtlpExporter.layerFlusher));
 		const headerPolicy = Layer.merge(Layer.succeed(HttpClient.TracerHeaderFilter, traceHeaderFilter), Layer.succeed(Headers.CurrentRedactedNames, [credentialHeaderPattern]));
 		const browserLifecycle = Layer.effectDiscard(Effect.gen(function* () {
 			if (validated.producer !== "browser" || !hasBrowserDocument()) return;
@@ -14240,17 +15013,25 @@ const makeEngineeringTelemetryLayer = (config) => {
 			}));
 		}));
 		const transport = Layer.effect(HttpClient.HttpClient, Effect.map(HttpClient.HttpClient, (client) => {
-			const selectedTransport = validated.producer === "browser" && hasBrowserDocument() ? browserExportClient(client) : client;
-			return HttpClient.transform(selectedTransport, (response, request) => Effect.suspend(() => enabled() && request.body._tag !== "Empty" ? response : Effect.succeed(HttpClientResponse.fromWeb(request, new Response(null, { status: 200 })))));
+			const originalTransport = validated.producer === "browser" && hasBrowserDocument() ? browserExportClient(client) : client;
+			const selectedTransport = bounded?.transport(originalTransport, enabled) ?? originalTransport;
+			return HttpClient.transform(selectedTransport, (response, request) => Effect.suspend(() => {
+				if (enabled() && request.body._tag !== "Empty") return response;
+				bounded?.discardBody(request.body);
+				return Effect.succeed(HttpClientResponse.fromWeb(request, new Response(null, { status: 200 })));
+			}));
 		})).pipe(Layer.provide(FetchHttpClient.layer));
 		const serialization = Layer.effect(OtlpSerialization.OtlpSerialization, Effect.map(OtlpSerialization.OtlpSerialization, (json) => {
 			const projected = minimalSerialization(validated);
-			return validated.privacy === "minimal" ? projected : {
+			const selected = validated.privacy === "minimal" ? projected : {
 				...json,
 				metrics: projected.metrics
 			};
+			return bounded?.serialization(selected) ?? selected;
 		})).pipe(Layer.provide(OtlpSerialization.layerJson));
-		return browserLifecycle.pipe(Layer.provideMerge(Layer.mergeAll(tracing, logging, metrics, headerPolicy)), Layer.provide(serialization), Layer.provide(transport));
+		const combined = browserLifecycle.pipe(Layer.provideMerge(Layer.mergeAll(tracing, logging, metrics, headerPolicy)), Layer.provide(serialization), Layer.provide(transport));
+		const scoped = bounded === void 0 ? combined : combined.pipe(Layer.provideMerge(Layer.effectDiscard(Effect.addFinalizer(() => Effect.sync(bounded.close)))));
+		return validated.deliveryBudget === void 0 ? scoped : scoped.pipe(Layer.provideMerge(Layer.succeed(Metric.MetricRegistry, validated.serviceName === "capxul-cli" ? validated.deliveryBudget.metricRegistry : validated.deliveryBudget.emptyMetricRegistry())));
 	});
 };
 //#endregion
@@ -47769,6 +48550,7 @@ function postHogObservability(client, options = {}) {
 		product: postHogProductTelemetry(policy)
 	};
 	Object.defineProperty(module, HOST_ENGINEERING_POLICY, { value: Object.freeze({
+		...options.engineeringDeliveryBudget === void 0 ? {} : { engineeringDeliveryBudget: options.engineeringDeliveryBudget },
 		...options.engineeringEnabled === void 0 ? {} : { engineeringEnabled: options.engineeringEnabled },
 		...options.engineeringPrivacy === void 0 ? {} : { engineeringPrivacy: options.engineeringPrivacy }
 	}) });
@@ -47806,6 +48588,7 @@ function isPromiseLike(value) {
 function hostEngineeringPolicy(observability) {
 	const policy = observability?.[HOST_ENGINEERING_POLICY];
 	return {
+		...policy?.engineeringDeliveryBudget === void 0 ? {} : { deliveryBudget: policy.engineeringDeliveryBudget },
 		...policy?.engineeringEnabled === void 0 ? {} : { enabled: policy.engineeringEnabled },
 		...policy?.engineeringPrivacy === void 0 ? {} : { privacy: policy.engineeringPrivacy }
 	};
@@ -49020,6 +49803,82 @@ function captureException(telemetry, error, context) {
 	}).pipe(Effect.flatten), () => Effect.void);
 }
 //#endregion
+//#region src/platform/observation-identity.ts
+const uuid = Schema.String.check(Schema.isPattern(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u));
+const person = Schema.String.check(Schema.isPattern(/^[^\s]{1,256}$/u));
+const binding = Schema.Struct({
+	authUserId: person,
+	eventId: uuid
+});
+const epoch = Schema.Struct({
+	id: uuid,
+	binding: Schema.NullOr(binding)
+});
+const ObservationIdentity = Schema.Struct({
+	version: Schema.Literal(1),
+	firstUse: Schema.Struct({
+		eventId: uuid,
+		observedAt: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))
+	}),
+	epoch
+});
+const ObservationIdentityChange = Schema.Union([
+	Schema.Struct({ kind: Schema.Literal("acquire") }),
+	Schema.Struct({
+		kind: Schema.Literal("bind"),
+		expectedEpoch: uuid,
+		authUserId: person
+	}),
+	Schema.Struct({
+		kind: Schema.Literal("rotate"),
+		expectedEpoch: uuid
+	})
+]);
+/** Observation bookkeeping only. The caller must obtain verified person facts from AUTH. */
+function transitionObservationIdentity(previous, change, fresh) {
+	if (change.kind !== "acquire" && previous?.epoch.id !== change.expectedEpoch) return {
+		state: previous,
+		result: { status: "stale" }
+	};
+	let state = previous ?? {
+		version: 1,
+		firstUse: {
+			eventId: fresh.eventId,
+			observedAt: fresh.observedAt
+		},
+		epoch: {
+			id: fresh.epochId,
+			binding: null
+		}
+	};
+	if (change.kind === "rotate" || change.kind === "acquire" && state.epoch.binding !== null) state = {
+		...state,
+		epoch: {
+			id: fresh.epochId,
+			binding: null
+		}
+	};
+	else if (change.kind === "bind" && state.epoch.binding?.authUserId !== change.authUserId) state = {
+		...state,
+		epoch: {
+			id: state.epoch.binding === null ? state.epoch.id : fresh.epochId,
+			binding: {
+				authUserId: change.authUserId,
+				eventId: fresh.eventId
+			}
+		}
+	};
+	return {
+		state,
+		result: {
+			status: "ready",
+			firstUse: state.firstUse,
+			firstUseClaimed: previous === null,
+			epoch: state.epoch
+		}
+	};
+}
+//#endregion
 //#region src/platform/state-files.ts
 const Settings = Schema.Struct({
 	version: Schema.Literal(1),
@@ -49163,11 +50022,12 @@ const withLock = (file, body) => Effect.scoped(Effect.gen(function* () {
 	}));
 	return yield* body(path.join(lock, `${owner}.data`));
 }));
-const replace = (file, content, validate) => Effect.gen(function* () {
+const replace = (file, update) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
-	if (new TextEncoder().encode(content).length > 65536) return yield* Effect.fail(fail("Corrupt"));
 	return yield* withLock(file, (temporary) => Effect.gen(function* () {
-		yield* validate;
+		const { content, value } = yield* update;
+		if (content === null) return value;
+		if (new TextEncoder().encode(content).length > 65536) return yield* Effect.fail(fail("Corrupt"));
 		const handle = yield* fs.open(temporary, {
 			flag: "wx",
 			mode: 384
@@ -49179,6 +50039,7 @@ const replace = (file, content, validate) => Effect.gen(function* () {
 			const path = yield* Path.Path;
 			yield* (yield* fs.open(path.dirname(file))).sync;
 		}));
+		return value;
 	}));
 });
 const setCollectionEnabled = (file, enabled) => Effect.gen(function* () {
@@ -49187,9 +50048,33 @@ const setCollectionEnabled = (file, enabled) => Effect.gen(function* () {
 		version: 1,
 		collection: { enabled }
 	};
-	yield* replace(location, JSON.stringify(settings), readSettings(location));
+	yield* replace(location, readSettings(location).pipe(Effect.as({
+		content: JSON.stringify(settings),
+		value: void 0
+	})));
 	return settings;
 }).pipe(Effect.mapError(storageError));
+const changeObservationIdentity = (directory, input) => Effect.gen(function* () {
+	const change = yield* Schema.decodeUnknownEffect(ObservationIdentityChange, { onExcessProperty: "error" })(input).pipe(Effect.mapError(() => fail("Corrupt")));
+	const path = yield* Path.Path;
+	const location = yield* locate(path.join(directory, "observation.json"), true);
+	return yield* replace(location, Effect.gen(function* () {
+		const content = yield* readFile(location);
+		const previous = content === null ? null : yield* Schema.decodeUnknownEffect(Schema.fromJsonString(ObservationIdentity), { onExcessProperty: "error" })(content).pipe(Effect.mapError(() => fail("Corrupt")));
+		const crypto = yield* Crypto.Crypto;
+		const next = transitionObservationIdentity(previous, change, {
+			epochId: yield* crypto.randomUUIDv4,
+			eventId: yield* crypto.randomUUIDv4,
+			observedAt: yield* Clock.currentTimeMillis
+		});
+		return {
+			content: next.state === previous ? null : JSON.stringify(next.state),
+			value: next.result
+		};
+	}));
+}).pipe(Effect.mapError(storageError));
+/** Call only for eligible collection. This never infers AUTH identity from stored state. */
+const acquireObservationIdentity = (directory) => changeObservationIdentity(directory, { kind: "acquire" });
 //#endregion
 //#region src/platform/collection-policy.ts
 const decode = Schema.decodeUnknownOption(Schema.fromJsonString(Settings), { onExcessProperty: "error" });
@@ -49299,6 +50184,8 @@ function parsedCommand(cause) {
 }
 //#endregion
 //#region src/runtime/config.ts
+const defaultHost = "https://us.i.posthog.com";
+const defaultProjectToken = Redacted.make("phc_BZuAVofrkNXzwpJkuDG7Rdfurir45fj2dudQvJZk847e");
 const optionalText = (name) => Config.option(Config.string(name));
 function httpOrigin(value, field) {
 	return Effect.try({
@@ -49312,14 +50199,12 @@ function httpOrigin(value, field) {
 		catch: () => configurationFailure(`The ${field} URL must be a valid approved origin.`)
 	});
 }
-const loadConfig = Effect.gen(function* () {
+const loadObservationConfig = Effect.gen(function* () {
 	const path = yield* Path.Path;
 	const values = yield* Config.all({
 		cliHome: optionalText("CAPXUL_CLI_HOME"),
 		home: optionalText("HOME"),
 		xdg: optionalText("XDG_CONFIG_HOME"),
-		key: Config.option(Config.redacted("CAPXUL_PUBLISHABLE_KEY")),
-		bootstrap: Config.string("CAPXUL_BOOTSTRAP_URL").pipe(Config.withDefault("https://api.staging.capxul.com")),
 		host: optionalText("CAPXUL_POSTHOG_HOST"),
 		token: Config.option(Config.redacted("CAPXUL_POSTHOG_PROJECT_TOKEN")),
 		disabled: Config.boolean("CAPXUL_TELEMETRY_DISABLED").pipe(Config.withDefault(false))
@@ -49333,19 +50218,29 @@ const loadConfig = Effect.gen(function* () {
 		else return yield* Effect.fail(configurationFailure("Set HOME or CAPXUL_CLI_HOME."));
 	}
 	const settingsPath = path.join(path.resolve(directory), "settings.json");
-	const bootstrapBaseUrl = yield* httpOrigin(values.bootstrap, "bootstrap");
-	const posthogHost = Option.isSome(values.host) ? yield* httpOrigin(values.host.value, "PostHog") : void 0;
+	const host = Option.getOrUndefined(values.host) ?? defaultHost;
 	return {
 		settingsPath,
-		publishableKey: Option.getOrUndefined(values.key),
-		bootstrapBaseUrl,
 		environment: "staging",
-		posthogHost,
-		projectToken: Option.getOrUndefined(values.token),
+		posthogHost: host === void 0 ? void 0 : yield* httpOrigin(host, "PostHog"),
+		projectToken: Option.getOrUndefined(values.token) ?? defaultProjectToken,
 		forcedDisabled: values.disabled,
 		collectionEnabled: collectionPolicy(settingsPath, values.disabled)
 	};
 });
+const loadConfig = Effect.gen(function* () {
+	const observation = yield* loadObservationConfig;
+	const values = yield* Config.all({
+		key: Config.option(Config.redacted("CAPXUL_PUBLISHABLE_KEY")),
+		bootstrap: Config.string("CAPXUL_BOOTSTRAP_URL").pipe(Config.withDefault("https://api.staging.capxul.com"))
+	}).pipe(Effect.mapError(() => configurationFailure("CLI environment configuration is invalid.")));
+	const bootstrapBaseUrl = yield* httpOrigin(values.bootstrap, "bootstrap");
+	return {
+		...observation,
+		bootstrapBaseUrl,
+		publishableKey: Option.getOrUndefined(values.key)
+	};
+});
 const collectionStatus = (config) => Effect.gen(function* () {
 	const stored = (yield* readSettings(config.settingsPath))?.collection.enabled ?? null;
 	const enabled = config.collectionEnabled();
@@ -49369,33 +50264,13 @@ const codes = [
 ];
 const identifier = Schema.String.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u));
 const version = Schema.String.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._+-]{0,127}$/u));
-const outcomeSchema = Schema.Literals([
-	"succeeded",
-	"refused",
-	"failed",
-	"cancelled"
-]);
 const completionSchema = Schema.Struct({
-	schema_version: Schema.Literal(1),
-	command: Schema.Literal("doctor"),
-	invocation_id: identifier,
+	...CliCommandCompletedTelemetryEventSchema.fields.props.fields,
 	correlation_id: identifier,
 	journey_id: identifier,
-	capxul_env: Schema.Literals([
-		"development",
-		"staging",
-		"production",
-		"local"
-	]),
-	producer: Schema.Literal("server"),
-	cli_version: version,
-	sdk_version: version,
-	outcome: outcomeSchema,
-	duration_ms: Schema.Number,
+	posthogDistinctId: Schema.optional(identifier),
 	wait_duration_ms: Schema.Number,
-	retry_count: Schema.Literal(0),
-	output_mode: Schema.Literals(["human", "json"]),
-	error_code: Schema.optional(Schema.Literals(codes))
+	retry_count: Schema.Literal(0)
 });
 const CAPTURE_CAPACITY = 32;
 const CAPTURE_BYTES = 8192;
@@ -49409,13 +50284,15 @@ const own = (value, key) => {
 		return;
 	}
 };
-const inactiveHost = () => postHogObservability(null, {
+const inactiveHost = (budget) => postHogObservability(null, {
 	enabled: false,
-	engineeringEnabled: false
+	engineeringEnabled: false,
+	engineeringDeliveryBudget: budget
 });
 /** One invocation owns its records, metric registry, callback queue, and total flush deadline. */
 function observeInvocation(input, work) {
 	return Effect.suspend(() => {
+		const deliveryBudget = makeCliEngineeringBudget();
 		const finalizers = [];
 		const onFinalize = (finalizer) => {
 			finalizers.push(finalizer);
@@ -49424,7 +50301,7 @@ function observeInvocation(input, work) {
 			concurrency: "unbounded",
 			discard: true
 		}));
-		const inactiveWork = Effect.acquireUseRelease(Effect.void, () => Effect.suspend(() => work(inactiveHost(), onFinalize)), () => finalize.pipe(Effect.interruptible, Effect.timeoutOption("2 seconds"), Effect.asVoid));
+		const inactiveWork = Effect.acquireUseRelease(Effect.void, () => Effect.suspend(() => work(inactiveHost(deliveryBudget), onFinalize)), () => finalize.pipe(Effect.interruptible, Effect.timeoutOption("2 seconds"), Effect.asVoid));
 		let disabled = false;
 		const enabled = () => {
 			if (disabled) return false;
@@ -49435,12 +50312,13 @@ function observeInvocation(input, work) {
 			}
 			return !disabled;
 		};
-		if (input.host === void 0 || input.projectToken === void 0 || !enabled()) return inactiveWork;
+		if (input.kind === "completion" || input.kind === "collection_control" || input.host === void 0 || input.projectToken === void 0 || !enabled()) return inactiveWork;
 		const host = input.host;
 		const token = Redacted.value(input.projectToken);
 		let engineering;
 		try {
 			Schema.decodeUnknownSync(identifier)(input.invocationId);
+			if (input.anonymousIdentity !== void 0) Schema.decodeUnknownSync(identifier)(input.anonymousIdentity.id);
 			Schema.decodeUnknownSync(version)(input.cliVersion);
 			engineering = makeEngineeringTelemetryLayer({
 				host,
@@ -49449,6 +50327,7 @@ function observeInvocation(input, work) {
 				producer: "server",
 				sdkVersion: input.sdkVersion,
 				serviceName: "capxul-cli",
+				deliveryBudget,
 				enabled,
 				shutdownTimeout: 0,
 				exportInterval: "1 hour"
@@ -49456,7 +50335,7 @@ function observeInvocation(input, work) {
 		} catch {
 			return inactiveWork;
 		}
-		const layer = Layer.merge(engineering, FetchHttpClient.layer).pipe(Layer.provideMerge(Layer.succeed(Metric.MetricRegistry, /* @__PURE__ */ new Map())), Layer.provideMerge(Layer.succeed(Logger.LogToStderr, true)));
+		const layer = Layer.merge(engineering, FetchHttpClient.layer).pipe(Layer.provideMerge(Layer.succeed(Logger.LogToStderr, true)));
 		return Effect.scoped(Effect.gen(function* () {
 			const built = yield* Effect.exit(Layer.build(layer));
 			if (Exit.isFailure(built)) return yield* inactiveWork;
@@ -49472,30 +50351,47 @@ function observeInvocation(input, work) {
 					producer: "server",
 					cli_version: input.cliVersion,
 					sdk_version: input.sdkVersion,
+					schema_version: 1,
+					command: input.command,
+					capability: input.capability,
+					invocation_kind: input.kind,
+					release: input.cliVersion,
+					platform: input.platform ?? "unknown",
+					architecture: input.architecture ?? "unknown",
+					ci: input.ci ?? false,
+					tty: input.tty ?? false,
+					output_mode: input.outputMode ?? "human",
+					...input.anonymousIdentity === void 0 ? {} : {
+						anonymous_id: input.anonymousIdentity.id,
+						cli_identity_kind: "anonymous"
+					},
 					invocation_id: input.invocationId,
 					correlation_id: input.invocationId,
 					journey_id: input.invocationId
 				};
-				const capture = (event, properties) => {
+				const capture = (event, properties, identity) => {
 					if (!enabled()) {
 						dropped += 1;
 						return;
 					}
+					const occurredAt = identity?.observedAt ?? clock.currentTimeMillisUnsafe();
 					const record = sanitizePostHogBrowserEvent({
 						event,
 						properties: {
 							...properties,
 							...envelope,
+							occurred_at: occurredAt,
 							...nativeContext
 						}
 					});
 					const body = JSON.stringify({
 						api_key: token,
 						...record,
-						uuid: crypto.randomUUID(),
+						uuid: identity?.eventId ?? crypto.randomUUID(),
+						timestamp: new Date(occurredAt).toISOString(),
 						properties: {
 							...record.properties,
-							distinct_id: input.invocationId,
+							distinct_id: input.anonymousIdentity?.id ?? input.invocationId,
 							$process_person_profile: false
 						}
 					});
@@ -49528,9 +50424,40 @@ function observeInvocation(input, work) {
 							...envelope
 						}
 					});
-					if (Option.isSome(decoded) && Queue.sizeUnsafe(queue) < 30) capture(event, { ...decoded.value.props });
+					if (Option.isSome(decoded) && Queue.sizeUnsafe(queue) < 29) capture(event, { ...decoded.value.props });
 					else dropped += 1;
 				} };
+				const clientHttp = HttpClient.transform(yield* HttpClient.HttpClient, (response, request) => Effect.suspend(() => {
+					if (enabled()) return response;
+					dropped += 1;
+					return Effect.succeed(HttpClientResponse.fromWeb(request, new Response(null)));
+				})).pipe(HttpClient.filterStatusOk, HttpClient.retryTransient({
+					times: 1,
+					schedule: Schedule.spaced("100 millis")
+				}));
+				const flushCaptures = Effect.gen(function* () {
+					const pending = yield* Queue.clear(queue);
+					if (!enabled()) {
+						dropped += pending.length;
+						return;
+					}
+					pendingCaptures += pending.length;
+					yield* Effect.forEach(pending, (item) => Effect.suspend(() => {
+						if (!enabled()) {
+							dropped += 1;
+							return Effect.void;
+						}
+						return clientHttp.execute(HttpClientRequest.post(`${host.replace(/\/+$/, "")}/capture/`).pipe(HttpClientRequest.bodyText(item, "application/json"))).pipe(Effect.asVoid, Effect.catchCause(() => Effect.sync(() => {
+							dropped += 1;
+						})));
+					}).pipe(Effect.ensuring(Effect.sync(() => {
+						pendingCaptures -= 1;
+					}))), {
+						concurrency: 4,
+						discard: true
+					});
+				}).pipe(Effect.withTracerEnabled(false), Effect.provideService(HttpClient.TracerPropagationEnabled, false));
+				let startDelivery;
 				let commandResult;
 				yield* Effect.gen(function* () {
 					const span = yield* Effect.currentSpan.pipe(Effect.orDie);
@@ -49543,15 +50470,39 @@ function observeInvocation(input, work) {
 						enabled,
 						engineeringEnabled: enabled,
 						engineeringPrivacy: "minimal",
+						engineeringDeliveryBudget: deliveryBudget,
 						capxulEnv: input.environment,
 						context: {
 							application: "capxul-cli",
+							...input.anonymousIdentity === void 0 ? {} : { anonymousId: input.anonymousIdentity.id },
 							release: input.cliVersion,
 							correlationId: input.invocationId,
 							journeyId: input.invocationId,
 							traceparent
 						}
 					});
+					const firstUse = input.anonymousIdentity?.firstUse;
+					if (firstUse !== void 0) {
+						const first = Schema.decodeUnknownSync(CliFirstUsedTelemetryEventSchema)({
+							name: "cli_first_used",
+							props: {
+								...envelope,
+								occurred_at: firstUse.observedAt
+							}
+						});
+						capture("cli_first_used", { ...first.props }, firstUse);
+					}
+					if (input.kind !== "parse_refusal") {
+						const start = Schema.decodeUnknownSync(CliCommandStartedTelemetryEventSchema)({
+							name: "cli_command_started",
+							props: {
+								...envelope,
+								occurred_at: clock.currentTimeMillisUnsafe()
+							}
+						});
+						capture("cli_command_started", { ...start.props });
+						startDelivery = yield* Effect.forkScoped(flushCaptures.pipe(Effect.interruptible), { startImmediately: true });
+					}
 					const waitStarted = clock.currentTimeMillisUnsafe();
 					const result = yield* Effect.exit(restore(Effect.suspend(() => work(observation, onFinalize))));
 					commandResult = result;
@@ -49564,8 +50515,12 @@ function observeInvocation(input, work) {
 						const duration = Math.max(0, clock.currentTimeMillisUnsafe() - started);
 						const completion = Schema.decodeUnknownSync(completionSchema)({
 							...envelope,
+							...input.anonymousIdentity === void 0 ? {} : { posthogDistinctId: input.anonymousIdentity.id },
+							occurred_at: clock.currentTimeMillisUnsafe(),
 							schema_version: 1,
 							command: input.command,
+							capability: input.capability,
+							invocation_kind: input.kind,
 							outcome,
 							duration_ms: duration,
 							wait_duration_ms: waitDuration,
@@ -49574,13 +50529,15 @@ function observeInvocation(input, work) {
 							...errorCode === void 0 ? {} : { error_code: errorCode }
 						});
 						yield* Effect.annotateCurrentSpan(completion);
-						yield* Effect.logInfo("cli.command.completed").pipe(Effect.annotateLogs(completion));
+						yield* logEngineeringInfo("cli.command.completed", completion);
 						for (const diagnostic of sdkDiagnostics) yield* Effect.logInfo("cli.sdk.operation.failed").pipe(Effect.annotateLogs({
 							...envelope,
 							...diagnostic
 						}));
 						const metricAttributes = {
 							command: input.command,
+							capability: input.capability,
+							invocation_kind: input.kind,
 							outcome,
 							capxul_env: input.environment
 						};
@@ -49600,15 +50557,27 @@ function observeInvocation(input, work) {
 								unit: "s"
 							}
 						}), duration / 1e3);
-						const event = {
-							name: "cli_diagnostic_completed",
+						const terminal = Schema.decodeUnknownSync(CliCommandCompletedTelemetryEventSchema)({
+							name: "cli_command_completed",
 							props: {
 								...envelope,
-								outcome
+								occurred_at: clock.currentTimeMillisUnsafe(),
+								outcome,
+								duration_ms: duration,
+								...errorCode === void 0 ? {} : { error_code: errorCode }
 							}
-						};
-						const decoded = Schema.decodeUnknownSync(CliDiagnosticCompletedTelemetryEventSchema)(event);
-						capture(event.name, { ...decoded.props });
+						});
+						capture("cli_command_completed", { ...terminal.props });
+						if (input.command === "doctor" && input.kind === "command" && input.network) {
+							const diagnostic = Schema.decodeUnknownSync(CliDiagnosticCompletedTelemetryEventSchema)({
+								name: "cli_diagnostic_completed",
+								props: {
+									...envelope,
+									outcome
+								}
+							});
+							capture("cli_diagnostic_completed", { ...diagnostic.props });
+						}
 						if (Exit.isFailure(result)) {
 							const defect = result.cause.reasons.find(Cause.isDieReason);
 							if (defect !== void 0) {
@@ -49619,7 +50588,7 @@ function observeInvocation(input, work) {
 									if (typeof stack === "string") error.stack = stack.slice(0, 8192);
 								} catch {}
 								yield* captureException({
-									emit: (exception) => Effect.sync(() => capture("$exception", projectException(exception.props))),
+									emit: (exception) => Effect.sync(() => capture("$exception", projectException(exception.props, input.command))),
 									identify: () => Effect.void,
 									group: () => Effect.void,
 									reset: () => Effect.void
@@ -49628,41 +50597,12 @@ function observeInvocation(input, work) {
 						}
 					}).pipe(Effect.catchCause(() => Effect.void));
 					if (Exit.isFailure(result)) return yield* Effect.fail("CLI command failed");
-				}).pipe(Effect.withSpan("cli.command.doctor"), Effect.exit);
-				const clientHttp = HttpClient.transform(yield* HttpClient.HttpClient, (response, request) => Effect.suspend(() => {
-					if (enabled()) return response;
-					dropped += 1;
-					return Effect.succeed(HttpClientResponse.fromWeb(request, new Response(null)));
-				})).pipe(HttpClient.filterStatusOk, HttpClient.retryTransient({
-					times: 1,
-					schedule: Schedule.spaced("100 millis")
-				}));
-				const flushCaptures = Effect.gen(function* () {
-					const pending = yield* Queue.clear(queue);
-					if (!enabled()) {
-						dropped += pending.length;
-						return;
-					}
-					pendingCaptures = pending.length;
-					yield* Effect.forEach(pending, (item) => Effect.suspend(() => {
-						if (!enabled()) {
-							dropped += 1;
-							return Effect.void;
-						}
-						return clientHttp.execute(HttpClientRequest.post(`${host.replace(/\/+$/, "")}/capture/`).pipe(HttpClientRequest.bodyText(item, "application/json"))).pipe(Effect.asVoid, Effect.catchCause(() => Effect.sync(() => {
-							dropped += 1;
-						})));
-					}).pipe(Effect.ensuring(Effect.sync(() => {
-						pendingCaptures -= 1;
-					}))), {
-						concurrency: 4,
-						discard: true
-					});
-				}).pipe(Effect.withTracerEnabled(false), Effect.provideService(HttpClient.TracerPropagationEnabled, false));
+				}).pipe(Effect.withSpan(`cli.command.${input.command}`), Effect.exit);
 				yield* Effect.all([
 					finalize,
 					flushCaptures,
-					flushEngineeringTelemetry
+					flushEngineeringTelemetry,
+					startDelivery === void 0 ? Effect.void : Fiber.join(startDelivery)
 				], {
 					concurrency: "unbounded",
 					discard: true
@@ -49672,6 +50612,7 @@ function observeInvocation(input, work) {
 				yield* Queue.shutdown(queue);
 				try {
 					input.onDropped?.(dropped);
+					input.onEngineeringDropped?.(deliveryBudget.snapshot().dropped);
 				} catch {}
 				if (commandResult === void 0) return yield* Effect.die("CLI observation could not start");
 				return yield* commandResult;
@@ -49706,7 +50647,7 @@ function projectSdkProperties(properties) {
 	if (failureMode !== void 0) output.failure_mode = failureMode;
 	return output;
 }
-function projectException(properties) {
+function projectException(properties, command) {
 	const sanitized = sanitizePostHogBrowserEvent({
 		event: "$exception",
 		properties: { ...properties }
@@ -49730,8 +50671,8 @@ function projectException(properties) {
 		$exception_type: "CLI_DEFECT",
 		$exception_message: "CLI command failed",
 		$exception_level: "error",
-		$exception_fingerprint: `cli.doctor.CLI_DEFECT:${frames[0]?.filename ?? "boundary"}:${frames[0]?.function ?? "unknown"}`,
-		$issue_name: "CLI doctor defect",
+		$exception_fingerprint: `cli.${command}.CLI_DEFECT:${frames[0]?.filename ?? "boundary"}:${frames[0]?.function ?? "unknown"}`,
+		$issue_name: `CLI ${command} defect`,
 		$exception_list: [{
 			type: "CLI_DEFECT",
 			value: "CLI command failed",
@@ -49757,41 +50698,101 @@ function renderResult(mode, envelope, lines = []) {
 }
 //#endregion
 //#region src/version.ts
-const cliVersion = "4.20.0-beta.2";
-const sdkVersion = "4.20.0-beta.2";
+const cliVersion = "4.20.0-beta.4";
+const sdkVersion = "4.20.0-beta.4";
+//#endregion
+//#region src/runtime/command-metadata.ts
+var CliCommandMetadata = class extends Context.Service()("capxul-cli/CommandMetadata") {};
+const collectionControl = (name) => name === "telemetry" || name === "telemetry.status" || name === "telemetry.enable" || name === "telemetry.disable";
+function metadataAtPath(root, path) {
+	let selected = root;
+	for (const part of path.slice(1)) {
+		const child = selected.subcommands.flatMap((group) => group.commands).find((command) => command.name === part || command.alias === part);
+		if (child === void 0) break;
+		selected = child;
+	}
+	const metadata = Context.getOption(selected.annotations, CliCommandMetadata);
+	return Option.isSome(metadata) && CLI_COMMAND_NAMES.includes(metadata.value.name) ? metadata.value : {
+		name: "unknown",
+		capability: "cli",
+		observation: "command"
+	};
+}
 //#endregion
 //#region src/runtime/run-command.ts
 var CliRuntime = class extends Context.Service()("capxul-cli/Runtime") {};
-const runCommand = (options, work) => Effect.gen(function* () {
-	const runtime = yield* CliRuntime;
-	const invocationId = yield* (yield* Crypto.Crypto).randomUUIDv4;
-	yield* Ref.set(runtime.current, {
-		command: options.name,
-		invocationId
-	});
-	const config = yield* loadConfig;
+const acquireInvocationIdentity = (config, eligible) => Effect.gen(function* () {
+	if (!eligible || config?.posthogHost === void 0 || config.projectToken === void 0 || !config.collectionEnabled()) return void 0;
+	const path = yield* Path.Path;
+	const acquired = yield* acquireObservationIdentity(path.dirname(config.settingsPath));
+	return acquired.status === "ready" ? acquired : void 0;
+}).pipe(Effect.catchCause(() => Effect.succeed(void 0)));
+const runInvocation = (runtime, metadata, kind, work, network = false) => Effect.gen(function* () {
+	const current = yield* Ref.get(runtime.current);
+	if (current !== null) return yield* work(current.host, current.onFinalize);
+	const invocationKind = kind === "completion" ? kind : collectionControl(metadata.name) ? "collection_control" : kind;
+	const silent = invocationKind === "completion" || invocationKind === "collection_control";
+	const invocation = {
+		command: metadata.name,
+		invocationId: runtime.invocationId,
+		kind
+	};
+	yield* Ref.set(runtime.current, invocation);
+	const config = runtime.observation;
+	const identity = yield* acquireInvocationIdentity(config, !silent);
 	let dropped = 0;
-	const result = options.network ? yield* observeInvocation({
-		command: "doctor",
-		invocationId,
+	let engineeringDropped = 0;
+	return yield* observeInvocation({
+		command: metadata.name,
+		capability: metadata.capability,
+		kind: invocationKind,
+		network,
+		invocationId: runtime.invocationId,
+		...identity === void 0 ? {} : { anonymousIdentity: {
+			id: identity.epoch.id,
+			...identity.firstUseClaimed ? { firstUse: identity.firstUse } : {}
+		} },
 		cliVersion,
 		sdkVersion,
-		environment: config.environment,
-		...config.posthogHost === void 0 ? {} : { host: config.posthogHost },
-		...config.projectToken === void 0 ? {} : { projectToken: config.projectToken },
-		enabled: config.collectionEnabled,
+		environment: config?.environment ?? "staging",
+		platform: runtime.platform === "darwin" || runtime.platform === "linux" ? runtime.platform : "unknown",
+		architecture: runtime.architecture === "arm64" || runtime.architecture === "x64" ? runtime.architecture : "unknown",
+		ci: runtime.ci,
+		tty: runtime.tty,
+		...!silent && config?.posthogHost !== void 0 ? { host: config.posthogHost } : {},
+		...!silent && config?.projectToken !== void 0 ? { projectToken: config.projectToken } : {},
+		enabled: identity === void 0 ? () => false : config?.collectionEnabled ?? (() => false),
 		outputMode: runtime.mode,
 		onDropped: (count) => {
 			dropped = count;
+		},
+		onEngineeringDropped: (count) => {
+			engineeringDropped = count;
 		}
-	}, (observation, onFinalize) => work(config, observation, onFinalize)).pipe(Effect.onExit(() => dropped > 0 ? writeStderr(`Telemetry dropped ${dropped} records.\n`) : Effect.void)) : yield* work(config);
-	yield* renderResult(runtime.mode, {
-		version: 1,
-		command: options.name,
-		invocationId,
-		outcome: "succeeded",
-		data: result.data
-	}, result.lines);
+	}, (host, onFinalize) => Effect.gen(function* () {
+		yield* Ref.set(runtime.current, {
+			...invocation,
+			host,
+			onFinalize
+		});
+		return yield* work(host, onFinalize);
+	})).pipe(Effect.onExit(() => {
+		const notice = (dropped > 0 ? `Telemetry dropped ${dropped} records.\n` : "") + (engineeringDropped > 0 ? `Engineering telemetry dropped ${engineeringDropped} items.\n` : "");
+		return notice === "" ? Effect.void : writeStderr(notice).pipe(Effect.catchCause(() => Effect.void));
+	}));
+});
+const runCommand = (options, work) => Effect.gen(function* () {
+	const runtime = yield* CliRuntime;
+	return yield* runInvocation(runtime, options, "command", (host, onFinalize) => Effect.gen(function* () {
+		const result = yield* work(yield* loadConfig, host, onFinalize);
+		yield* renderResult(runtime.mode, {
+			version: 1,
+			command: options.name,
+			invocationId: runtime.invocationId,
+			outcome: "succeeded",
+			data: result.data
+		}, result.lines);
+	}), options.network);
 });
 //#endregion
 //#region src/platform/capxul.ts
@@ -49875,42 +50876,63 @@ const checkDoctor = (config, options) => Effect.gen(function* () {
 });
 //#endregion
 //#region src/commands/doctor.ts
+const metadata = {
+	name: "doctor",
+	capability: "diagnostics",
+	observation: "command"
+};
 const doctor = Command.make("doctor", {
 	online: Flag.boolean("online").pipe(Flag.withDefault(false), Flag.withDescription("Also check the backend through the public SDK")),
 	timeoutMs: Flag.integer("timeout-ms").pipe(Flag.filter((value) => value >= 1 && value <= 3e5, () => "Use --timeout-ms between 1 and 300000."), Flag.withDefault(3e4), Flag.withDescription("Online check deadline in milliseconds (1 to 300000)"))
 }, ({ online, timeoutMs }) => runCommand({
-	name: "doctor",
+	...metadata,
 	network: online
 }, (config, observation, onFinalize) => checkDoctor(config, {
 	online,
 	timeoutMs,
 	...observation === void 0 ? {} : { observation },
 	...onFinalize === void 0 ? {} : { onFinalize }
-}))).pipe(Command.withDescription("Check local configuration; --online also checks the backend"));
+}))).pipe(Command.annotate(CliCommandMetadata, metadata), Command.withDescription("Check local configuration; --online also checks the backend"));
 //#endregion
 //#region src/commands/telemetry.ts
+const statusMetadata = {
+	name: "telemetry.status",
+	capability: "collection",
+	observation: "collection-control"
+};
+const enableMetadata = {
+	...statusMetadata,
+	name: "telemetry.enable"
+};
+const disableMetadata = {
+	...statusMetadata,
+	name: "telemetry.disable"
+};
 const report = (config) => collectionStatus(config).pipe(Effect.map((status) => ({
 	data: status,
 	lines: [
 		`Remote CLI observation ${status.enabled ? "enabled" : "disabled"}.`,
 		...status.configured ? [] : ["Remote delivery is not configured."],
 		...config.forcedDisabled ? ["CAPXUL_TELEMETRY_DISABLED overrides the saved preference."] : [],
-		"Local commands send nothing. Use capxul telemetry disable to opt out."
+		"Commands collect usage and diagnostics. Collection controls and completions send nothing."
 	]
 })));
 const status = Command.make("status", {}, () => runCommand({
-	name: "telemetry.status",
+	...statusMetadata,
 	network: false
-}, report));
+}, report)).pipe(Command.annotate(CliCommandMetadata, statusMetadata));
 const enable = Command.make("enable", {}, () => runCommand({
-	name: "telemetry.enable",
+	...enableMetadata,
 	network: false
-}, (config) => setCollectionEnabled(config.settingsPath, true).pipe(Effect.andThen(report(config)))));
+}, (config) => setCollectionEnabled(config.settingsPath, true).pipe(Effect.andThen(report(config))))).pipe(Command.annotate(CliCommandMetadata, enableMetadata));
 const disable = Command.make("disable", {}, () => runCommand({
-	name: "telemetry.disable",
+	...disableMetadata,
 	network: false
-}, (config) => setCollectionEnabled(config.settingsPath, false).pipe(Effect.andThen(report(config)))));
-const telemetry = Command.make("telemetry").pipe(Command.withDescription("Show or change this CLI's collection preference"), Command.withSubcommands([
+}, (config) => setCollectionEnabled(config.settingsPath, false).pipe(Effect.andThen(report(config))))).pipe(Command.annotate(CliCommandMetadata, disableMetadata));
+const telemetry = Command.make("telemetry").pipe(Command.annotate(CliCommandMetadata, {
+	...statusMetadata,
+	name: "telemetry"
+}), Command.withDescription("Show or change this CLI's collection preference"), Command.withSubcommands([
 	status,
 	enable,
 	disable
@@ -49940,52 +50962,87 @@ const outputMode = (args) => Effect.gen(function* () {
 });
 //#endregion
 //#region src/command.ts
-const command = Command.make("capxul").pipe(Command.withDescription("Capxul diagnostics and configuration"), Command.withSubcommands([doctor, telemetry]), Command.withGlobalFlags([JsonOutput]));
+const command = Command.make("capxul").pipe(Command.annotate(CliCommandMetadata, {
+	name: "capxul",
+	capability: "cli",
+	observation: "command"
+}), Command.withDescription("Capxul diagnostics and configuration"), Command.withSubcommands([doctor, telemetry]), Command.withGlobalFlags([JsonOutput]));
 //#endregion
 //#region src/runtime/entry.ts
+const completionFailure = (error) => {
+	if (!CliError.isCliError(error)) return false;
+	if (error._tag === "ShowHelp") return error.errors.some(completionFailure);
+	return (error._tag === "InvalidValue" || error._tag === "MissingOption" || error._tag === "DuplicateOption") && (error.option === "completions" || error.option === "--completions");
+};
 const runCli = (platform) => Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
 	const stdio = yield* Stdio.Stdio;
+	const stateServices = yield* Effect.context().pipe(Effect.map(Context.pick(Crypto.Crypto, FileSystem.FileSystem, Path.Path)));
 	const args = yield* stdio.args;
 	const mode = yield* outputMode(args);
 	const interactive = yield* stdio.stdinIsTerminal;
 	const cliConfig = yield* CliConfig.CliConfig;
 	const current = yield* Ref.make(null);
+	const invocationId = yield* (yield* Crypto.Crypto).randomUUIDv4;
+	const observation = yield* loadObservationConfig.pipe(Effect.catch(() => Effect.succeed(void 0)));
+	const ci = yield* Config.string("CI").pipe(Config.withDefault("false"), Effect.map((value) => value !== "" && value !== "false" && value !== "0"), Effect.catch(() => Effect.succeed(false)));
+	const runtime = {
+		mode,
+		current,
+		invocationId,
+		observation,
+		...platform,
+		architecture: arch,
+		ci,
+		tty: interactive
+	};
 	const nativeConsole = yield* Console.Console;
 	const output = [];
 	const capture = (...values) => {
 		output.push(values.map(String).join(" "));
 	};
+	const flushNative = Effect.suspend(() => {
+		if (output.length === 0) return Effect.void;
+		const text = output.splice(0).join("\n");
+		return mode === "json" ? renderResult(mode, {
+			version: 1,
+			command: "capxul",
+			invocationId: null,
+			outcome: "succeeded",
+			data: { text }
+		}) : writeStdout(`${text}\n`);
+	});
+	const decorate = (flag, kind) => GlobalFlag.action({
+		flag: flag.flag,
+		run: (value, context) => runInvocation(runtime, metadataAtPath(context.command, context.commandPath), kind, () => flag.run(value, context).pipe(Effect.andThen(flushNative))).pipe(Effect.provide(stateServices), Effect.provideService(Stdio.Stdio, stdio), Effect.orDie)
+	});
+	const builtIns = cliConfig.builtIns.filter((flag) => interactive && !ci && mode === "human" || flag !== GlobalFlag.Wizard).map((flag) => flag === GlobalFlag.Help ? decorate(GlobalFlag.Help, "help") : flag === GlobalFlag.Version ? decorate(GlobalFlag.Version, "version") : flag === GlobalFlag.Completions ? decorate(GlobalFlag.Completions, "completion") : flag);
 	const exit = yield* restore(Command.runWith(command, {
 		version: cliVersion,
 		renderErrors: false
-	})(args).pipe(Effect.provideService(CliRuntime, {
-		mode,
-		current,
-		...platform
-	}), Effect.provideService(CliConfig.CliConfig, { builtIns: interactive && mode === "human" ? cliConfig.builtIns : cliConfig.builtIns.filter((flag) => flag !== GlobalFlag.Wizard) }), Effect.provideService(Console.Console, {
+	})(args).pipe(Effect.provideService(CliRuntime, runtime), Effect.provideService(CliConfig.CliConfig, { builtIns }), Effect.provideService(Console.Console, {
 		...nativeConsole,
 		log: capture,
 		info: capture
 	}))).pipe(Effect.exit);
 	if (Exit.isSuccess(exit)) {
-		if (output.length > 0) {
-			if (mode === "json") yield* renderResult(mode, {
-				version: 1,
-				command: "capxul",
-				invocationId: null,
-				outcome: "succeeded",
-				data: { text: output.join("\n") }
-			});
-			else yield* writeStdout(`${output.join("\n")}\n`);
-		}
+		if ((yield* Ref.get(current)) === null && output.length > 0) yield* runInvocation(runtime, metadataAtPath(command, [command.name]), "help", () => flushNative);
+		else yield* flushNative;
 		return 0;
 	}
+	const error = Cause.squash(exit.cause);
+	if ((yield* Ref.get(current)) === null) {
+		const path = CliError.isCliError(error) && error._tag === "ShowHelp" ? error.commandPath : [];
+		if (path.length > 0) {
+			const metadata = metadataAtPath(command, path);
+			if (metadata.name !== "unknown") yield* runInvocation(runtime, metadata, completionFailure(error) ? "completion" : "parse_refusal", () => Effect.failCause(exit.cause)).pipe(Effect.exit);
+		}
+	}
 	const invocation = yield* Ref.get(current);
 	const failure = classifyFailure(exit.cause);
 	yield* renderResult(mode, {
 		version: 1,
-		command: invocation?.command ?? parsedCommand(exit.cause),
-		invocationId: invocation?.invocationId ?? null,
+		command: invocation?.kind === "parse_refusal" || invocation?.kind === "completion" || invocation?.kind === "collection_control" ? parsedCommand(exit.cause) : invocation?.command ?? parsedCommand(exit.cause),
+		invocationId: invocation?.kind === "command" ? invocation.invocationId : null,
 		outcome: failure.outcome,
 		error: {
 			code: failure.code,