feat: integrate PR #347 provenance through current feed and session owners

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Changelog
 
+Add feed provenance to analyst/view answers and HUD context while retaining existing response fields and runner ownership (Matt Van Horn, #347).
+
 Analyst records for loaded satellites, datacenters and dams, with explicit bounded count/rank coverage (Matt Van Horn, #351).
 
 - Add an optional Nominatim geocoding adapter with configurable search/reverse endpoints, cancellation, bounded responses and retryable upstream errors. Extract portable response-reading and Overpass lexical helpers while retaining existing server exports.

docs/CURRENT-STATE.md

@@ -1,5 +1,7 @@
 # God's Eye View Current State
 
+Voice and HUD snapshots reuse the existing feedState classifier. Analyst follow-ups retain their original data provenance; current-view results append provenance without replacing legacy fields. HUD context and deterministic telemetry include non-nominal feed state.
+
 Satellite and local infrastructure layers expose on-demand analyst records through their current factory owners. Analyst counts and ranks explicitly cover only bounded examined loaded records; omitted records can change nearest/count and satellite distance is ground distance. Existing tools and result fields remain available.
 
 Place search accepts an explicit Nominatim provider with independently configured search and reverse endpoints. The default offline/Google/Photon/local-fallback order is unchanged when no provider is selected. Provider adapters share normalized coordinates, viewport framing and reverse labels; roads and boundary geometry remain separate services. Portable capped-response and Overpass lexical helpers are exported independently of the Node server.

server/providers/openai/hud-summary.js

@@ -1,4 +1,4 @@
-import { keylessHudSummaryResponse } from '../../../src/hudSummaryResponse.js';
+import { HUD_SUMMARY_INSTRUCTIONS, keylessHudSummaryResponse } from '../../../src/hudSummaryResponse.js';
 import { enforceOptInRateLimit, openAiRateLimiter } from './rate-limit.js';
 import { readRequestBody } from '../common/request.js';
 import { OPENAI_HUD_SUMMARY_MODEL_DEFAULT } from './constants.js';
@@ -61,13 +61,7 @@ async function handleHudSummary(req, res) {
         model:
           process.env.OPENAI_HUD_SUMMARY_MODEL ||
           OPENAI_HUD_SUMMARY_MODEL_DEFAULT,
-        instructions: [
-          "Write one concise intelligence-HUD summary for God's Eye View.",
-          'Use only the supplied place, street, nearby-place, and enabled-layer text labels.',
-          'Prefer the clearest named place and include a relevant enabled layer only when useful.',
-          'Do not infer from coordinates or invent a place.',
-          'Output exactly five words with no title, punctuation, markdown, or introductory phrase.',
-        ].join(' '),
+        instructions: HUD_SUMMARY_INSTRUCTIONS,
         input: JSON.stringify(context),
         reasoning: { effort: 'minimal' },
         max_output_tokens: 100,

server/providers/openai/instructions.js

@@ -18,7 +18,8 @@ function realtimeInstructions(
     'For camera-motion requests — "orbit around this", "pan left", "tilt up", "stop moving" — call move_camera. For "fly the route" over a drawn route, call fly_route. Confirm with the RESULTING state ("Orbiting slowly", "Flying the route").',
     'analyst_query ANSWERS questions; it never moves the camera or starts tracking. For requests to FOLLOW or TRACK a specific aircraft/ship, call track_entity (get_entity_context first when the target is ambiguous), never analyst_query as the final or only action. For "follow/track the nearest aircraft", first call analyst_query with the aircraft layer(s), sortBy=distance, and limit=1, then call track_entity with the returned aircraft identity in the same turn. The lookup alone does not fulfill a follow/track command.',
     'For a request to enable an aircraft layer and SELECT or FIND the nearest/closest aircraft near a named place — for example, "Turn on flights and select the closest aircraft to Austin" — call select_nearest_aircraft once. It atomically turns on the requested aircraft layer first, waits for location arrival, refreshes that layer for the destination viewport, filters out landed/on-ground records, and selects the nearest airborne result. A healthy fallback feed is valid data: report the returned feed source briefly, never call it an enable failure. Do not also call fly_to_location, set_layer_visibility, analyst_query, track_entity, set_context_mode, or control_cockpit for the same request. SELECT/FIND never implies Contacts or Cockpit unless the user explicitly asks for either mode.',
-    'For ANALYTICAL questions about layer data — how many / which / fastest / highest / biggest / nearest flights, ships, fires, or earthquakes ("how many flights over Texas", "biggest fire near LA", "which ships are headed to Oakland", "anything above 40,000 feet") — call analyst_query, not get_entity_context. Narrate the count plus two or three notable examples by name, and reflect the result\'s coverage note honestly: the answer covers data loaded by enabled layers, not the whole world. If the needed layer is disabled, say so and offer to enable it. For follow-ups about the same set ("which of THOSE is closest?"), call analyst_query with followUp=true and only the new filter/sort.',
+    'For ANALYTICAL questions about layer data — how many / which / fastest / highest / biggest / nearest flights, ships, fires, earthquakes, satellites, datacenters, or dams ("how many flights over Texas", "biggest fire near LA", "which ships are headed to Oakland", "anything above 40,000 feet") — call analyst_query, not get_entity_context. Narrate the count plus two or three notable examples by name, and reflect the result\'s coverage note honestly: the answer covers data loaded by enabled layers, not the whole world. If the needed layer is disabled, say so and offer to enable it. For follow-ups about the same set ("which of THOSE is closest?"), call analyst_query with followUp=true and only the new filter/sort.',
+'FEED STATE CONTRACT — analyst_query and get_current_view_state carry feedProvenance from the same layerFeedState the Data Layers chips use (nominal/loading/degraded/stale/fallback/unavailable, or off). NEVER narrate a count as live or current when feedProvenance.overall is not nominal. Say the feedState in the same breath as the count ("12 flights in view, STALE"). If unavailable, do not invent a count; say the feed is unavailable. Fallback is valid data — name the fallback source, never call it an enable failure. Confirm only what the tool result returned.',
     'COUNTING CONTRACT — what "near" means. (1) While Contacts is ACTIVE, "near / nearby / how many aircraft" means the Contacts window: answer from contactsWindow in the tool result — those are the exact numbers on the user\'s panel. set_context_mode, analyst_query, and get_current_view_state carry it after Contacts settles. For "Open Contacts and tell me how many aircraft are within 250 km", call set_context_mode{mode:"contacts"} first and answer from contactsWindow.aircraft; do not answer from a pre-Contacts analyst query. analyst_query\'s own count measures currently-loaded records and is usually lower; never give it as the window count. CENTER PRECEDENCE for a nearby/how-many ask, in order: an explicit place in the question ("over Texas", "near Austin") always wins and ignores Contacts state; else the CONTACTS SUBJECT when Contacts is active and has one — a selected datacenter, dam, fire, or cable does NOT silently become the center; else an entity the user explicitly names ("around this datacenter"); else the current view, said aloud ("nothing is selected, so this is the current view"). With Contacts active but NO subject yet, use the view and say so; never read an empty panel. (2) With Contacts OFF, "nearby" means in view; "near <place>" means a radius around that place. (3) EVERY count names its scope in words — "42 in your window", "8 in view", "about 30 within 250 km of Austin" — never a bare number; analyst_query returns scopeLabel for exactly this. Two different numbers with named scopes are not a contradiction; say both if asked. (4) State counts VERBATIM — never estimate, round, or hedge ("a few", "less than a dozen"): if a tool returns 46, say 46. (5) When it matters, add once: counts cover loaded data, and the flights layer loads where you look.',
     'While Cockpit is active, navigate with control_cockpit (next/previous, optionally targetLayer or aircraftClass). track_entity and fly_to_location are REFUSED by design while Cockpit owns the camera — that refusal is correct, not an error to retry. To go somewhere else, exit Cockpit first. control_cockpit enter establishes Contacts itself, so do not call set_context_mode before or after it.',
     'When the target layer is unknown, OMIT layerId in track_entity so it searches all enabled layers. Passing the wrong layerId ("flights" for a military contact) returns "Nothing matched" even though the contact is loaded.',

server/providers/openai/toolDescriptions.js

@@ -505,7 +505,7 @@ export const ACTION_DESCRIPTIONS = {
   },
   analyst_query: {
     description:
-      'Answer questions ABOUT the data currently loaded on the map — counts, lists, superlatives, and attribute filters over live layers (flights, military, ships, fires, earthquakes). Examples: "how many flights over Texas", "biggest fire near LA", "which ships are headed to Oakland", "anything above 40,000 feet", "fastest thing in view". Queries ONLY client-side data from ENABLED layers — if the needed layer is off, say so and offer to enable it. For a follow-up about the previous answer\'s set ("which of those is closest?"), set followUp=true and send only the new filters/sort.',
+      'Answer questions ABOUT the data currently loaded on the map — counts, lists, superlatives, and attribute filters over live layers (flights, military, ships, fires, earthquakes, satellites, datacenters, dams). Examples: "how many flights over Texas", "biggest fire near LA", "which ships are headed to Oakland", "anything above 40,000 feet", "fastest thing in view". For satellites and infrastructure, counts and ranks cover only bounded examined loaded records; omitted records can change nearest/count. Queries ONLY client-side data from ENABLED layers — if the needed layer is off, say so and offer to enable it. For a follow-up about the previous answer\'s set ("which of those is closest?"), set followUp=true and send only the new filters/sort.',
     $position: 1,
     parameters: {
       properties: {

src/data/analystEngine.js

@@ -24,6 +24,7 @@
  * @module data/analystEngine
  */
 
+import { feedProvenanceEnvelope } from './layerSnapshot.js';
 import { pointInRing } from './naturalEarthRegions.js';
 
 /** Layers the engine understands, with the fields queries may reference. */
@@ -118,12 +119,15 @@ export function createAnalystEngine(providers) {
     // 1) Source records
     let records;
     let layersQueried;
+    let queriedSnapshots;
     if (layers === null) {
       records = lastResult.items.slice();
       layersQueried = lastResult.coverage.layersQueried;
+      queriedSnapshots = lastResult.coverage.feedProvenance?.layers || [];
     } else {
       records = [];
       layersQueried = [];
+      queriedSnapshots = [];
       const unknown = layers.filter((k) => !ANALYST_LAYERS[k]);
       if (unknown.length) {
         return {
@@ -135,7 +139,9 @@ export function createAnalystEngine(providers) {
       for (const key of layers) {
         if (!ANALYST_LAYERS[key]) continue;
         const rows = providers.getRecords(key) || [];
-        layersQueried.push({ layerKey: key, records: rows.length, ...providers.getRecordCoverage?.(key, rows) });
+        const snapshot = providers.getLayerSnapshot?.(key);
+        if (snapshot) queriedSnapshots.push(snapshot);
+        layersQueried.push({ layerKey: key, records: rows.length, ...(snapshot ? { feedState: snapshot.feedState, source: snapshot.source, lastUpdate: snapshot.lastUpdate, enabled: snapshot.enabled, error: snapshot.error } : {}), ...providers.getRecordCoverage?.(key, rows) });
         for (const row of rows) records.push({ layerKey: key, ...row });
       }
     }
@@ -231,6 +237,7 @@ export function createAnalystEngine(providers) {
       coverage: {
         layersQueried,
         scope: scopeNote,
+        ...(queriedSnapshots.length ? { feedProvenance: feedProvenanceEnvelope(queriedSnapshots) } : {}),
         followUp: Boolean(spec.followUp && lastResult),
         note: layersQueried.some((layer) => layer.basis === 'bounded-loaded-records')
           ? 'Counts and ranks cover the bounded examined loaded records only; omitted records may change the nearest item or count. Satellite distance is ground distance, not slant range.'

src/data/analystEngine.test.mjs

@@ -262,3 +262,21 @@ test('bounded loaded cohorts disclose truncation before filtering and retain it
   const followUp = await engine.query({ followUp: true });
   assert.equal(followUp.coverage.layersQueried[0].loadedCount, 3000);
 });
+
+
+test('follow-up provenance stays attached to old rows after a feed recovers', async () => {
+  let state = 'stale';
+  const engine = createAnalystEngine({
+    getRecords: () => [{ id: 'A', lat: 0, lon: 0 }],
+    getLayerSnapshot: () => ({ id: 'flights', enabled: true, feedState: state }),
+    getViewContext: () => ({ lat: 0, lon: 0, viewRadiusKm: 25 }),
+  });
+  const first = await engine.query();
+  state = 'nominal';
+  const followUp = await engine.query({ followUp: true });
+  assert.equal(first.coverage.feedProvenance.overall, 'stale');
+  assert.equal(followUp.coverage.feedProvenance.overall, 'stale');
+  engine.reset();
+  assert.equal(engine.hasMemory(), false);
+  assert.equal((await engine.query()).coverage.feedProvenance.overall, 'nominal');
+});

src/data/layerSnapshot.js

@@ -0,0 +1,234 @@
+import { layerFeedState } from './feedState.js';
+/**
+ * Shared layer snapshot envelope for voice and HUD answers.
+ *
+ * Data Layers chips, `analyst_query`, `get_current_view_state`, and the HUD
+ * summary must all name the same feed-state. This module is the one envelope:
+ * it classifies `getStats()` through `layerFeedState` and stamps the result
+ * so a stale or degraded feed cannot be narrated as live. Cesium-free so the
+ * HUD summary proxy can import it from Node.
+ *
+ * @module data/layerSnapshot
+ */
+
+/** Feed states the Data Layers chips and voice/HUD provenance share. */
+export const LAYER_FEED_STATES = Object.freeze([
+  'nominal',
+  'loading',
+  'degraded',
+  'stale',
+  'fallback',
+  'unavailable',
+]);
+
+/** Chip labels for enabled layers. Disabled layers read OFF, not a feed-state. */
+export const LAYER_FEED_STATE_LABELS = Object.freeze({
+  nominal: 'ON',
+  loading: 'LOADING',
+  degraded: 'DEGRADED',
+  stale: 'STALE',
+  fallback: 'FALLBACK',
+  unavailable: 'UNAVAILABLE',
+});
+
+/** Snapshot feed-state including a disabled layer. */
+export const SNAPSHOT_FEED_STATES = Object.freeze([...LAYER_FEED_STATES, 'off']);
+
+/**
+ * Lower rank is more severe. Voice/HUD `overall` is the worst queried state
+ * so a mixed roster cannot hide an unavailable or stale feed behind a nominal
+ * neighbour.
+ */
+export const FEED_STATE_SEVERITY = Object.freeze({
+  unavailable: 0,
+  loading: 1,
+  degraded: 2,
+  stale: 3,
+  fallback: 4,
+  nominal: 5,
+  off: 6,
+});
+
+export { layerFeedState } from './feedState.js';
+
+function snapshotError(stats) {
+  const err = stats?.error || stats?.lastError || stats?.managerRefreshError;
+  if (err == null || err === '') return null;
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * Age of a lastUpdate timestamp in whole seconds.
+ * @param {number|null|undefined} lastUpdate Epoch ms.
+ * @param {number} [now=Date.now()] Clock for tests.
+ * @returns {number|null} Non-negative seconds, or null when unknown.
+ */
+export function snapshotAgeSec(lastUpdate, now = Date.now()) {
+  const stamp = Number(lastUpdate);
+  if (!Number.isFinite(stamp) || stamp <= 0) return null;
+  return Math.max(0, Math.floor((now - stamp) / 1000));
+}
+
+/**
+ * Compact age label matching the Data Layers meta line.
+ * @param {number|null|undefined} lastUpdate Epoch ms.
+ * @param {number} [now=Date.now()] Clock for tests.
+ * @returns {string|null} `just now` / `12s ago` / `4m ago` / `2h ago`.
+ */
+export function snapshotAgeLabel(lastUpdate, now = Date.now()) {
+  const sec = snapshotAgeSec(lastUpdate, now);
+  if (sec === null) return null;
+  if (sec < 5) return 'just now';
+  if (sec < 60) return `${sec}s ago`;
+  if (sec < 3600) return `${Math.floor(sec / 60)}m ago`;
+  return `${Math.floor(sec / 3600)}h ago`;
+}
+
+/**
+ * Pick the most severe feed-state from a list.
+ * @param {Iterable<string|null|undefined>} states Feed-state strings.
+ * @returns {'nominal'|'loading'|'degraded'|'stale'|'fallback'|'unavailable'|'off'|null}
+ */
+export function worstFeedState(states) {
+  let worst = null;
+  let worstRank = Number.POSITIVE_INFINITY;
+  for (const state of states || []) {
+    if (!Object.hasOwn(FEED_STATE_SEVERITY, state)) continue;
+    const rank = FEED_STATE_SEVERITY[state];
+    if (rank < worstRank) {
+      worst = state;
+      worstRank = rank;
+    }
+  }
+  return worst;
+}
+
+/**
+ * One honest layer snapshot for voice/HUD narration.
+ *
+ * Disabled layers report `feedState: 'off'` — the same reading the chips use —
+ * even if leftover stats would otherwise classify as stale. Counts and errors
+ * still travel so a disabled layer with a last-known error is inspectable.
+ *
+ * @param {object} [layer] `DataLayerManager.getAll()` projection, or a layer-like
+ *   object with `id`, `enabled`, `stats`, and optional `source`/`name`.
+ * @param {{ now?: number }} [options]
+ * @returns {{
+ *   id: string|null,
+ *   name: string|null,
+ *   enabled: boolean,
+ *   feedState: string,
+ *   source: string|null,
+ *   count: number,
+ *   lastUpdate: number|null,
+ *   ageSec: number|null,
+ *   ageLabel: string|null,
+ *   error: string|null,
+ * }}
+ */
+export function layerSnapshot(layer = {}, { now = Date.now() } = {}) {
+  const stats = (layer && typeof layer.stats === 'object' && layer.stats) || {};
+  const source = String(stats.source || layer.source || '').trim() || null;
+  const enabled = Boolean(layer.enabled);
+  const countRaw = Number(stats.count);
+  const count = Number.isFinite(countRaw) ? countRaw : 0;
+  const lastUpdate = Number.isFinite(Number(stats.lastUpdate)) ? Number(stats.lastUpdate) : null;
+  const feedState = enabled ? layerFeedState({ ...stats, source }) : 'off';
+  return {
+    id: layer.id || layer.layerKey || null,
+    name: layer.name || layer.label || layer.id || layer.layerKey || null,
+    enabled,
+    feedState,
+    source,
+    count,
+    lastUpdate,
+    ageSec: snapshotAgeSec(lastUpdate, now),
+    ageLabel: snapshotAgeLabel(lastUpdate, now),
+    error: snapshotError(stats),
+  };
+}
+
+/**
+ * Snapshot every layer in a roster.
+ * @param {Array<object>} [layers]
+ * @param {{ now?: number }} [options]
+ * @returns {Array<object>}
+ */
+export function layerSnapshots(layers = [], options) {
+  if (!Array.isArray(layers)) return [];
+  return layers.map((layer) => layerSnapshot(layer, options));
+}
+
+function asSnapshot(entry, now) {
+  if (!entry || typeof entry !== 'object') return layerSnapshot({}, { now });
+  if (typeof entry.feedState === 'string') return entry;
+  return layerSnapshot(entry, { now });
+}
+
+/**
+ * Mechanical narration note so the model does not have to infer honesty.
+ * @param {Array<object>} layers Snapshots.
+ * @param {string|null} overall Worst considered feed-state.
+ * @returns {string}
+ */
+export function feedProvenanceNote(layers = [], overall = null) {
+  if (!overall) {
+    return 'No layer snapshot is attached. Do not invent a feed-state or a count.';
+  }
+  if (overall === 'nominal') {
+    return 'Queried enabled layers are nominal. Still name the count scope; do not claim whole-world coverage.';
+  }
+  if (overall === 'off') {
+    const names = layers.map((s) => s.name || s.id).filter(Boolean).join(', ') || 'the requested layer';
+    return `${names} is off. Do not invent a count; say the layer is off and offer to enable it.`;
+  }
+  const flagged = layers.filter((s) => (
+    s.feedState && s.feedState !== 'nominal' && s.feedState !== 'off'
+  ));
+  const bits = flagged.map((s) => {
+    const extras = [s.source, s.ageLabel || snapshotAgeLabel(s.lastUpdate), s.error]
+      .filter(Boolean)
+      .join(', ');
+    return `${s.name || s.id} is ${String(s.feedState).toUpperCase()}${extras ? ` (${extras})` : ''}`;
+  });
+  const body = bits.join('; ') || `${String(overall).toUpperCase()} feed`;
+  return `${body}. Narrate that provenance with any count; do not describe this as live.`;
+}
+
+/**
+ * Shared envelope stamped onto analyst, view-state, and HUD payloads.
+ * @param {Array<object>} [snapshots] Snapshots or raw `getAll()` rows.
+ * @param {{ now?: number }} [options]
+ * @returns {{ overall: string|null, layers: Array<object>, note: string }}
+ */
+export function feedProvenanceEnvelope(snapshots = [], { now = Date.now() } = {}) {
+  const layers = (Array.isArray(snapshots) ? snapshots : []).map((entry) => asSnapshot(entry, now));
+  const active = layers.filter((s) => s.feedState && s.feedState !== 'off');
+  const overall = worstFeedState(active.map((s) => s.feedState))
+    || (layers.length ? 'off' : null);
+  return {
+    overall,
+    layers,
+    note: feedProvenanceNote(layers, overall),
+  };
+}
+
+/**
+ * Compact voice-tool layer row: identity + the fields a model must read.
+ * @param {object} layer Raw `getAll()` row or snapshot.
+ * @param {{ now?: number }} [options]
+ * @returns {object}
+ */
+export function viewStateLayerRow(layer, options) {
+  const snap = layerSnapshot(layer, options);
+  return {
+    id: snap.id,
+    name: snap.name,
+    enabled: snap.enabled,
+    count: snap.count,
+    error: snap.error,
+    feedState: snap.feedState,
+    source: snap.source,
+    lastUpdate: snap.lastUpdate,
+  };
+}

src/data/layerSnapshot.test.mjs

@@ -0,0 +1,182 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import {
+  FEED_STATE_SEVERITY,
+  LAYER_FEED_STATE_LABELS,
+  LAYER_FEED_STATES,
+  SNAPSHOT_FEED_STATES,
+  feedProvenanceEnvelope,
+  feedProvenanceNote,
+  layerFeedState,
+  layerSnapshot,
+  layerSnapshots,
+  snapshotAgeLabel,
+  snapshotAgeSec,
+  viewStateLayerRow,
+  worstFeedState,
+} from './layerSnapshot.js';
+
+const NOW = 1_700_000_000_000;
+
+test('layerSnapshot stays Cesium-free so the HUD proxy can import it', () => {
+  const src = readFileSync(new URL('./layerSnapshot.js', import.meta.url), 'utf8');
+  assert.equal(src.includes("from './manager.js'"), false);
+  assert.doesNotMatch(src, /from ['"]cesium['"]/i);
+});
+
+test('layerFeedState matches the chip classifier for every honesty class', () => {
+  assert.equal(layerFeedState({ error: 'feed down', count: 0, lastUpdate: null }), 'unavailable');
+  assert.equal(layerFeedState({
+    status: 'unavailable',
+    error: 'feed down',
+    count: 50,
+    lastUpdate: 1,
+  }), 'unavailable');
+  assert.equal(layerFeedState({ mode: 'sim', count: 100, lastUpdate: 1 }), 'fallback');
+  assert.equal(layerFeedState({ source: 'adsb.lol', count: 10, lastUpdate: 1 }), 'fallback');
+  assert.equal(layerFeedState({
+    source: 'adsb.lol',
+    fallback: false,
+    count: 10,
+    lastUpdate: 1,
+  }), 'nominal');
+  assert.equal(layerFeedState({ stale: true, count: 0, lastUpdate: 1 }), 'stale');
+  assert.equal(layerFeedState({ error: 'partial group failure', count: 50, lastUpdate: 1 }), 'degraded');
+  assert.equal(layerFeedState({ loading: true }), 'loading');
+  assert.equal(layerFeedState({ count: 5, lastUpdate: 1 }), 'nominal');
+  assert.equal(layerFeedState({ status: 'zoom-in', error: 'zoom in to search', count: 12 }), 'nominal');
+  assert.equal(layerFeedState({ status: 'zoom-in', stale: true, count: 12 }), 'stale');
+});
+
+test('chip labels and severity cover every feed-state the envelope can emit', () => {
+  assert.deepEqual([...LAYER_FEED_STATES], [
+    'nominal', 'loading', 'degraded', 'stale', 'fallback', 'unavailable',
+  ]);
+  assert.deepEqual([...SNAPSHOT_FEED_STATES], [...LAYER_FEED_STATES, 'off']);
+  for (const state of LAYER_FEED_STATES) {
+    assert.equal(typeof LAYER_FEED_STATE_LABELS[state], 'string');
+    assert.equal(typeof FEED_STATE_SEVERITY[state], 'number');
+  }
+  assert.equal(FEED_STATE_SEVERITY.unavailable < FEED_STATE_SEVERITY.stale, true);
+  assert.equal(FEED_STATE_SEVERITY.stale < FEED_STATE_SEVERITY.fallback, true);
+  assert.equal(worstFeedState(['nominal', 'stale', 'fallback']), 'stale');
+  assert.equal(worstFeedState(['degraded', 'unavailable']), 'unavailable');
+  assert.equal(worstFeedState([]), null);
+});
+
+test('a disabled layer is off even when leftover stats would read stale', () => {
+  const snap = layerSnapshot({
+    id: 'flights',
+    name: 'Live Flights',
+    enabled: false,
+    source: 'OpenSky Network',
+    stats: { stale: true, count: 12, lastUpdate: NOW - 240_000, source: 'OpenSky Network' },
+  }, { now: NOW });
+  assert.equal(snap.feedState, 'off');
+  assert.equal(snap.enabled, false);
+  assert.equal(snap.count, 12);
+  assert.equal(snap.ageLabel, '4m ago');
+});
+
+test('an enabled stale layer carries age, source, and a mechanical note', () => {
+  const snap = layerSnapshot({
+    id: 'flights',
+    name: 'Live Flights',
+    enabled: true,
+    stats: {
+      stale: true,
+      count: 12,
+      lastUpdate: NOW - 240_000,
+      source: 'OpenSky Network',
+    },
+  }, { now: NOW });
+  assert.equal(snap.feedState, 'stale');
+  assert.equal(snap.source, 'OpenSky Network');
+  assert.equal(snap.ageSec, 240);
+  assert.equal(snap.ageLabel, '4m ago');
+  const envelope = feedProvenanceEnvelope([snap], { now: NOW });
+  assert.equal(envelope.overall, 'stale');
+  assert.match(envelope.note, /Live Flights is STALE/);
+  assert.match(envelope.note, /OpenSky Network/);
+  assert.match(envelope.note, /4m ago/);
+  assert.match(envelope.note, /do not describe this as live/i);
+});
+
+test('degraded and unavailable envelopes outrank leftover nominal neighbours', () => {
+  const layers = layerSnapshots([
+    {
+      id: 'earthquakes',
+      name: 'Earthquakes',
+      enabled: true,
+      stats: { count: 3, lastUpdate: NOW - 10_000 },
+    },
+    {
+      id: 'local-firms',
+      name: 'Active Fires',
+      enabled: true,
+      stats: { error: 'FIRMS key missing', count: 8, lastUpdate: NOW - 30_000 },
+    },
+  ], { now: NOW });
+  const envelope = feedProvenanceEnvelope(layers, { now: NOW });
+  assert.equal(envelope.overall, 'degraded');
+  assert.match(envelope.note, /Active Fires is DEGRADED/);
+  assert.match(envelope.note, /FIRMS key missing/);
+});
+
+test('an unavailable feed with no prior data does not become a confident zero', () => {
+  const snap = layerSnapshot({
+    id: 'ais-live-vessels',
+    name: 'Live Vessels',
+    enabled: true,
+    stats: { error: 'AISStream down', count: 0, lastUpdate: null },
+  }, { now: NOW });
+  assert.equal(snap.feedState, 'unavailable');
+  const envelope = feedProvenanceEnvelope([snap]);
+  assert.equal(envelope.overall, 'unavailable');
+  assert.match(envelope.note, /UNAVAILABLE/);
+});
+
+test('fallback provenance names the fallback source instead of calling it live', () => {
+  const snap = layerSnapshot({
+    id: 'flights',
+    name: 'Live Flights',
+    enabled: true,
+    stats: { source: 'adsb.lol fallback', count: 40, lastUpdate: NOW - 8_000 },
+  }, { now: NOW });
+  assert.equal(snap.feedState, 'fallback');
+  assert.match(feedProvenanceNote([snap], 'fallback'), /adsb\.lol fallback/);
+});
+
+test('view-state rows keep the existing identity fields and add feedState', () => {
+  const row = viewStateLayerRow({
+    id: 'flights',
+    name: 'Live Flights',
+    enabled: true,
+    stats: { count: 9, lastUpdate: 42, error: null, source: 'OpenSky Network' },
+  }, { now: NOW });
+  assert.deepEqual(row, {
+    id: 'flights',
+    name: 'Live Flights',
+    enabled: true,
+    count: 9,
+    error: null,
+    feedState: 'nominal',
+    source: 'OpenSky Network',
+    lastUpdate: 42,
+  });
+});
+
+test('empty roster envelope does not pretend to be nominal', () => {
+  const envelope = feedProvenanceEnvelope([]);
+  assert.equal(envelope.overall, null);
+  assert.match(envelope.note, /Do not invent/);
+});
+
+test('age labels match the Data Layers meta clock', () => {
+  assert.equal(snapshotAgeSec(null, NOW), null);
+  assert.equal(snapshotAgeLabel(NOW - 3_000, NOW), 'just now');
+  assert.equal(snapshotAgeLabel(NOW - 12_000, NOW), '12s ago');
+  assert.equal(snapshotAgeLabel(NOW - 240_000, NOW), '4m ago');
+  assert.equal(snapshotAgeLabel(NOW - 7_200_000, NOW), '2h ago');
+});

src/hud.js

@@ -20,7 +20,7 @@ import { CITY_POIS } from './locations.js';
 import { composeLocalityTag } from './hudLocality.js';
 import { ellipsoidalToMslDisplayM, ensureGeoidReady, geoidHeight } from './data/geoid.js';
 import { getBasemapLabelContext } from './voice/gevActions.js';
-import { isHudSummaryUnconfigured } from './hudSummaryResponse.js';
+import { hudSummaryLayerContext, hudTelemetryProvenanceTag, isHudSummaryUnconfigured } from './hudSummaryResponse.js';
 
 /** Color palettes keyed by shader mode; applied as CSS custom properties. */
 const HUD_COLORS = {
@@ -592,7 +592,9 @@ export class IntelHUD {
     // NEAR the nearest catalogued POI at metro range; otherwise the lat/lon sector.
     const localityTag = composeLocalityTag(nearest, m.latDeg, m.lonDeg);
 
-    return `${modeLabel} ${band} ${localityTag} | ${region} | ALT ${altTag} | WINDOW ${winTag} | SUN ${m.sunEl.toFixed(0)}° | ONA ${m.ona.toFixed(0)}° | ${localTag}`;
+    const provenance = hudTelemetryProvenanceTag(this._dataManager?.getAll?.() || []);
+    const line = `${modeLabel} ${band} ${localityTag} | ${region} | ALT ${altTag} | WINDOW ${winTag} | SUN ${m.sunEl.toFixed(0)}° | ONA ${m.ona.toFixed(0)}° | ${localTag}`;
+    return provenance ? `${line} | ${provenance}` : line;
   }
 
   /**
@@ -710,6 +712,7 @@ export class IntelHUD {
       streetLabels: labels.streetLabels,
       nearbyPlaceLabels: labels.nearbyPlaceLabels,
       enabledLayerLabels: enabledLayers,
+      ...hudSummaryLayerContext(this._dataManager?.getAll?.() || []),
     };
   }
 
@@ -839,7 +842,7 @@ export class IntelHUD {
     this._dataManager = dataManager || null;
     if (typeof this._dataManager?.subscribe === 'function') {
       this._dataManagerUnsubscribe = this._dataManager.subscribe((change) => {
-        if (change?.type === 'visibility') this._markSummaryDirty();
+        if (['visibility', 'refresh-transition', 'refresh-cancelled'].includes(change?.type)) this._markSummaryDirty();
       });
     }
     this._markSummaryDirty();

src/hudSummaryResponse.js

@@ -1,3 +1,8 @@
+import {
+  feedProvenanceEnvelope,
+  layerSnapshots,
+} from './data/layerSnapshot.js';
+
 export const HUD_SUMMARY_UNCONFIGURED_CODE = 'OPENAI_NOT_CONFIGURED';
 
 /**
@@ -33,3 +38,60 @@ export function isHudSummaryUnconfigured(status, data) {
     && data?.error === null
     && data?.summary === null;
 }
+
+/**
+ * HUD summary model instructions. The five-word line may only describe
+ * supplied labels, and must carry feed-state when any enabled layer is not
+ * nominal.
+ */
+export const HUD_SUMMARY_INSTRUCTIONS = [
+  "Write one concise intelligence-HUD summary for God's Eye View.",
+  'Use only the supplied place, street, nearby-place, enabled-layer labels, and feedProvenance.',
+  'Prefer the clearest named place and include a relevant enabled layer only when useful.',
+  'If any enabled layer is not nominal, the five words MUST include that feedState token (STALE, DEGRADED, FALLBACK, LOADING, or UNAVAILABLE) and must not present the view as live.',
+  'Do not infer from coordinates or invent a place or feed state.',
+  'Output exactly five words with no title, punctuation, markdown, or introductory phrase.',
+].join(' ');
+
+/**
+ * Stamp HUD summary context with the same layer snapshots voice tools use.
+ * @param {Array<object>} [layers] `DataLayerManager.getAll()` rows.
+ * @param {{ now?: number }} [options]
+ * @returns {{
+ *   enabledLayerLabels: string[],
+ *   enabledLayers: Array<{id: string|null, name: string|null, feedState: string, source: string|null, count: number}>,
+ *   feedProvenance: object,
+ * }}
+ */
+export function hudSummaryLayerContext(layers = [], options) {
+  const snapshots = layerSnapshots(layers, options).filter((s) => s.enabled);
+  const envelope = feedProvenanceEnvelope(snapshots, options);
+  return {
+    enabledLayerLabels: snapshots.map((s) => s.name).filter(Boolean),
+    enabledLayers: snapshots.map((s) => ({
+      id: s.id,
+      name: s.name,
+      feedState: s.feedState,
+      source: s.source,
+      count: s.count,
+    })),
+    feedProvenance: envelope,
+  };
+}
+
+/**
+ * Deterministic telemetry suffix when an enabled feed is not nominal.
+ * @param {Array<object>} [layers]
+ * @param {{ now?: number }} [options]
+ * @returns {string|null}
+ */
+export function hudTelemetryProvenanceTag(layers = [], options) {
+  const snapshots = layerSnapshots(layers, options).filter((s) => s.enabled);
+  const envelope = feedProvenanceEnvelope(snapshots, options);
+  if (!envelope.overall || envelope.overall === 'nominal') return null;
+  const names = envelope.layers
+    .filter((s) => s.feedState && s.feedState !== 'nominal' && s.feedState !== 'off')
+    .map((s) => String(s.name || s.id || 'LAYER').toUpperCase())
+    .slice(0, 2);
+  return `${envelope.overall.toUpperCase()}${names.length ? ` ${names.join('/')}` : ''}`;
+}

src/hudSummaryResponse.test.mjs

@@ -1,7 +1,11 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
+import { readFileSync } from 'node:fs';
 import {
+  HUD_SUMMARY_INSTRUCTIONS,
   HUD_SUMMARY_UNCONFIGURED_CODE,
+  hudSummaryLayerContext,
+  hudTelemetryProvenanceTag,
   isHudSummaryUnconfigured,
   keylessHudSummaryResponse,
 } from './hudSummaryResponse.js';
@@ -128,3 +132,41 @@ test('the installed keyless HUD route stays successful after the voice quota is
     else process.env.GEV_RATELIMIT_OPENAI_PER_MIN = previousLimit;
   }
 });
+
+test('HUD summary context and telemetry tag carry chip-identical feed-state', () => {
+  const now = 1_000_000;
+  const layers = [
+    {
+      id: 'flights',
+      name: 'Live Flights',
+      enabled: true,
+      stats: { stale: true, count: 12, lastUpdate: now - 240_000, source: 'OpenSky Network' },
+    },
+    {
+      id: 'earthquakes',
+      name: 'Earthquakes',
+      enabled: false,
+      stats: { count: 3, lastUpdate: now },
+    },
+  ];
+  const context = hudSummaryLayerContext(layers, { now });
+  assert.deepEqual(context.enabledLayerLabels, ['Live Flights']);
+  assert.equal(context.enabledLayers[0].feedState, 'stale');
+  assert.equal(context.feedProvenance.overall, 'stale');
+  assert.equal(hudTelemetryProvenanceTag(layers, { now }), 'STALE LIVE FLIGHTS');
+  assert.equal(hudTelemetryProvenanceTag([{
+    id: 'flights', name: 'Live Flights', enabled: true, stats: { count: 4, lastUpdate: now },
+  }], { now }), null);
+});
+
+test('HUD summary instructions require non-nominal feedState in the five words', () => {
+  assert.match(HUD_SUMMARY_INSTRUCTIONS, /five words MUST include that feedState token/);
+  assert.match(HUD_SUMMARY_INSTRUCTIONS, /STALE, DEGRADED, FALLBACK, LOADING, or UNAVAILABLE/);
+  assert.match(HUD_SUMMARY_INSTRUCTIONS, /feedProvenance/);
+});
+
+test('the HUD proxy uses the shared provenance instructions', () => {
+  const local = readFileSync(new URL('../server/providers/openai/hud-summary.js', import.meta.url), 'utf8');
+  assert.match(local, /HUD_SUMMARY_INSTRUCTIONS/);
+  assert.doesNotMatch(local, /enabled-layer text labels/);
+});

src/voice/gevActions.js

@@ -1,3 +1,4 @@
+import { layerSnapshot, layerSnapshots, feedProvenanceEnvelope } from '../data/layerSnapshot.js';
 import { readLayerLifecycleSummary } from './layerSummary.js';
 export { readLayerLifecycleSummary } from './layerSummary.js';
 import { defaultGeospatial } from '../search/defaults.js';
@@ -2352,7 +2353,11 @@ function getCurrentViewState(viewer, styleManager, dataManager, sceneDirector =
       enabled: layer.enabled,
       count: layer.stats?.count || 0,
       error: layer.stats?.error || null,
+      feedState: layerSnapshot(layer).feedState,
+      source: layerSnapshot(layer).source,
+      lastUpdate: layerSnapshot(layer).lastUpdate,
     })),
+    feedProvenance: feedProvenanceEnvelope(layerSnapshots(dataManager.getAll()).filter((layer) => layer.enabled)),
   };
 }
 
@@ -3253,6 +3258,12 @@ function analystProviders(viewer, dataManager, { recordLimitByLayer = null, plac
         ? (mod.getAnalystRecords(requestedLimit) || [])
         : (mod.getAnalystRecords() || []);
     },
+    getLayerSnapshot(layerKey) {
+      const row = dataManager.getAll?.().find((layer) => layer.id === layerKey);
+      if (row) return layerSnapshot(row);
+      const module = dataManager.layers?.get(layerKey)?.module;
+      return layerSnapshot({ id: layerKey, enabled: dataManager.isEnabled?.(layerKey), stats: module?.getStats?.() || {} });
+    },
     getRecordCoverage(layerKey, rows) {
       if (!['satellites', 'local-datacenters', 'local-dams'].includes(layerKey)) return null;
       const module = dataManager.layers.get(layerKey)?.module;
@@ -3353,7 +3364,10 @@ async function runAnalystQuery(analystEngine, dataManager, args = {}, _layerEnab
   // arbitrary points — only "how many aircraft around <this contact>" is
   // unified, because that is the question the panel is already answering.
   const entityWindow = aircraftProximityWindowForQuery(dataManager, args, result);
-  if (entityWindow) return entityWindow;
+  if (entityWindow) {
+    const provenance = feedProvenanceEnvelope(layerSnapshots(dataManager.getAll?.() || []).filter((layer) => layer.enabled && ['flights', 'military'].includes(layer.id)));
+    return { ...entityWindow, feedProvenance: provenance, feedState: provenance.overall };
+  }
 
   const contactsWindow = activeContactsWindow(dataManager);
   const aircraftQueried = (result.coverage?.layersQueried || [])
@@ -3385,6 +3399,8 @@ async function runAnalystQuery(analystEngine, dataManager, args = {}, _layerEnab
     items,
     summary: result.summary,
     coverage: result.coverage,
+    feedProvenance: result.coverage?.feedProvenance || null,
+    feedState: result.coverage?.feedProvenance?.overall || null,
     // The panel's own numbers, carried so the answer can match what the
     // operator is looking at regardless of how the model reads the note.
     // Flattened alongside the object so the count and its subject cannot be

src/voice/gevActions.test.mjs

@@ -3182,3 +3182,66 @@ test('ISS voice lookup uses the registered satellite instance', async () => {
   assert.deepEqual(calls, [{ latDeg: 30, lonDeg: -97, minElevDeg: 15 }]);
   assert.match(result.error, /No ISS pass above 15/);
 });
+
+test('analyst_query and get_current_view_state carry stale feed provenance', async () => {
+  globalThis.window = globalThis.window || { clearTimeout, setTimeout, requestIdleCallback: null };
+  const now = Date.now();
+  const flights = {
+    id: 'flights',
+    source: 'OpenSky Network',
+    getStats: () => ({
+      source: 'OpenSky Network',
+      stale: true,
+      count: 12,
+      lastUpdate: now - 240_000,
+    }),
+    getAnalystRecords: () => ([
+      { id: 'SWA1', icao24: 'aaa001', lat: 30.27, lon: -97.74, altitudeM: 11000, onGround: false },
+    ]),
+  };
+  const viewer = {
+    clock: { onTick: { addEventListener: () => () => {} } },
+    scene: { canvas: { addEventListener() {}, removeEventListener() {} } },
+    camera: {
+      moveEnd: { addEventListener() {} },
+      positionWC: Cesium.Cartesian3.fromDegrees(-97.7, 30.2, 1000),
+      positionCartographic: { height: 300_000, latitude: 0.52, longitude: -1.71 },
+    },
+  };
+  const dataManager = {
+    layers: new Map([['flights', { module: flights }]]),
+    isEnabled: (id) => id === 'flights',
+    getAll: () => [{
+      id: 'flights',
+      name: 'Live Flights',
+      enabled: true,
+      source: 'OpenSky Network',
+      stats: flights.getStats(),
+    }],
+  };
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager: {
+      activeStyle: 'normal',
+      getContextModeState: () => ({ mode: null, active: false }),
+      getCockpitState: () => ({ active: false }),
+      getControlState: () => null,
+    },
+    dataManager,
+  });
+  const view = await runner('get_current_view_state');
+  assert.equal(view.layers[0].feedState, 'stale');
+  assert.equal(view.feedProvenance.overall, 'stale');
+  assert.match(view.feedProvenance.note, /STALE/);
+
+  const query = await runner('analyst_query', {
+    layers: ['flights'],
+    scope: { kind: 'view' },
+    limit: 5,
+  });
+  assert.equal(query.ok, true);
+  assert.equal(query.feedState, 'stale');
+  assert.equal(query.feedProvenance.overall, 'stale');
+  assert.equal(query.coverage.layersQueried[0].feedState, 'stale');
+  assert.match(query.feedProvenance.note, /do not describe this as live/i);
+});