@butlr/butlr-mcp-server 0.5.0 → 0.6.0

package/dist/tools/butlr-search-assets.js

@@ -1,11 +1,12 @@
 import { apolloClient } from "../clients/graphql-client.js";
 import { z } from "zod";
-import { GET_FULL_TOPOLOGY } from "../clients/queries/topology.js";
+import { GET_ALL_HIVES, GET_ALL_SENSORS, GET_FULL_TOPOLOGY } from "../clients/queries/topology.js";
 import { getCachedTopology, setCachedTopology, generateTopologyCacheKey, } from "../cache/topology-cache.js";
 import { flattenTopology } from "../utils/asset-flattener.js";
 import { searchAssets } from "../utils/fuzzy-match.js";
 import { buildAssetPath } from "../utils/path-builder.js";
-import { rethrowIfGraphQLError } from "../utils/graphql-helpers.js";
+import { isProductionHive, isProductionSensor, rethrowIfGraphQLError, throwIfGraphQLErrors, } from "../utils/graphql-helpers.js";
+import { mergeSensorsAndHivesIntoTopology } from "../utils/topology-merge.js";
 import { debug } from "../utils/debug.js";
 import { withToolErrorHandling } from "../errors/mcp-errors.js";
 const VALID_ASSET_TYPES = ["site", "building", "floor", "room", "zone", "sensor", "hive"];
@@ -85,15 +86,18 @@ export async function executeSearchAssets(args) {
     debug("search-assets", `Searching for "${args.query}"` +
         (args.asset_types ? ` in types: ${args.asset_types.join(",")}` : "") +
         ` (max: ${maxResults})`);
-    // Use a generic cache key for full topology (we'll search across it).
-    // `devicesMerged: false` because this tool intentionally caches the raw
-    // `sites` tree without running mergeSensorsAndHivesIntoTopology — flattening
-    // for fuzzy search doesn't need the per-floor sensors/hives arrays. The
-    // distinct cache key prevents `butlr_list_topology` from reading this
-    // device-incomplete shape and silently dropping device-level matches.
+    // `devicesMerged: true`: sensors and hives are merged onto their floors
+    // before flattening, because `flattenTopology` reads devices from
+    // `floor.sensors`/`floor.hives` and `GET_FULL_TOPOLOGY` selects neither.
+    // Without the merge this tool's corpus holds zero sensors and zero hives,
+    // while `VALID_ASSET_TYPES` advertises both and `butlr_hardware_snapshot`
+    // tells callers to find sensors here first.
+    //
+    // This is the same key `butlr_list_topology` writes, deliberately: both now
+    // hold the merged shape, so either can prime the other.
     const cacheKey = generateTopologyCacheKey(process.env.BUTLR_ORG_ID || "default", true, // include devices for comprehensive search
     true, // include zones
-    false, // devicesMerged: search_assets does not merge sensors/hives
+    true, // devicesMerged: devices are nested onto their floors before flattening
     undefined);
     // Try to get cached topology
     let sites = [];
@@ -106,10 +110,20 @@ export async function executeSearchAssets(args) {
         // Fetch fresh topology
         debug("search-assets", "Fetching fresh topology for search");
         try {
-            const result = await apolloClient.query({
-                query: GET_FULL_TOPOLOGY,
-                fetchPolicy: "network-only",
-            });
+            const [result, sensorsResult, hivesResult] = await Promise.all([
+                apolloClient.query({
+                    query: GET_FULL_TOPOLOGY,
+                    fetchPolicy: "network-only",
+                }),
+                apolloClient.query({
+                    query: GET_ALL_SENSORS,
+                    fetchPolicy: "network-only",
+                }),
+                apolloClient.query({
+                    query: GET_ALL_HIVES,
+                    fetchPolicy: "network-only",
+                }),
+            ]);
             // Apollo can return both data and errors - only fail if we have no data
             if (!result.data || !result.data.sites || !result.data.sites.data) {
                 // If we have error but no data, throw
@@ -118,12 +132,41 @@ export async function executeSearchAssets(args) {
                 }
                 throw new Error("Invalid response structure from API");
             }
-            // Track whether the topology data is partial (errors alongside data)
-            const partialData = !!result.error;
+            // A failed device fetch must surface as an error, not as
+            // `total_matches: 0` — and must never be cached under the key
+            // butlr_list_topology trusts.
+            throwIfGraphQLErrors(sensorsResult);
+            throwIfGraphQLErrors(hivesResult);
+            // Track whether the topology data is partial (errors alongside data).
+            // A device query that errored counts too: caching a tree whose floors
+            // carry empty sensor arrays would make every later cache hit report
+            // "no sensors in this org" as if it were the answer.
+            const partialData = !!result.error || !!sensorsResult.error || !!hivesResult.error;
             if (partialData) {
                 debug("search-assets", "Warning: GraphQL errors present, data may be partial");
             }
             sites = result.data.sites.data;
+            // Same shape contract as butlr_list_topology, which reads the cache
+            // entry this tool writes: only an explicit array survives. `|| []`
+            // here would launder a serialisation regression into a device-empty
+            // tree, cached where that tool's own contract check never runs.
+            const rawSensors = sensorsResult.data?.sensors?.data;
+            if (!Array.isArray(rawSensors)) {
+                throw new Error("Unexpected response shape from sensors query (expected array, got " +
+                    `${rawSensors === null ? "null" : typeof rawSensors}). Please retry; if persistent, the upstream API contract may have changed.`);
+            }
+            const rawHives = hivesResult.data?.hives?.data;
+            if (!Array.isArray(rawHives)) {
+                throw new Error("Unexpected response shape from hives query (expected array, got " +
+                    `${rawHives === null ? "null" : typeof rawHives}). Please retry; if persistent, the upstream API contract may have changed.`);
+            }
+            // Test/mirror devices are excluded from the corpus, matching
+            // butlr_list_topology. A search hit on a mirror sensor would hand the
+            // caller an ID that every data tool then refuses.
+            const allSensors = rawSensors.filter(isProductionSensor);
+            const allHives = rawHives.filter(isProductionHive);
+            sites = mergeSensorsAndHivesIntoTopology(sites, allSensors, allHives);
+            debug("search-assets", `Merged ${allSensors.length} sensors and ${allHives.length} hives into topology`);
             // Only cache complete topology data — partial results should be re-fetched
             if (!partialData) {
                 setCachedTopology(cacheKey, { sites });
@@ -162,6 +205,7 @@ export async function executeSearchAssets(args) {
         type: match.asset.type,
         path: buildAssetPath(match.asset),
         match_score: match.score,
+        ...(match.asset.type === "sensor" && match.asset.mode ? { mode: match.asset.mode } : {}),
         site_id: match.asset.site_id,
         building_id: match.asset.building_id,
         floor_id: match.asset.floor_id,

package/dist/tools/butlr-search-assets.js.map

@@ -1 +1 @@
-{"version":3,"file":"butlr-search-assets.js","sourceRoot":"","sources":["../../src/tools/butlr-search-assets.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"butlr-search-assets.js","sourceRoot":"","sources":["../../src/tools/butlr-search-assets.ts"],"names":[],"mappings":"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"}

package/dist/tools/butlr-traffic-flow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"butlr-traffic-flow.d.ts","sourceRoot":"","sources":["../../src/tools/butlr-traffic-flow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAcxB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AA0CjE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;EAc/B,CAAC;AA+BJ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAwBrE;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,eAAe,gCA6R7D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAsB3D"}
+{"version":3,"file":"butlr-traffic-flow.d.ts","sourceRoot":"","sources":["../../src/tools/butlr-traffic-flow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAyBxB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AA4CjE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;EAc/B,CAAC;AAiCJ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AA2CrE;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,eAAe,gCAif7D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAsB3D"}

package/dist/tools/butlr-traffic-flow.js

@@ -2,11 +2,13 @@ import { apolloClient } from "../clients/graphql-client.js";
 import { gql } from "@apollo/client";
 import { z } from "zod";
 import { ReportingRequestBuilder } from "../clients/reporting-client.js";
-import { GET_ALL_SENSORS, GET_FULL_TOPOLOGY } from "../clients/queries/topology.js";
 import { executeSearchAssets } from "./butlr-search-assets.js";
 import { getTimezoneForAsset, buildTimezoneMetadata, getLocalMidnight, } from "../utils/timezone-helpers.js";
 import { createValidationError, withToolErrorHandling } from "../errors/mcp-errors.js";
-import { rethrowIfGraphQLError, throwIfGraphQLErrors } from "../utils/graphql-helpers.js";
+import { resolveTimeToIso } from "../utils/time-resolver.js";
+import { rethrowIfGraphQLError, throwIfGraphQLErrors, isKnownTestSensor, } from "../utils/graphql-helpers.js";
+import { fetchTopology, fetchSensorsByIds, fetchSensorsByRoomIds, resolveSensorContext, } from "../utils/occupancy-helpers.js";
+import { detectAssetType } from "../utils/asset-helpers.js";
 import { debug } from "../utils/debug.js";
 const timeStringSchema = z.string().refine((val) => {
     const isoMatch = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z?$/.test(val);
@@ -23,7 +25,7 @@ const trafficFlowInputShape = {
         .min(1, "space_id_or_name cannot be empty")
         .max(200)
         .trim()
-        .describe("Space ID or search term"),
+        .describe("Room ID (room_...), sensor ID (sensor_...) for per-access-point counts, or a name search term (matches rooms and traffic sensors)"),
     time_window: z
         .enum(["20m", "1h", "today", "custom"])
         .default("today")
@@ -52,6 +54,7 @@ export const TrafficFlowArgsSchema = z
     path: ["custom_start"],
 });
 const TRAFFIC_FLOW_DESCRIPTION = "Get entry and exit counts for spaces equipped with traffic-mode sensors (typically lobbies, building entrances, elevator banks). Returns total movements, net flow (entries - exits), and hourly breakdown in the space's local timezone. Designed for space activation analysis, security/compliance, and amenity demand forecasting.\n\n" +
+    "Accepts a room ID (counts aggregate across the room's traffic sensors), a single sensor ID (sensor_...) for per-access-point counts, or a name to search. Sensors do not need to be assigned to a room to be queried directly, and a name search matches sensors as well as rooms, so an access point does not have to be modeled as a room. (Name search covers devices assigned to a floor; a floor-less or not-yet-MAC-bound sensor is still queryable by its sensor_... ID.)\n\n" +
     "Primary Users:\n" +
     "- Facilities Manager: Monitor building entry/exit patterns, optimize security staffing, validate badge system accuracy\n" +
     "- Workplace Manager: Understand amenity traffic (café, gym, event spaces), measure activation of new spaces\n" +
@@ -65,7 +68,8 @@ const TRAFFIC_FLOW_DESCRIPTION = "Get entry and exit counts for spaces equipped
     '5. "Show me lobby traffic for the last 20 minutes"\n' +
     '6. "What\'s the net flow (entries - exits) for Floor 2 today?"\n' +
     '7. "How many people entered the event space during lunch hour (12-1pm)?"\n' +
-    '8. "Compare today\'s building entrance traffic to typical Monday"\n\n' +
+    '8. "Compare today\'s building entrance traffic to typical Monday"\n' +
+    '9. "How many people came through the north elevator door today?" (a single sensor, by name or by sensor_... ID)\n\n' +
     "When to Use:\n" +
     "- Entry/exit counts for lobbies, building entrances, elevator banks, or amenities\n" +
     "- Understand peak traffic hours for security, cleaning, or HVAC planning\n" +
@@ -99,69 +103,145 @@ const GET_ROOM_SENSORS = gql `
     }
   }
 `;
+/**
+ * Fetch a room and its floor/building context. Kept separate from the shared
+ * topology fetch so it can run in parallel with it.
+ */
+async function fetchRoom(roomId) {
+    try {
+        const result = await apolloClient.query({
+            query: GET_ROOM_SENSORS,
+            variables: { roomId },
+            fetchPolicy: "network-only",
+        });
+        throwIfGraphQLErrors(result);
+        return result;
+    }
+    catch (error) {
+        rethrowIfGraphQLError(error);
+        throw error;
+    }
+}
 /**
  * Execute traffic flow tool
  */
 export async function executeTrafficFlow(args) {
     let spaceId = args.space_id_or_name;
-    // If not an ID, search for the space
-    if (!spaceId.match(/^room_/)) {
+    // One prefix detector for both branches. `asset-helpers.ts` is the single
+    // place that encodes ID prefixes, so re-testing the string with a local
+    // regex here would be a second thing to keep in sync with it.
+    let assetType = detectAssetType(spaceId);
+    // If it is neither a room nor a sensor ID, treat it as a search term.
+    // Direct sensor queries skip room resolution entirely: the reporting API
+    // serves sensor-level traffic via the sensors filter, so a sensor does not
+    // need a room wrapper to be queryable.
+    if (assetType !== "sensor" && assetType !== "room") {
         debug("traffic-flow", `Searching for space: "${args.space_id_or_name}"`);
+        // Both types, so a natural-language query can reach the sensor path too.
+        // The customer ask behind sensor support was to stop modeling each door as
+        // a room; searching rooms only would leave the capability reachable solely
+        // by callers who already know the sensor ID.
         const searchResults = await executeSearchAssets({
             query: args.space_id_or_name,
-            asset_types: ["room"], // Traffic is room-level
+            asset_types: ["room", "sensor"],
             max_results: 5,
         });
         if (searchResults.matches.length === 0) {
-            throw new Error(`No rooms found matching "${args.space_id_or_name}". Try a different search term.`);
+            throw new Error(`No rooms or sensors found matching "${args.space_id_or_name}". Try a different search term, or pass a room ID (room_...) or sensor ID (sensor_...) directly. butlr_search_assets finds both by name or MAC; butlr_hardware_snapshot lists sensors with their health.`);
         }
-        spaceId = searchResults.matches[0].id;
-        debug("traffic-flow", `Using best match: ${searchResults.matches[0].name} (${spaceId})`);
+        // Take the highest-ranked candidate that can actually serve traffic: any
+        // room (validated downstream), or a traffic-mode sensor. Taking
+        // matches[0] unconditionally let a presence sensor whose name outranks
+        // the intended room dead-end the whole query with the right room sitting
+        // at index 1.
+        const viable = searchResults.matches.find((m) => m.type === "room" || (m.type === "sensor" && m.mode === "traffic"));
+        if (!viable) {
+            throw new Error(`"${args.space_id_or_name}" matched only presence-mode sensors, which have no entry/exit counts. Try butlr_get_current_occupancy for occupancy data, or search for a room or traffic-mode sensor.`);
+        }
+        spaceId = viable.id;
+        assetType = detectAssetType(spaceId);
+        debug("traffic-flow", `Using best viable match: ${viable.name} (${spaceId}, ${assetType})`);
     }
-    // Query room details, topology for timezone, and all sensors
-    let room = null;
+    const isSensorQuery = assetType === "sensor";
+    // Query asset details, topology for timezone, and sensors
+    let displayName = "";
     let roomPath = "";
     let timezone;
     let tzMetadata;
     let timezoneFallback = false;
     let trafficSensors = [];
-    try {
-        const [roomResult, topoResult, sensorsResult] = await Promise.all([
-            apolloClient.query({
-                query: GET_ROOM_SENSORS,
-                variables: { roomId: spaceId },
-                fetchPolicy: "network-only",
-            }),
-            apolloClient.query({
-                query: GET_FULL_TOPOLOGY,
-                fetchPolicy: "network-only",
-            }),
-            apolloClient.query({
-                query: GET_ALL_SENSORS,
-                fetchPolicy: "network-only",
-            }),
+    let installationWarning;
+    if (isSensorQuery) {
+        // One sensor by ID, not the org's whole inventory: the `sensors` root
+        // field accepts an `ids` argument, and nothing on this branch needs the
+        // full list. A capped or paged `sensors` field would otherwise turn a real
+        // sensor past the cap into a bogus "not found".
+        const [topology, sensors] = await Promise.all([fetchTopology(), fetchSensorsByIds([spaceId])]);
+        const sensor = sensors.find((s) => s.id === spaceId);
+        if (!sensor) {
+            throw new Error(`Sensor ${spaceId} not found`);
+        }
+        // Resolved up front so the rejections below can consult real topology
+        // rather than pointing the caller at an ID that may not resolve.
+        const sensorContext = resolveSensorContext(sensor, topology);
+        // Only a KNOWN test device is refused. isProductionSensor is stricter (it
+        // also drops MAC-less placeholder rows) and is the right filter for the
+        // room path's aggregate below, but applying it to a caller's explicit
+        // request would tell the owner of a real, not yet MAC bound sensor that
+        // their device is fake and leave them no way to query it.
+        if (isKnownTestSensor(sensor)) {
+            throw new Error(`Sensor "${sensor.name}" (${spaceId}) is a test/mirror device, not a production sensor — it has no real traffic data.`);
+        }
+        if (sensor.mode !== "traffic") {
+            // Only name the room when it actually resolves. A dangling room_id (the
+            // room was deleted) would otherwise send the caller to a second dead
+            // end: butlr_get_current_occupancy accepts the room_ prefix, finds no
+            // room, and answers "no sensors configured".
+            const suggestion = sensorContext.room
+                ? `Try butlr_get_current_occupancy with its room (${sensorContext.room.id}) instead.`
+                : `Try butlr_get_asset_details or butlr_hardware_snapshot to inspect it.`;
+            throw new Error(`Sensor "${sensor.name}" is ${sensor.mode ? `a ${sensor.mode}-mode sensor` : "not a traffic-mode sensor"}, so it has no entry/exit counts. ${suggestion}`);
+        }
+        // An uninstalled sensor reports nothing, which otherwise reads as a
+        // confident zero. That is likelier here than on the room path: the caller
+        // picked one specific device rather than a room aggregating several.
+        if (sensor.installation_status === "UNINSTALLED") {
+            installationWarning = `Sensor "${sensor.name}" is marked UNINSTALLED in the platform. An uninstalled sensor reports no traffic, so a zero count is expected; any rows returned predate its removal. Check butlr_hardware_snapshot for its current status.`;
+        }
+        trafficSensors = [sensor];
+        displayName = sensorContext.name;
+        roomPath = sensorContext.path;
+        timezone = sensorContext.timezone;
+        tzMetadata = sensorContext.tzMetadata;
+        timezoneFallback = sensorContext.timezoneFallback;
+        debug("traffic-flow", `Direct sensor query: ${displayName} (${spaceId})`);
+    }
+    else {
+        // The room's own sensor rows via `sensors(room_ids:)` rather than the
+        // org-wide inventory. The rows arrive unfiltered and only KNOWN test
+        // devices (mirror/fake prefixes) are dropped: this list drives the
+        // refusal gate and sensor_count, never the totals (the reporting API
+        // aggregates by room_id server-side), so a provisioned-but-MAC-less
+        // sensor must not disqualify its room the way the stricter
+        // isProductionSensor aggregate filter would.
+        const [topology, roomResult, roomSensorRows] = await Promise.all([
+            fetchTopology(),
+            fetchRoom(spaceId),
+            fetchSensorsByRoomIds([spaceId]),
         ]);
-        throwIfGraphQLErrors(roomResult);
-        throwIfGraphQLErrors(topoResult);
-        throwIfGraphQLErrors(sensorsResult);
-        if (!roomResult.data?.room) {
+        if (!roomResult?.data?.room) {
             throw new Error(`Room ${spaceId} not found`);
         }
-        room = roomResult.data.room;
+        const room = roomResult.data.room;
+        displayName = room.name;
         const floor = room.floor;
         const building = floor?.building;
         roomPath = building ? `${building.name} > ${floor.name} > ${room.name}` : room.name;
-        // Get timezone for this room
-        const sites = topoResult.data?.sites?.data || [];
-        const buildings = sites.flatMap((s) => s.buildings || []);
-        const floors = buildings.flatMap((b) => b.floors || []);
-        const resolved = getTimezoneForAsset(spaceId, "room", floors, buildings, sites);
+        const resolved = getTimezoneForAsset(spaceId, "room", topology.floors, topology.buildings, topology.sites);
         timezone = resolved.timezone;
         timezoneFallback = resolved.isFallback;
         tzMetadata = buildTimezoneMetadata(timezone);
-        // Analyze traffic sensors for this room
-        const allSensors = sensorsResult.data?.sensors?.data || [];
-        const roomSensors = allSensors.filter((s) => (s.room_id || s.roomID) === spaceId);
+        const roomSensors = roomSensorRows.filter((s) => !isKnownTestSensor(s));
         // Room-level traffic counts every traffic-mode sensor bound to the room.
         // See `resolveAssetContext` in occupancy-helpers.ts for the canonical
         // rationale: `is_entrance` is a semantic flag, not a routing one, and the
@@ -172,10 +252,6 @@ export async function executeTrafficFlow(args) {
         }
         debug("traffic-flow", `Found ${trafficSensors.length} traffic sensors for room`);
     }
-    catch (error) {
-        rethrowIfGraphQLError(error);
-        throw error;
-    }
     // Calculate time range
     const timeWindow = args.time_window || "today";
     let start;
@@ -220,36 +296,98 @@ export async function executeTrafficFlow(args) {
             : `today (${tzMetadata.timezone_abbr})`;
         debug("traffic-flow", `Today starts at ${start} (midnight ${usedUtcFallback ? "UTC fallback" : tzMetadata.timezone_abbr})`);
     }
-    debug("traffic-flow", `Querying traffic from ${start} to ${stop}`);
+    // Resolve relative forms ("-20m", "now") to absolute timestamps: the
+    // ETL-backed reporting API requires RFC3339, and the response period
+    // metadata should carry real timestamps rather than relative strings.
+    start = resolveTimeToIso(start);
+    stop = resolveTimeToIso(stop);
+    // Pick window granularity from the range length. The ETL backend only
+    // returns fully-closed, end-labeled buckets that fit inside [start, stop]:
+    // a 1h window over a short recent range drops the in-progress hour
+    // entirely (its bucket doesn't exist until the hour closes). Querying 1m
+    // buckets for short ranges keeps edge loss to at most the current minute;
+    // results are rolled back up to hours below.
+    const durationMs = new Date(stop).getTime() - new Date(start).getTime();
+    const windowEvery = durationMs <= 2 * 60 * 60 * 1000 ? "1m" : "1h";
+    debug("traffic-flow", `Querying traffic from ${start} to ${stop} (window ${windowEvery})`);
+    // `fine` marks 1m-bucket points whose timestamps must be rolled up to the
+    // enclosing hour; native 1h bucket labels pass through untouched (they may
+    // sit on a non-UTC-aligned local grid, e.g. :30-offset timezones).
     let trafficData = [];
+    const queryAssetType = isSensorQuery ? "sensor" : "room";
     try {
         const response = await new ReportingRequestBuilder()
-            .assets("room", [spaceId])
+            .assets(queryAssetType, [spaceId])
             .measurements(["traffic"])
             .timeRange(start, stop)
-            .window("1h", "sum", timezone) // Sum traffic per hour, aligned to local timezone
+            .window(windowEvery, "sum", timezone) // Sum traffic per bucket, aligned to local timezone
             .execute();
         // Parse flat array response
         // Traffic returns TWO data points per hour per sensor: "in" and "out"
         if (!Array.isArray(response.data)) {
             throw new Error("Expected array response from traffic query");
         }
-        trafficData = response.data;
+        trafficData = response.data.map((p) => ({
+            ...p,
+            fine: windowEvery === "1m",
+        }));
         debug("traffic-flow", `Received ${trafficData.length} data points from ${trafficSensors.length} sensors`);
+        // A 1h bucket only exists once its hour closes AND the ETL has written
+        // it, so a range ending at/near now silently misses the in-progress hour
+        // and possibly the just-closed one. Re-query the trailing 2 hours at 1m
+        // granularity and merge; hours already covered by a returned 1h bucket
+        // are deduplicated in the rollup below. The tail exists solely to
+        // recover those not-yet-materialized recent hours (materialization lag
+        // measured at up to ~1h), so it is skipped when the range's stop is old
+        // enough that every hourly bucket has long since landed.
+        if (windowEvery === "1h") {
+            const stopDate = new Date(stop);
+            const startDate = new Date(start);
+            const twoHoursMs = 2 * 60 * 60 * 1000;
+            const tailStartMs = Math.max(startDate.getTime(), stopDate.getTime() - twoHoursMs);
+            const recentStopMs = 3 * 60 * 60 * 1000;
+            if (tailStartMs < stopDate.getTime() && Date.now() - stopDate.getTime() < recentStopMs) {
+                try {
+                    const tailResponse = await new ReportingRequestBuilder()
+                        .assets(queryAssetType, [spaceId])
+                        .measurements(["traffic"])
+                        .timeRange(new Date(tailStartMs).toISOString(), stop)
+                        .window("1m", "sum", timezone)
+                        .execute();
+                    if (Array.isArray(tailResponse.data)) {
+                        trafficData = trafficData.concat(tailResponse.data.map((p) => ({ ...p, fine: true })));
+                        debug("traffic-flow", `Merged ${tailResponse.data.length} tail data points (1m)`);
+                    }
+                }
+                catch (tailError) {
+                    // The closed-hour data is still valid without the tail
+                    debug("traffic-flow", "Partial-hour tail query failed:", tailError);
+                }
+            }
+        }
     }
     catch (error) {
         rethrowIfGraphQLError(error);
         debug("traffic-flow", "Failed to get traffic data:", error);
         const msg = error instanceof Error ? error.message : String(error);
-        throw new Error(`Failed to get traffic data for ${room.name}. ${msg}`);
+        throw new Error(`Failed to get traffic data for ${displayName}. ${msg}`);
     }
     // Parse traffic data: group by time, then by sensor, then aggregate
-    // Store time separately to preserve full ISO timestamp
+    // Store time separately to preserve full ISO timestamp. The fine flag is
+    // part of the key: a 1m tail bucket ending exactly on an hour boundary
+    // carries the same label as that hour's native 1h bucket, and must not
+    // share (and overwrite) the native bucket's entry.
     const byHourSensor = new Map();
     for (const point of trafficData) {
-        const key = `${point.time}:${point.sensor_id}`;
+        const key = `${point.time}:${point.sensor_id}:${point.fine}`;
         if (!byHourSensor.has(key)) {
-            byHourSensor.set(key, { time: point.time, in: 0, out: 0 });
+            byHourSensor.set(key, {
+                time: point.time,
+                sensor_id: point.sensor_id,
+                fine: point.fine,
+                in: 0,
+                out: 0,
+            });
         }
         const counts = byHourSensor.get(key);
         if (point.field === "in") {
@@ -259,10 +397,48 @@ export async function executeTrafficFlow(args) {
             counts.out = point.value || 0;
         }
     }
+    // Roll a bucket timestamp up to its enclosing hour. Bucket timestamps are
+    // end-labeled (a 1m bucket "17:29" covers 17:28–17:29), so ceil to the
+    // hour to stay on the same end-labeled convention the API uses for 1h
+    // buckets.
+    const toHourEnd = (iso) => {
+        const d = new Date(iso);
+        if (d.getUTCMinutes() !== 0 || d.getUTCSeconds() !== 0 || d.getUTCMilliseconds() !== 0) {
+            d.setUTCMinutes(0, 0, 0);
+            d.setUTCHours(d.getUTCHours() + 1);
+        }
+        return d.toISOString().replace(".000Z", "Z");
+    };
+    // Native (closed) 1h buckets are authoritative for the interval they
+    // cover, so fine-grained tail minutes falling inside any of them are
+    // dropped to avoid double counting. Coverage is checked on the bucket
+    // intervals themselves — an end-labeled 1h bucket T covers (T-1h, T] —
+    // rather than on labels, so it also holds for sites whose local hour grid
+    // is not UTC-aligned (e.g. :30-offset timezones). Coverage is tracked
+    // per sensor: bucket materialization is a per-series flush, so one
+    // sensor's landed hour must not suppress another sensor's tail minutes
+    // for that same hour.
+    const HOUR_MS = 60 * 60 * 1000;
+    const nativeEndsBySensor = new Map();
+    for (const [, data] of byHourSensor) {
+        if (!data.fine) {
+            const ends = nativeEndsBySensor.get(data.sensor_id) || [];
+            ends.push(new Date(data.time).getTime());
+            nativeEndsBySensor.set(data.sensor_id, ends);
+        }
+    }
+    const coveredByNative = (sensorId, iso) => {
+        const t = new Date(iso).getTime();
+        const ends = nativeEndsBySensor.get(sensorId);
+        return ends ? ends.some((end) => t <= end && t > end - HOUR_MS) : false;
+    };
     // Aggregate across sensors by hour (group by time only)
     const byHour = new Map();
     for (const [_key, data] of byHourSensor) {
-        const time = data.time; // Use actual time from data, not split key
+        if (data.fine && coveredByNative(data.sensor_id, data.time)) {
+            continue;
+        }
+        const time = data.fine ? toHourEnd(data.time) : data.time;
         if (!byHour.has(time)) {
             byHour.set(time, { in: 0, out: 0 });
         }
@@ -294,13 +470,32 @@ export async function executeTrafficFlow(args) {
     }
     // Build enhanced summary
     const netFlowStr = netFlow >= 0 ? `+${netFlow}` : `${netFlow}`;
-    const summary = `${room.name}: ${totalTraffic.toLocaleString()} movements ${periodDescription} (${totalEntries.toLocaleString()} entries, ${totalExits.toLocaleString()} exits, net flow: ${netFlowStr})`;
+    const summary = `${displayName}: ${totalTraffic.toLocaleString()} movements ${periodDescription} (${totalEntries.toLocaleString()} entries, ${totalExits.toLocaleString()} exits, net flow: ${netFlowStr})`;
+    // Compose the response warning. Two independent conditions can raise one and
+    // both matter, so they are joined rather than one silently shadowing the other.
+    const warnings = [];
+    if (installationWarning) {
+        warnings.push(installationWarning);
+    }
+    if (usedUtcFallback) {
+        // Window-aware copy. The midnight sentence is only true on the `today`
+        // branch. The unassigned-sensor path sets timezoneFallback for every
+        // room-less, floor-less sensor, so on a 20m/1h/custom window the old text
+        // fired routinely and sent the reader chasing a day-alignment problem that
+        // no part of the query involved.
+        // `timezone` holds whatever the fallback actually resolved to — UTC, or
+        // BUTLR_TIMEZONE when configured — so the copy names it rather than
+        // asserting UTC for a query that may have used something else.
+        warnings.push(timeWindow === "today"
+            ? `Could not determine local timezone for this space; timestamps use midnight in the fallback timezone (${timezone}). 'Today' may not align with the site's actual local day.`
+            : `Could not determine local timezone for this space; hourly bucket alignment falls back to ${timezone}, so buckets may not line up with the site's local hours. The queried range itself is unaffected.`);
+    }
     // Build response with timezone metadata and in/out breakdown
     const response = {
         space: {
-            id: room.id,
-            name: room.name,
-            type: "room",
+            id: spaceId,
+            name: displayName,
+            type: isSensorQuery ? "sensor" : "room",
             path: roomPath,
             sensor_mode: "traffic",
             ...tzMetadata,
@@ -330,9 +525,12 @@ export async function executeTrafficFlow(args) {
         summary,
         timestamp: new Date().toISOString(),
         timezone_note: "All timestamps are UTC (ISO-8601). Use site_timezone to interpret in local time.",
-        ...(usedUtcFallback && {
-            warning: "Could not determine local timezone for this space; timestamps use UTC midnight as fallback. 'Today' may not align with the site's actual local day.",
+        // Traffic events take ~5-6 minutes to land in the reporting store, so a
+        // window ending at/near now structurally undercounts the trailing minutes
+        ...(Date.now() - new Date(stop).getTime() < 10 * 60 * 1000 && {
+            freshness_note: "Traffic data becomes available roughly 5-10 minutes after events occur. Counts for the most recent ~10 minutes may still be incomplete; re-query later for final numbers.",
         }),
+        ...(warnings.length > 0 && { warning: warnings.join(" ") }),
     };
     return response;
 }