From 22e883d13b2713ee597dfae7d9b581aad8ed9be4 Mon Sep 17 00:00:00 2001
From: Nathan Flurry <git@nathanflurry.com>
Date: Wed, 1 Jul 2026 17:03:03 -0700
Subject: [PATCH] feat(core): opt-in high-resolution guest clock option + bench
 harness use

---
 packages/core/src/agent-os.ts       | 12 ++++++++++++
 packages/core/src/options-schema.ts |  1 +
 scripts/benchmarks/run-all.ts       |  4 ++++
 3 files changed, 17 insertions(+)

diff --git a/packages/core/src/agent-os.ts b/packages/core/src/agent-os.ts
index 0d4d1cb603..d5d35417ee 100644
--- a/packages/core/src/agent-os.ts
+++ b/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 }
 										: {}),
diff --git a/packages/core/src/options-schema.ts b/packages/core/src/options-schema.ts
index 3600da3b38..0bdd4a3f64 100644
--- a/packages/core/src/options-schema.ts
+++ b/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(),
diff --git a/scripts/benchmarks/run-all.ts b/scripts/benchmarks/run-all.ts
index 2d8ac4f6a5..2b9bf7a3ab 100644
--- a/scripts/benchmarks/run-all.ts
+++ b/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[] = [];