feat(core): opt-in high-resolution guest clock option + bench harness use

packages/core/src/agent-os.ts

@@ -595,6 +595,14 @@ export interface AgentOsOptions {
 	 * Defaults to the hardened builtin set used by the native sidecar bridge.
 	 */
 	allowedNodeBuiltins?: string[];
+	/**
+	 * Opt in to a high-resolution monotonic guest clock (microsecond class)
+	 * for guest Node processes. Default `false` keeps the security-oriented
+	 * 1ms timer resolution — untrusted guest code should not get a precise
+	 * timer (timing side channels). Enable only for trusted benchmarking or
+	 * profiling workloads.
+	 */
+	highResolutionTime?: boolean;
 	/** Root filesystem configuration. Defaults to an overlay with the bundled base snapshot as its deepest lower. */
 	rootFilesystem?: RootFilesystemConfig;
 	/** Filesystems to mount at boot time. */
@@ -2916,6 +2924,7 @@ export class AgentOs {
 					// emulation), matching the prior behavior where Agent OS only
 					// constrained the builtin allow-list.
 					...(options?.allowedNodeBuiltins !== undefined ||
+					options?.highResolutionTime !== undefined ||
 					snapshotUserlandCode !== undefined
 						? {
 								jsRuntime: {
@@ -2924,6 +2933,9 @@ export class AgentOs {
 									...(options?.allowedNodeBuiltins !== undefined
 										? { allowedBuiltins: options.allowedNodeBuiltins }
 										: {}),
+									...(options?.highResolutionTime !== undefined
+										? { highResolutionTime: options.highResolutionTime }
+										: {}),
 									...(snapshotUserlandCode !== undefined
 										? { snapshotUserlandCode }
 										: {}),

packages/core/src/options-schema.ts

@@ -270,6 +270,7 @@ export const agentOsOptionFieldSchemas = {
 	defaultSoftware: z.boolean().optional(),
 	loopbackExemptPorts: z.array(z.number().int().min(0).max(65535)).optional(),
 	allowedNodeBuiltins: stringArray.optional(),
+	highResolutionTime: z.boolean().optional(),
 	rootFilesystem: rootFilesystemConfigSchema.optional(),
 	mounts: z.array(mountConfigSchema).optional(),
 	moduleAccessCwd: z.string().optional(),

scripts/benchmarks/run-all.ts

@@ -19,6 +19,10 @@ const FAMILY_FILTER = process.env.BENCH_FAMILIES
 export async function runLatencyMatrix(): Promise<OpResult[]> {
 	const vm = await AgentOs.create({
 		permissions: { fs: "allow", network: "allow", childProcess: "allow", process: "allow" },
+		// Benchmark VM: opt in to the µs-resolution guest clock so sub-ms guest
+		// samples are real instead of 1ms-floor artifacts. Never enable this for
+		// untrusted workloads (timing side channels) — off by default everywhere.
+		highResolutionTime: true,
 	});
 	try {
 		const results: OpResult[] = [];