Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

Count Store and model-list reach only when a person opens them (#1325)

0xken15939a4af88c03
diff --git a/backend/src/analytics/dailyProductReview.test.ts b/backend/src/analytics/dailyProductReview.test.ts
index ea79270dc..e4536178c 100644
--- a/backend/src/analytics/dailyProductReview.test.ts
+++ b/backend/src/analytics/dailyProductReview.test.ts
@@ -82,3 +82,15 @@ it('reports a read the apps make on their own as reliability only, even from cli
installationDays: null, firstMeasuredInstallations: null, repeatInstallationDays: null })
expect(r.features.find(f => f.action === 'search')).toMatchObject({ automatic: false, installationDays: 19 })
})
+
+it('reads Store and model-list reach only from the requests a person opened', () => {
+ const r = dailyProductReview([
+ row('2026-10-12', 'store_list_requests', 1965), row('2026-10-12', 'store_list_installation_days', 22),
+ row('2026-10-12', 'store_list_user_requests', 9), row('2026-10-12', 'store_list_user_installation_days', 4),
+ row('2026-10-12', 'store_list_user_first_installations', 3), row('2026-10-12', 'store_list_user_repeat_installation_days', 1),
+ ], new Date('2026-10-13'))
+ expect(r.features.find(f => f.action === 'store_list')).toMatchObject({ requests: 1965, automatic: true, userRequests: 9,
+ installationDays: 4, firstMeasuredInstallations: 3, repeatInstallationDays: 1 })
+ expect(r.features.find(f => f.action === 'model_list')).toMatchObject({ userRequests: 0, installationDays: null })
+ expect(r.features.find(f => f.action === 'history')).toMatchObject({ userRequests: null, installationDays: null })
+})
diff --git a/backend/src/analytics/dailyProductReview.ts b/backend/src/analytics/dailyProductReview.ts
index 155a7d914..2a11171c9 100644
--- a/backend/src/analytics/dailyProductReview.ts
+++ b/backend/src/analytics/dailyProductReview.ts
@@ -1,4 +1,4 @@
-import { PRODUCT_FEEDBACK, PRODUCT_FEEDBACK_REASONS, PRODUCT_FEEDBACK_OUTCOMES, PRODUCT_USAGE_ACTIONS, PRODUCT_USAGE_AUTOMATIC_ACTIONS, PRODUCT_USAGE_FLOWS, PRODUCT_USAGE_SURFACES } from '../types/productUsage.js'
+import { PRODUCT_FEEDBACK, PRODUCT_FEEDBACK_REASONS, PRODUCT_FEEDBACK_OUTCOMES, PRODUCT_USAGE_ACTIONS, PRODUCT_USAGE_AUTOMATIC_ACTIONS, PRODUCT_USAGE_FLOWS, PRODUCT_USAGE_SURFACES, PRODUCT_USAGE_USER_OPENED_ACTIONS } from '../types/productUsage.js'
import { DAILY_PRODUCT_METRICS } from './dailyProductUsage.js'
type Row = { dayUtc: Date; metric: string; value: number }
@@ -125,14 +125,20 @@ export function dailyProductReview(rows: Row[], now: Date) {
interpretation: 'Post-sign-in first-use signals; these stage counts are not one signup cohort or a signup conversion rate. Already installed clients enter measurement when updated.' },
feedback: Object.fromEntries(PRODUCT_FEEDBACK.map(answer => [answer, c[`feedback_${answer}`] ?? 0])),
features: PRODUCT_USAGE_ACTIONS.map(action => {
- // The apps make these reads on their own; clients before the split still send their reach.
+ // The apps make these reads on their own; clients before the split still send their reach. The
+ // Store and model lists are also opened by people, and only those requests carry reach (`_user_`).
const automatic = PRODUCT_USAGE_AUTOMATIC_ACTIONS.includes(action)
- const reach = (measure: string) => automatic ? null : c[`${action}_${measure}`] ?? null
+ const opened = (PRODUCT_USAGE_USER_OPENED_ACTIONS as readonly string[]).includes(action)
+ const reach = (measure: string) => opened ? c[`${action}_user_${measure}`] ?? null
+ : automatic ? null : c[`${action}_${measure}`] ?? null
return { action, automatic, requests: c[`${action}_requests`] ?? 0,
+ userRequests: opened ? c[`${action}_user_requests`] ?? 0 : null,
installationDays: reach('installation_days'),
firstMeasuredInstallations: reach('first_installations'),
repeatInstallationDays: reach('repeat_installation_days'),
- interpretation: automatic
+ interpretation: opened
+ ? 'Also requested by the apps on their own: requests are reliability only. userRequests and reach count only a person opening the list (apps that mark it); reach is installation-days, a lower bound.'
+ : automatic
? 'Requested by the apps on their own (after updates, on connect, for previews): reliability and latency only, not feature use.'
: 'An operation was requested, possibly automatically. Reach is installation-days, not unique people, UI clicks or successful feature use.',
}
diff --git a/backend/src/types/productUsage.ts b/backend/src/types/productUsage.ts
index fdc70df0f..28ad0d5c5 100644
--- a/backend/src/types/productUsage.ts
+++ b/backend/src/types/productUsage.ts
@@ -13,6 +13,10 @@ export const PRODUCT_USAGE_ACTIONS = ['create', 'resume', 'restart', 'model_chan
* lists on connect, picker previews): measured for reliability, never as a feature someone used. */
export const PRODUCT_USAGE_AUTOMATIC_ACTIONS: readonly typeof PRODUCT_USAGE_ACTIONS[number][] = ['history', 'history_page', 'store_list', 'model_list']
export const PRODUCT_USAGE_FEATURE_MEASURES = ['installation_days', 'first_installations', 'repeat_installation_days'] as const
+/** Of those, the lists a person also opens (the Store, a model list): the request that opening sends
+ * carries `userAction: true`, and only it counts their reach, under its own `_user_` names, because
+ * clients released before the split still send the plain names for every automatic read. */
+export const PRODUCT_USAGE_USER_OPENED_ACTIONS = ['store_list', 'model_list'] as const satisfies typeof PRODUCT_USAGE_AUTOMATIC_ACTIONS
export const PRODUCT_USAGE_SURFACES = ['desktop', 'phone', 'web'] as const
export const PRODUCT_USAGE_FLOWS = ['setup', 'setup_harness', 'setup_tmux', 'setup_clipboard', 'sign_in',
'workspace_connect', 'computer_link', 'remote_connect', 'viewer_open', 'update_check', 'update_stage', ...HEALTH_FLOWS] as const
@@ -51,6 +55,8 @@ export const PRODUCT_USAGE_METRICS = [
...PRODUCT_FEEDBACK.map(answer => `feedback_${answer}` as const),
...PRODUCT_USAGE_ACTIONS.flatMap(action => PRODUCT_USAGE_ACTION_MEASURES.map(measure => `${action}_${measure}` as const)),
...PRODUCT_USAGE_ACTIONS.flatMap(action => PRODUCT_USAGE_FEATURE_MEASURES.map(measure => `${action}_${measure}` as const)),
+ ...PRODUCT_USAGE_USER_OPENED_ACTIONS.flatMap(action => (['requests', ...PRODUCT_USAGE_FEATURE_MEASURES] as const)
+ .map(measure => `${action}_user_${measure}` as const)),
...PRODUCT_USAGE_UI_METRICS,
] as const
export type ProductUsageMetric = typeof PRODUCT_USAGE_METRICS[number]
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.ts
index 6caa61b22..56c44c04a 100644
--- a/cli/src/backendSocket.ts
+++ b/cli/src/backendSocket.ts
@@ -827,7 +827,8 @@ export class BackendSocket {
const launchMeasured = productUsageLaunch(type, (frame.payload as { creationId?: unknown } | undefined)?.creationId,
signal => this.toGateway('usage', gateway => gateway.usageLaunch?.(signal)))
const usageSource = local && connId && this.toolClients.has(connId) ? 'tool' : local || role === 'web' ? 'app' : 'unknown'
- const measured = productUsageRequest(type, (metric) => this.toGateway('usage', (gateway) => gateway.usageCounter?.(metric)), Date.now, usageSource)
+ const measured = productUsageRequest(type, (metric) => this.toGateway('usage', (gateway) => gateway.usageCounter?.(metric)), Date.now, usageSource,
+ (frame.payload as { userAction?: unknown } | undefined)?.userAction === true)
productUsageIntent(type, (frame.payload as { usageIntent?: unknown } | undefined)?.usageIntent,
(frame.payload as { agentId?: unknown } | undefined)?.agentId, usageSource,
signal => this.toGateway('usage', gateway => gateway.usageLaunch?.(signal)))
diff --git a/cli/src/gateway/productUsage.spec.ts b/cli/src/gateway/productUsage.spec.ts
index 3030084a3..0dbe5c288 100644
--- a/cli/src/gateway/productUsage.spec.ts
+++ b/cli/src/gateway/productUsage.spec.ts
@@ -229,6 +229,20 @@ it('counts a read the apps make on their own for reliability only, never as a fe
search_requests: 1, search_installation_days: 1, search_first_installations: 1 })
})
+it('counts the Store or a model list as used only when a person opened it, once a day', async () => {
+ await usage.sync()
+ usage.counter('store_list_requests'); usage.counter('store_list_user_requests'); usage.counter('store_list_user_requests')
+ await usage.sync()
+ expect(totals()).toEqual({ measurement_v2_installation_days: 1, store_list_requests: 1, store_list_user_requests: 2,
+ store_list_user_installation_days: 1, store_list_user_first_installations: 1 })
+ now += 86400000; await usage.stop(); usage = createProductUsage({ file, now: () => now, request }); await usage.sync()
+ usage.counter('store_list_user_requests'); usage.counter('model_list_user_requests')
+ await usage.sync()
+ expect(totals()).toMatchObject({ store_list_user_installation_days: 2, store_list_user_repeat_installation_days: 1,
+ store_list_user_first_installations: 1, model_list_user_first_installations: 1 })
+ expect(totals()).not.toHaveProperty('store_list_installation_days')
+})
+
it('tracks a durable launch through polls without persisting its receipt or counting polls as attempts', async () => {
await usage.sync()
const id = 'PRIVATE_CREATION_CANARY'
diff --git a/cli/src/gateway/productUsage.ts b/cli/src/gateway/productUsage.ts
index b78668afa..2ae0df635 100644
--- a/cli/src/gateway/productUsage.ts
+++ b/cli/src/gateway/productUsage.ts
@@ -6,6 +6,7 @@ import { dirname } from 'node:path'
import { randomUUID } from 'node:crypto'
import type { ProductUsageLaunchSignal } from '../lib/productUsageSignals.js'
import { PRODUCT_USAGE_ACTIONS, PRODUCT_USAGE_AUTOMATIC_ACTIONS, PRODUCT_USAGE_DAYS, PRODUCT_USAGE_MAX_COUNT, PRODUCT_USAGE_METRICS,
+ PRODUCT_USAGE_USER_OPENED_ACTIONS,
type ProductUsageChoice, type ProductUsageMetric, type ProductUsageReport } from '../lib/productUsageContract.js'
const DAY = 86_400_000
@@ -13,9 +14,14 @@ const MAX_QUEUE_BYTES = 256 * 1024
// A report stays below the server's 8 KiB body bound even with the complete vocabulary.
const MAX_REPORT_METRICS = 64
const metricSet = new Set<string>(PRODUCT_USAGE_METRICS)
-// Feature reach is a person's use; the reads the apps make on their own count only their reliability.
-const requestActions = new Map(PRODUCT_USAGE_ACTIONS.filter(action => !PRODUCT_USAGE_AUTOMATIC_ACTIONS.includes(action))
- .map(action => [`${action}_requests`, action]))
+// Feature reach is a person's use; the reads the apps make on their own count only their reliability,
+// unless the app says a person opened that list (`<action>_user_requests`, its own first/repeat).
+type Reach = typeof PRODUCT_USAGE_ACTIONS[number] | `${typeof PRODUCT_USAGE_USER_OPENED_ACTIONS[number]}_user`
+const REACHES: readonly Reach[] = [...PRODUCT_USAGE_ACTIONS, ...PRODUCT_USAGE_USER_OPENED_ACTIONS.map(action => `${action}_user` as const)]
+const requestActions = new Map<string, Reach>([
+ ...PRODUCT_USAGE_ACTIONS.filter(action => !PRODUCT_USAGE_AUTOMATIC_ACTIONS.includes(action)).map(action => [`${action}_requests`, action] as const),
+ ...PRODUCT_USAGE_USER_OPENED_ACTIONS.map(action => [`${action}_user_requests`, `${action}_user`] as const),
+])
const key = (now: number) => new Date(now).toISOString().slice(0, 10)
const week = (now: number) => { const d = new Date(now); return key(now - ((d.getUTCDay() + 6) % 7) * DAY) }
type Counters = Partial<Record<ProductUsageMetric, number>>
@@ -29,8 +35,8 @@ interface State {
workWeek: string | null
workMonth: string | null
measurementDay: string | null
- featureDays: Partial<Record<typeof PRODUCT_USAGE_ACTIONS[number], string>>
- featuresUsed: typeof PRODUCT_USAGE_ACTIONS[number][]
+ featureDays: Partial<Record<Reach, string>>
+ featuresUsed: Reach[]
workedBefore: boolean
respondedBefore: boolean
launchedBefore: boolean
@@ -80,7 +86,7 @@ export function createProductUsage(deps: ProductUsageDeps) {
if (typeof saved[field] === 'string' && validDay(saved[field]!)) state[field] = saved[field]
}
if (typeof saved.workMonth === 'string' && /^\d{4}-\d{2}$/.test(saved.workMonth)) state.workMonth = saved.workMonth
- for (const action of PRODUCT_USAGE_ACTIONS) {
+ for (const action of REACHES) {
if (validDay(saved.featureDays?.[action] ?? '')) state.featureDays[action] = saved.featureDays![action]
if (saved.featuresUsed?.includes(action)) state.featuresUsed.push(action)
}
@@ -128,7 +134,7 @@ export function createProductUsage(deps: ProductUsageDeps) {
for (const field of ['activeDay', 'workDay', 'workWeek', 'measurementDay'] as const) if (state[field] && !validDay(state[field]!)) state[field] = null
for (const day of Object.keys(state.days)) if (!validDay(day)) delete state.days[day]
for (const day of Object.keys(state.dayContexts)) if (!state.days[day]) delete state.dayContexts[day]
- for (const action of PRODUCT_USAGE_ACTIONS) if (!validDay(state.featureDays[action] ?? '')) delete state.featureDays[action]
+ for (const action of REACHES) if (!validDay(state.featureDays[action] ?? '')) delete state.featureDays[action]
state.workDays = state.workDays.filter(validDay)
if (state.firstLaunchAt !== null && !validDay(key(state.firstLaunchAt))) state.firstLaunchAt = null
if (state.pending && !validDay(state.pending.day)) state.pending = null
diff --git a/cli/src/lib/productUsageContract.ts b/cli/src/lib/productUsageContract.ts
index fdc70df0f..28ad0d5c5 100644
--- a/cli/src/lib/productUsageContract.ts
+++ b/cli/src/lib/productUsageContract.ts
@@ -13,6 +13,10 @@ export const PRODUCT_USAGE_ACTIONS = ['create', 'resume', 'restart', 'model_chan
* lists on connect, picker previews): measured for reliability, never as a feature someone used. */
export const PRODUCT_USAGE_AUTOMATIC_ACTIONS: readonly typeof PRODUCT_USAGE_ACTIONS[number][] = ['history', 'history_page', 'store_list', 'model_list']
export const PRODUCT_USAGE_FEATURE_MEASURES = ['installation_days', 'first_installations', 'repeat_installation_days'] as const
+/** Of those, the lists a person also opens (the Store, a model list): the request that opening sends
+ * carries `userAction: true`, and only it counts their reach, under its own `_user_` names, because
+ * clients released before the split still send the plain names for every automatic read. */
+export const PRODUCT_USAGE_USER_OPENED_ACTIONS = ['store_list', 'model_list'] as const satisfies typeof PRODUCT_USAGE_AUTOMATIC_ACTIONS
export const PRODUCT_USAGE_SURFACES = ['desktop', 'phone', 'web'] as const
export const PRODUCT_USAGE_FLOWS = ['setup', 'setup_harness', 'setup_tmux', 'setup_clipboard', 'sign_in',
'workspace_connect', 'computer_link', 'remote_connect', 'viewer_open', 'update_check', 'update_stage', ...HEALTH_FLOWS] as const
@@ -51,6 +55,8 @@ export const PRODUCT_USAGE_METRICS = [
...PRODUCT_FEEDBACK.map(answer => `feedback_${answer}` as const),
...PRODUCT_USAGE_ACTIONS.flatMap(action => PRODUCT_USAGE_ACTION_MEASURES.map(measure => `${action}_${measure}` as const)),
...PRODUCT_USAGE_ACTIONS.flatMap(action => PRODUCT_USAGE_FEATURE_MEASURES.map(measure => `${action}_${measure}` as const)),
+ ...PRODUCT_USAGE_USER_OPENED_ACTIONS.flatMap(action => (['requests', ...PRODUCT_USAGE_FEATURE_MEASURES] as const)
+ .map(measure => `${action}_user_${measure}` as const)),
...PRODUCT_USAGE_UI_METRICS,
] as const
export type ProductUsageMetric = typeof PRODUCT_USAGE_METRICS[number]
diff --git a/cli/src/lib/productUsageSignals.spec.ts b/cli/src/lib/productUsageSignals.spec.ts
index 777b02d81..f99b23bba 100644
--- a/cli/src/lib/productUsageSignals.spec.ts
+++ b/cli/src/lib/productUsageSignals.spec.ts
@@ -65,3 +65,16 @@ it('observes Store, search and model operations without their arguments and reje
productUsageRequest('terminal_input', emit, clock)
expect(clock).not.toHaveBeenCalled()
})
+
+it('marks a Store or model list a person opened, and only those', () => {
+ const emit = vi.fn()
+ productUsageRequest('dsh_list', emit, Date.now, 'app', true)(undefined, undefined, false)
+ productUsageRequest('grid_models_list', emit, Date.now, 'app', true)(undefined, undefined, false)
+ expect(emit.mock.calls.flat()).toEqual(expect.arrayContaining(['store_list_user_requests', 'model_list_user_requests']))
+ emit.mockClear()
+ // The Store's minute refresh, the pickers and the previews send no flag; history has no person behind it.
+ productUsageRequest('dsh_list', emit)(undefined, undefined, false)
+ productUsageRequest('agent_recent', emit, Date.now, 'app', true)(undefined, undefined, false)
+ productUsageRequest('session_tail', emit, Date.now, 'app', true)(undefined, undefined, false)
+ expect(emit.mock.calls.flat().filter(m => String(m).includes('_user_'))).toEqual([])
+})
diff --git a/cli/src/lib/productUsageSignals.ts b/cli/src/lib/productUsageSignals.ts
index 85be77fb4..389025045 100644
--- a/cli/src/lib/productUsageSignals.ts
+++ b/cli/src/lib/productUsageSignals.ts
@@ -1,5 +1,5 @@
import type { HealthSource } from './productHealthContract.js'
-import type { ProductUsageMetric } from './productUsageContract.js'
+import { PRODUCT_USAGE_USER_OPENED_ACTIONS, type ProductUsageMetric } from './productUsageContract.js'
const actions = { agent_create: 'create', agent_resume: 'resume', agent_restart: 'restart',
agent_retarget: 'model_change', agent_recent: 'history',
@@ -55,8 +55,10 @@ export function productUsageLaunch(type: string, id: unknown, emit: (signal: Pro
* No request, reply, error message, path, agent name or identifier is handed to the collector.
* A pending durable launch is an acknowledgement, never a successful launch. Status polling is
* excluded: counting each poll as a launch would turn a slow install into hundreds of attempts.
+ * [userAction] is the app saying a person opened the list (the Store, a model list); the same request
+ * from a refresh, a probe or a picker carries none, and only the flagged one counts toward reach.
*/
-export function productUsageRequest(type: string, emit: (metric: ProductUsageMetric) => void, now = Date.now, source?: HealthSource) {
+export function productUsageRequest(type: string, emit: (metric: ProductUsageMetric) => void, now = Date.now, source?: HealthSource, userAction = false) {
const action = type === 'message' ? 'message' : Object.hasOwn(actions, type) ? actions[type as keyof typeof actions] : null
// In particular, streaming frames and polling do not allocate clocks or observers.
if (!action) return unmeasured
@@ -66,6 +68,7 @@ export function productUsageRequest(type: string, emit: (metric: ProductUsageMet
const count = (measure: string) => { if (action && action !== 'message') { try { emit(`${action}_${measure}` as ProductUsageMetric) } catch { /* Optional measurement. */ } } }
const detail = (measure: string) => { if (!source) return; try { emit(`request_${origin}_${action}_${measure}` as ProductUsageMetric) } catch { /* Optional measurement. */ } }
count('requests'); detail('started')
+ if (userAction && (PRODUCT_USAGE_USER_OPENED_ACTIONS as readonly string[]).includes(action)) count('user_requests')
return (error: unknown, state: unknown, hasAgent: boolean, ok?: unknown) => {
if (!action || answered) return
answered = true
diff --git a/desktop/lib/screens/swarm_screen.dart b/desktop/lib/screens/swarm_screen.dart
index fe5b5291c..656f1347e 100644
--- a/desktop/lib/screens/swarm_screen.dart
+++ b/desktop/lib/screens/swarm_screen.dart
@@ -5418,6 +5418,7 @@ class _SwarmScreenState extends State<SwarmScreen> {
_onboarding.acknowledge(OnboardingStep.models);
app.modelManager.setPanelVisible(true);
unawaited(app.modelManager.dismissIntroduction());
+ app.markModelsOpened();
unawaited(app.modelManager.refresh());
unawaited(_modelsMenu!.refresh());
_modelsOverlay = OverlayEntry(
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index 1c2877735..fa22403db 100644
--- a/desktop/lib/state/app_state.dart
+++ b/desktop/lib/state/app_state.dart
@@ -1723,6 +1723,7 @@ class AppNotifier extends ChangeNotifier {
if (harness != null) notifyListeners();
return;
}
+ _storeOpenedByPerson = true;
final existing = swarms.where((swarm) => swarm.isStore).firstOrNull;
if (existing != null) {
selectSwarm(existing.id);
@@ -1751,6 +1752,17 @@ class AppNotifier extends ChangeNotifier {
String? _pendingStoreHarness;
+ /// A person opened the Store ([openStore]), not a tab restored at launch: the Store tab's first ask
+ /// takes it ([takeStoreOpened]) and marks its `dsh_list` as theirs, all the Store's reach counts
+ /// (`store_list_user_*`). Its minute refresh and reconnect asks carry no mark.
+ bool _storeOpenedByPerson = false;
+
+ bool takeStoreOpened() {
+ final opened = _storeOpenedByPerson;
+ _storeOpenedByPerson = false;
+ return opened;
+ }
+
/// Devices is a regular workspace on the desktop app. A browser or a viewer
/// build has no device on its desk to manage.
bool get devicesEnabled => !kIsWeb && !kViewerMode;
@@ -9207,8 +9219,21 @@ class AppNotifier extends ChangeNotifier {
///
/// Never throws — a machine whose daemon is too old to know the RPC, one with no grid, and one
/// that timed out are all "nothing to offer", which is what the picker shows.
- Future<GridModels> gridModels(String machineId) =>
- _askGridModels(machineId, const {'rowState': true});
+ Future<GridModels> gridModels(
+ String machineId, {
+ bool userAction = false,
+ }) => _askGridModels(machineId, {
+ 'rowState': true,
+ if (userAction) 'userAction': true,
+ });
+
+ /// A person opened the Models panel: read this computer's model list marked as theirs, all that
+ /// the list's reach (`model_list_user_*`) counts. The panel's own refresh joins it in flight.
+ void markModelsOpened() {
+ if (localMachineState case final local?) {
+ unawaited(refreshGridModels(local.machine.machineId, userAction: true));
+ }
+ }
/// One `grid_models_list` ask with [payload].
///
@@ -9315,12 +9340,18 @@ class AppNotifier extends ChangeNotifier {
/// when a `grid_models_changed` push landed is returned to its caller but not adopted: the push is
/// newer. An answer that is not one — the machine could not be asked — is returned but not adopted
/// either: one surface's timed-out read must not blank the list every other surface is showing.
- Future<GridModels> refreshGridModels(String machineId) {
+ ///
+ /// [userAction] marks the read as a person opening a model list ([markModelsOpened]); joined with
+ /// a read in flight, the mark is lost.
+ Future<GridModels> refreshGridModels(
+ String machineId, {
+ bool userAction = false,
+ }) {
final inFlight = _gridReads[machineId];
if (inFlight != null) return inFlight;
final epoch = gridPictures.epochOf(machineId);
late final Future<GridModels> read;
- read = gridModels(machineId)
+ read = gridModels(machineId, userAction: userAction)
.then((answer) {
if (!_disposed && answer.reachable) {
gridPictures.adopt(machineId, answer, ifEpoch: epoch);
@@ -9907,22 +9938,35 @@ class AppNotifier extends ChangeNotifier {
/// [MachineDsh.inFlight] exactly like [probeEngines]. The Create dialog asks
/// with [force] on every open, since an install it started itself is what
/// most often makes the stored answer stale.
- Future<void> probeDsh(String machineId, {bool force = false}) {
+ ///
+ /// [userAction] marks the ask as a person opening the Store, for its reach. One that joins an ask
+ /// already in flight loses the mark: the count is a lower bound.
+ Future<void> probeDsh(
+ String machineId, {
+ bool force = false,
+ bool userAction = false,
+ }) {
final machine = machineStates[machineId];
if (machine == null) return Future.value();
final existing = machine.dsh.inFlight;
if (existing != null) return existing;
if (machine.dsh.loaded && !force) return Future.value();
- final work = _probeDsh(machine);
+ final work = _probeDsh(machine, userAction: userAction);
machine.dsh.inFlight = work;
notifyListeners();
return work;
}
- Future<void> _probeDsh(MachineState machine) async {
+ Future<void> _probeDsh(
+ MachineState machine, {
+ bool userAction = false,
+ }) async {
try {
- final result = await _conn(machine.machine.machineId)
- .request('dsh_list', timeout: const Duration(seconds: 30));
+ final result = await _conn(machine.machine.machineId).request(
+ 'dsh_list',
+ payload: userAction ? const {'userAction': true} : const {},
+ timeout: const Duration(seconds: 30),
+ );
final raw = result['dsh'];
if (raw is! List) throw const FormatException('dsh_list: no list');
machine.dsh.replace(raw.map(DshEntry.fromJson).whereType<DshEntry>());
diff --git a/desktop/lib/store/store_screen.dart b/desktop/lib/store/store_screen.dart
index 433d2ed1f..316e0da7d 100644
--- a/desktop/lib/store/store_screen.dart
+++ b/desktop/lib/store/store_screen.dart
@@ -182,8 +182,10 @@ class _StoreTabState extends State<StoreTab> {
if (!mounted) return;
unawaited(_store.loadRatings());
// Refresh installs made from a local terminal while the Store was closed.
+ // Taken whether or not this computer is here yet, so the mark never lands on a later Store.
+ final opened = widget.notifier.takeStoreOpened();
final local = widget.notifier.localMachineState;
- if (local != null) _ask(local);
+ if (local != null) _ask(local, userAction: opened);
widget.notifier.addListener(_onAppChanged);
// A Store left open picks up new publications; engines do not need reprobes.
// The daemon caches catalog HTTP requests for five minutes.
@@ -206,12 +208,14 @@ class _StoreTabState extends State<StoreTab> {
/// harnesses installed. So a machine is asked again each time it connects.
final _askedWhileConnected = <String>{};
- void _ask(MachineState machine) {
+ void _ask(MachineState machine, {bool userAction = false}) {
final id = machine.machine.machineId;
if (machine.connectionStatus == ConnectionStatus.connected) {
_askedWhileConnected.add(id);
}
- unawaited(widget.notifier.probeDsh(id, force: true));
+ unawaited(
+ widget.notifier.probeDsh(id, force: true, userAction: userAction),
+ );
// The engine rows read the same probe the New Harness dialog does; a
// machine that has never been asked would show Claude Code as absent.
unawaited(widget.notifier.probeEngines(id, force: true));
diff --git a/desktop/test/community_fork_test.dart b/desktop/test/community_fork_test.dart
index 8ba1adf8f..81208d7a3 100644
--- a/desktop/test/community_fork_test.dart
+++ b/desktop/test/community_fork_test.dart
@@ -136,7 +136,11 @@ class ForkTestApp extends ModelManagerTestApp {
String? viewerUse;
bool viewerInstalled = false;
@override
- Future<void> probeDsh(String machineId, {bool force = false}) async {
+ Future<void> probeDsh(
+ String machineId, {
+ bool force = false,
+ bool userAction = false,
+ }) async {
stateOf(machineId)!.dsh.replace([
DshEntry(
id: 'forks/test',
diff --git a/desktop/test/desktop_compact_launch_test.dart b/desktop/test/desktop_compact_launch_test.dart
index ccd946440..93bbdb26a 100644
--- a/desktop/test/desktop_compact_launch_test.dart
+++ b/desktop/test/desktop_compact_launch_test.dart
@@ -59,7 +59,11 @@ class _CompactApp extends AppNotifier {
@override
Future<void> probeEngines(String machineId, {bool force = false}) async {}
@override
- Future<void> probeDsh(String machineId, {bool force = false}) async {}
+ Future<void> probeDsh(
+ String machineId, {
+ bool force = false,
+ bool userAction = false,
+ }) async {}
@override
Future<Map<String, dynamic>> readGitProject(
String machineId,
diff --git a/desktop/test/desktop_composer_layout_test.dart b/desktop/test/desktop_composer_layout_test.dart
index d1f6f59d7..fe7655d67 100644
--- a/desktop/test/desktop_composer_layout_test.dart
+++ b/desktop/test/desktop_composer_layout_test.dart
@@ -69,11 +69,17 @@ class _ReviewApp extends AppNotifier {
Future<void> probeEngines(String machineId, {bool force = false}) async {}
@override
- Future<void> probeDsh(String machineId, {bool force = false}) async {}
+ Future<void> probeDsh(
+ String machineId, {
+ bool force = false,
+ bool userAction = false,
+ }) async {}
@override
- Future<GridModels> refreshGridModels(String machineId) async =>
- const GridModels.unreachable();
+ Future<GridModels> refreshGridModels(
+ String machineId, {
+ bool userAction = false,
+ }) async => const GridModels.unreachable();
@override
Future<Map<String, dynamic>> readGitProject(
diff --git a/desktop/test/desktop_new_harness_edge_test.dart b/desktop/test/desktop_new_harness_edge_test.dart
index 048b3f248..4ddf1567d 100644
--- a/desktop/test/desktop_new_harness_edge_test.dart
+++ b/desktop/test/desktop_new_harness_edge_test.dart
@@ -75,7 +75,11 @@ class _App extends AppNotifier {
Future<void> probeEngines(String machineId, {bool force = false}) async {}
@override
- Future<void> probeDsh(String machineId, {bool force = false}) async {}
+ Future<void> probeDsh(
+ String machineId, {
+ bool force = false,
+ bool userAction = false,
+ }) async {}
@override
Future<Map<String, dynamic>> listCodexProfiles(
diff --git a/desktop/test/essential_harness_test.dart b/desktop/test/essential_harness_test.dart
index 1f5b0ebc2..3aa0405ac 100644
--- a/desktop/test/essential_harness_test.dart
+++ b/desktop/test/essential_harness_test.dart
@@ -42,7 +42,11 @@ class _App extends MonitorTestApp {
String listedEngine = 'opencode';
@override
- Future<void> probeDsh(String machineId, {bool force = false}) async {
+ Future<void> probeDsh(
+ String machineId, {
+ bool force = false,
+ bool userAction = false,
+ }) async {
stateOf(machineId)!.dsh.replace([
for (final essential in storeEssentials)
DshEntry(
diff --git a/desktop/test/models_menu_test.dart b/desktop/test/models_menu_test.dart
index 6349d24ea..a2babb03b 100644
--- a/desktop/test/models_menu_test.dart
+++ b/desktop/test/models_menu_test.dart
@@ -51,7 +51,11 @@ class _GridApp extends AppNotifier {
Future<void> probeEngines(String machineId, {bool force = false}) async {}
@override
- Future<void> probeDsh(String machineId, {bool force = false}) async {
+ Future<void> probeDsh(
+ String machineId, {
+ bool force = false,
+ bool userAction = false,
+ }) async {
final installed = grid[machineId];
machineStates[machineId]!.dsh.replace([
if (installed != null)
diff --git a/desktop/test/new_agent_dsh_test.dart b/desktop/test/new_agent_dsh_test.dart
index 1c94ca70e..e3693ff0c 100644
--- a/desktop/test/new_agent_dsh_test.dart
+++ b/desktop/test/new_agent_dsh_test.dart
@@ -64,7 +64,11 @@ class _Notifier extends AppNotifier {
String? probeRefusal;
@override
- Future<void> probeDsh(String machineId, {bool force = false}) async {
+ Future<void> probeDsh(
+ String machineId, {
+ bool force = false,
+ bool userAction = false,
+ }) async {
harnessProbes++;
if (probeRefusal case final refusal?) {
stateOf(machineId)!.dsh.error = refusal;
diff --git a/desktop/test/new_agent_permission_mode_test.dart b/desktop/test/new_agent_permission_mode_test.dart
index 6ec3b0d12..094b96507 100644
--- a/desktop/test/new_agent_permission_mode_test.dart
+++ b/desktop/test/new_agent_permission_mode_test.dart
@@ -38,7 +38,11 @@ class _Notifier extends AppNotifier {
Future<void> probeEngines(String machineId, {bool force = false}) async {}
@override
- Future<void> probeDsh(String machineId, {bool force = false}) async {}
+ Future<void> probeDsh(
+ String machineId, {
+ bool force = false,
+ bool userAction = false,
+ }) async {}
@override
Future<Map<String, dynamic>> listCodexProfiles(
diff --git a/desktop/test/new_agent_rows_and_task_test.dart b/desktop/test/new_agent_rows_and_task_test.dart
index f38d721cb..0d08dbc97 100644
--- a/desktop/test/new_agent_rows_and_task_test.dart
+++ b/desktop/test/new_agent_rows_and_task_test.dart
@@ -100,7 +100,7 @@ class _App extends AppNotifier {
Future<void> probeEngines(String machineId, {bool force = false}) async {}
@override
- Future<void> probeDsh(String machineId, {bool force = false}) async {}
+ Future<void> probeDsh(String machineId, {bool force = false, bool userAction = false}) async {}
@override
Future<Map<String, dynamic>> listCodexProfiles(
diff --git a/desktop/test/new_agent_terminal_test.dart b/desktop/test/new_agent_terminal_test.dart
index 48ae9a1fd..cb6db8ccf 100644
--- a/desktop/test/new_agent_terminal_test.dart
+++ b/desktop/test/new_agent_terminal_test.dart
@@ -46,7 +46,11 @@ class _Notifier extends AppNotifier {
Future<void> probeEngines(String machineId, {bool force = false}) async {}
@override
- Future<void> probeDsh(String machineId, {bool force = false}) async {}
+ Future<void> probeDsh(
+ String machineId, {
+ bool force = false,
+ bool userAction = false,
+ }) async {}
@override
Future<Map<String, dynamic>> listCodexProfiles(
diff --git a/desktop/test/new_harness_attachments_test.dart b/desktop/test/new_harness_attachments_test.dart
index 0ed92604e..ea4e280c5 100644
--- a/desktop/test/new_harness_attachments_test.dart
+++ b/desktop/test/new_harness_attachments_test.dart
@@ -39,7 +39,11 @@ class _Notifier extends AppNotifier {
Future<void> probeEngines(String machineId, {bool force = false}) async {}
@override
- Future<void> probeDsh(String machineId, {bool force = false}) async {}
+ Future<void> probeDsh(
+ String machineId, {
+ bool force = false,
+ bool userAction = false,
+ }) async {}
@override
Future<Map<String, dynamic>> listCodexProfiles(
diff --git a/desktop/test/new_harness_install_pane_test.dart b/desktop/test/new_harness_install_pane_test.dart
index 7f496a7da..e820c0766 100644
--- a/desktop/test/new_harness_install_pane_test.dart
+++ b/desktop/test/new_harness_install_pane_test.dart
@@ -78,7 +78,11 @@ class _Notifier extends AppNotifier {
Future<void> probeEngines(String machineId, {bool force = false}) async {}
@override
- Future<void> probeDsh(String machineId, {bool force = false}) async {}
+ Future<void> probeDsh(
+ String machineId, {
+ bool force = false,
+ bool userAction = false,
+ }) async {}
@override
Future<Map<String, dynamic>> listCodexProfiles(
diff --git a/desktop/test/store_discover_test.dart b/desktop/test/store_discover_test.dart
index a9364bcd3..fd908dd65 100644
--- a/desktop/test/store_discover_test.dart
+++ b/desktop/test/store_discover_test.dart
@@ -137,7 +137,11 @@ class _App extends AppNotifier {
configStore: null,
);
@override
- Future<void> probeDsh(String machineId, {bool force = false}) async {}
+ Future<void> probeDsh(
+ String machineId, {
+ bool force = false,
+ bool userAction = false,
+ }) async {}
@override
Future<void> probeEngines(String machineId, {bool force = false}) async {}
diff --git a/desktop/test/store_experiments_test.dart b/desktop/test/store_experiments_test.dart
index f71d54d34..ef7bc91e2 100644
--- a/desktop/test/store_experiments_test.dart
+++ b/desktop/test/store_experiments_test.dart
@@ -61,7 +61,11 @@ class _App extends AppNotifier {
configStore: null,
);
@override
- Future<void> probeDsh(String machineId, {bool force = false}) async {}
+ Future<void> probeDsh(
+ String machineId, {
+ bool force = false,
+ bool userAction = false,
+ }) async {}
@override
Future<void> probeEngines(String machineId, {bool force = false}) async {}
@override
diff --git a/desktop/test/store_page_test.dart b/desktop/test/store_page_test.dart
index 2b5fdabc4..a458b4c58 100644
--- a/desktop/test/store_page_test.dart
+++ b/desktop/test/store_page_test.dart
@@ -81,7 +81,11 @@ class _Notifier extends AppNotifier {
}
@override
- Future<void> probeDsh(String machineId, {bool force = false}) async {
+ Future<void> probeDsh(
+ String machineId, {
+ bool force = false,
+ bool userAction = false,
+ }) async {
probes++;
}
diff --git a/desktop/test/store_screen_test.dart b/desktop/test/store_screen_test.dart
index b28d5477e..266b0d220 100644
--- a/desktop/test/store_screen_test.dart
+++ b/desktop/test/store_screen_test.dart
@@ -74,7 +74,11 @@ class _Notifier extends AppNotifier {
}
@override
- Future<void> probeDsh(String machineId, {bool force = false}) async {
+ Future<void> probeDsh(
+ String machineId, {
+ bool force = false,
+ bool userAction = false,
+ }) async {
probes++;
probedMachines.add(machineId);
}
diff --git a/desktop/test/store_showcase_test.dart b/desktop/test/store_showcase_test.dart
index 9cf32ad28..dc888f34f 100644
--- a/desktop/test/store_showcase_test.dart
+++ b/desktop/test/store_showcase_test.dart
@@ -66,7 +66,11 @@ class _Notifier extends AppNotifier {
Future<void> probeEngines(String machineId, {bool force = false}) async {}
@override
- Future<void> probeDsh(String machineId, {bool force = false}) async {}
+ Future<void> probeDsh(
+ String machineId, {
+ bool force = false,
+ bool userAction = false,
+ }) async {}
@override
Future<Map<String, dynamic>> listCodexProfiles(
diff --git a/desktop/test/store_tab_state_test.dart b/desktop/test/store_tab_state_test.dart
index cd110d7a1..0c948daf0 100644
--- a/desktop/test/store_tab_state_test.dart
+++ b/desktop/test/store_tab_state_test.dart
@@ -398,6 +398,10 @@ void main() {
expect(row('relay'), findsNothing);
expect(older.requests, isEmpty);
expect(relay.requests, isEmpty);
+ // Opened by a person: the first ask is marked as theirs, for the Store's reach.
+ expect(local.requests.firstWhere((r) => r.$1 == 'dsh_list').$2, {
+ 'userAction': true,
+ });
await tester.tap(find.byKey(const ValueKey('store-primary-action')));
await tester.pumpAndSettle();
@@ -424,6 +428,11 @@ void main() {
'dsh_remove',
'dsh_list',
]);
+ // The asks after an install or a removal are the app's own.
+ expect(
+ local.requests.where((r) => r.$1 == 'dsh_list').skip(1).map((r) => r.$2),
+ everyElement(isEmpty),
+ );
expect(older.requests, isEmpty);
expect(relay.requests, isEmpty);
diff --git a/desktop/test/support/harness_monitor.dart b/desktop/test/support/harness_monitor.dart
index bf20cf31d..37ab8b611 100644
--- a/desktop/test/support/harness_monitor.dart
+++ b/desktop/test/support/harness_monitor.dart
@@ -65,7 +65,11 @@ class MonitorTestApp extends ModelManagerTestApp {
}
@override
- Future<void> probeDsh(String machineId, {bool force = false}) async {
+ Future<void> probeDsh(
+ String machineId, {
+ bool force = false,
+ bool userAction = false,
+ }) async {
await probeReply?.future;
if (probeError != null) throw StateError(probeError!);
stateOf(machineId)!.dsh.replace([
diff --git a/desktop/test/support/model_manager.dart b/desktop/test/support/model_manager.dart
index 073da8f99..f5e79d035 100644
--- a/desktop/test/support/model_manager.dart
+++ b/desktop/test/support/model_manager.dart
@@ -235,7 +235,11 @@ class ModelManagerTestApp extends AppNotifier {
String label = 'harness',
}) async => '/fixture/$label';
@override
- Future<void> probeDsh(String machineId, {bool force = false}) async {
+ Future<void> probeDsh(
+ String machineId, {
+ bool force = false,
+ bool userAction = false,
+ }) async {
await probeReply?.future;
if (probeError != null) throw StateError(probeError!);
stateOf(machineId)!.dsh.replace([
@@ -262,7 +266,10 @@ class ModelManagerTestApp extends AppNotifier {
}
@override
- Future<GridModels> gridModels(String machineId) async {
+ Future<GridModels> gridModels(
+ String machineId, {
+ bool userAction = false,
+ }) async {
gridReads++;
return inventory;
}
diff --git a/desktop/test/user_opened_reach_test.dart b/desktop/test/user_opened_reach_test.dart
new file mode 100644
index 000000000..028bad2fd
--- /dev/null
+++ b/desktop/test/user_opened_reach_test.dart
@@ -0,0 +1,77 @@
+// A person opening the Store or the Models panel marks that one list request
+// `userAction`, which is all the daemon counts as the list's reach
+// (docs/plans/2026-10-14-user-opened-reach.md). The refreshes and probes the
+// app makes on its own carry no mark.
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/ws/ws_conn.dart';
+
+import 'swarm_state_test.dart' show createApp;
+
+class _Connection extends WsConn {
+ _Connection()
+ : super(
+ wsBaseUrl: 'ws://fixture.invalid',
+ autonomousEnv: 'test',
+ machineId: 'm',
+ accessTokenProvider: (_, _) async => '',
+ onAuthFailure: (_) {},
+ onEvent: (_) {},
+ onStatus: (_) {},
+ );
+
+ final calls = <(String, Map<String, dynamic>)>[];
+
+ @override
+ Future<Map<String, dynamic>> request(
+ String type, {
+ Map<String, dynamic> payload = const {},
+ Duration timeout = const Duration(seconds: 20),
+ }) async {
+ calls.add((type, Map.of(payload)));
+ return type == 'dsh_list' ? {'dsh': []} : {};
+ }
+
+ List<bool> marks(String type) => [
+ for (final (t, payload) in calls)
+ if (t == type) payload['userAction'] == true,
+ ];
+}
+
+void main() {
+ test(
+ 'opening the Store marks one dsh_list, and the Store\'s own probes do not',
+ () async {
+ final connection = _Connection();
+ final app = createApp(connectionForTest: (_) => connection);
+ addTearDown(app.dispose);
+ app.stateOf('m')!.localOnly = true;
+
+ // A Store tab restored at launch was not opened by anyone.
+ expect(app.takeStoreOpened(), isFalse);
+ app.openStore();
+ // The Store tab's first ask takes the mark, once.
+ expect(app.takeStoreOpened(), isTrue);
+ expect(app.takeStoreOpened(), isFalse);
+ // Already on the Store: nothing was opened.
+ app.openStore();
+ expect(app.takeStoreOpened(), isFalse);
+
+ await app.probeDsh('m', force: true, userAction: true);
+ await app.probeDsh('m', force: true);
+ expect(connection.marks('dsh_list'), [true, false]);
+ },
+ );
+
+ test('opening the Models panel marks one grid_models_list, and the surfaces\' reads do not', () async {
+ final connection = _Connection();
+ final app = createApp(connectionForTest: (_) => connection);
+ addTearDown(app.dispose);
+ app.stateOf('m')!.localOnly = true;
+
+ app.markModelsOpened();
+ await app.refreshGridModels('m');
+ await app.refreshGridModels('m');
+ expect(connection.marks('grid_models_list'), [true, false]);
+ expect(connection.calls.first.$2['rowState'], isTrue);
+ });
+}
diff --git a/desktop/test/workspace_start_guide_test.dart b/desktop/test/workspace_start_guide_test.dart
index d4557d1b1..0e0e900cb 100644
--- a/desktop/test/workspace_start_guide_test.dart
+++ b/desktop/test/workspace_start_guide_test.dart
@@ -84,7 +84,11 @@ class _FirstApp extends AppNotifier {
}
@override
- Future<void> probeDsh(String machineId, {bool force = false}) async {}
+ Future<void> probeDsh(
+ String machineId, {
+ bool force = false,
+ bool userAction = false,
+ }) async {}
@override
Future<Map<String, dynamic>> listRemoteFolder(
String machineId,
diff --git a/desktop/tool/machines_preview.dart b/desktop/tool/machines_preview.dart
index f654ccf3e..baf540048 100644
--- a/desktop/tool/machines_preview.dart
+++ b/desktop/tool/machines_preview.dart
@@ -110,8 +110,10 @@ class _App extends AppNotifier {
}
@override
- Future<GridModels> gridModels(String machineId) async =>
- const GridModels(gridName: 'Review', models: []);
+ Future<GridModels> gridModels(
+ String machineId, {
+ bool userAction = false,
+ }) async => const GridModels(gridName: 'Review', models: []);
@override
Future<Map<String, dynamic>> localModels(
diff --git a/desktop/tool/models_review.dart b/desktop/tool/models_review.dart
index c0aece5df..cd0fa8883 100644
--- a/desktop/tool/models_review.dart
+++ b/desktop/tool/models_review.dart
@@ -162,7 +162,10 @@ class ReviewApp extends ModelManagerTestApp {
}
@override
- Future<GridModels> gridModels(String machineId) async => GridModels(
+ Future<GridModels> gridModels(
+ String machineId, {
+ bool userAction = false,
+ }) async => GridModels(
gridName: 'home',
models: [
for (final raw in localInventory['models'] as List)
diff --git a/docs/plans/2026-10-14-user-opened-reach.md b/docs/plans/2026-10-14-user-opened-reach.md
new file mode 100644
index 000000000..0527887ae
--- /dev/null
+++ b/docs/plans/2026-10-14-user-opened-reach.md
@@ -0,0 +1,65 @@
+# Feature reach for the Store and model lists, counted when a person opens them
+
+Status: approved in conversation on 2026-10-14 (approach A).
+
+## Why
+
+#1313 stopped counting feature reach (`*_installation_days`, `*_first_installations`,
+`*_repeat_installation_days`) for the four reads the apps make on their own: `history`
+(`agent_recent`), `history_page` (`session_tail`), `store_list` (`dsh_list`) and `model_list`
+(`models_list`, `grid_models_list`). Their reliability counts stay. Since then the report cannot say how
+many installations open the Store or a model list.
+
+What starts each request:
+
+| Action | Started by a person? |
+|---|---|
+| `history` | No. Search previews, task routing and the change-agent handoff read it. |
+| `history_page` | No. Session activity labels and Community publishing read it. |
+| `store_list` | Sometimes. Opening the Store does, but so do the Store's one-minute refresh, reconnects and the New Harness probes. |
+| `model_list` | Sometimes. Opening the Models panel (desktop) or a model sheet (phone) does, but so does every surface that shows models. |
+
+`history` and `history_page` stay reliability-only: no person's action stands behind them, and
+`search` and `resume` already measure finding and reopening a conversation.
+
+## Design
+
+1. **Contract** (`cli/src/lib/productUsageContract.ts` = `backend/src/types/productUsage.ts`):
+ `PRODUCT_USAGE_USER_OPENED_ACTIONS = ['store_list', 'model_list']`. The new metrics are
+ `<action>_user_requests`, `<action>_user_installation_days`, `<action>_user_first_installations` and
+ `<action>_user_repeat_installation_days`. They are new names because clients released before #1313 still
+ send `store_list_installation_days` for every automatic read.
+2. **App**: the request that opening the screen sends carries `userAction: true` in its payload.
+ - Desktop: `AppNotifier.openStore` leaves a one-shot mark. The Store tab's first ask takes it
+ (`takeStoreOpened`), so a Store tab restored at launch is not counted and no extra request is sent.
+ Opening the Models panel asks this computer's `grid_models_list` (`markModelsOpened`), and the
+ panel's own refresh joins that read.
+ - Phone: a model sheet opening (new agent, change model, and Find's `:` models mode, which shares the
+ change-model controller) asks the machine's `grid_models_list`. Desktop's ⌘P models mode and pane
+ pickers are not marked, so desktop and phone reach are not directly comparable.
+ - The Store's periodic refresh, reconnect probes, pickers and previews send no flag.
+3. **Daemon**: `productUsageRequest` emits `<action>_user_requests` beside `<action>_requests` when the
+ payload carries `userAction: true` and the action is user-opened. The gateway counts reach from that
+ metric, once per installation per UTC day. It keeps its own `first` and `repeat` state, apart from
+ the old automatic reach.
+4. **Report**: `review.features` reads reach for `store_list` and `model_list` from the `_user_` metrics
+ and adds `userRequests`. A count is a lower bound. Older apps and daemons send no flag. A flagged
+ request that joins one already in flight loses its flag.
+
+## Rollout
+
+The backend schema is strict and rejects a report that holds a metric it does not know. So release the
+backend before the CLI. The CLI and the apps can then ship in any order. An old daemon ignores the
+payload field, and an app without the flag simply contributes no reach.
+
+## Tests
+
+- CLI `productUsageSignals.spec.ts`: a flagged `dsh_list`/`grid_models_list` emits `_user_requests`;
+ an unflagged one and a flagged `agent_recent` or `session_tail` do not.
+- CLI `gateway/productUsage.spec.ts`: `_user_requests` counts reach once a day with first/repeat;
+ plain `store_list_requests` still counts none.
+- Backend `dailyProductReview.test.ts`: reach for `store_list` comes only from the `_user_` metrics;
+ `history` stays null.
+- Desktop: after `openStore`, the Store tab's first `dsh_list` is flagged and its later asks are not. A
+ restored tab takes no mark. Opening the Models panel sends a flagged `grid_models_list`.
+- Phone: opening the model sheet sends a flagged `grid_models_list`.
diff --git a/docs/product-measurement.md b/docs/product-measurement.md
index 59c4bd862..456f5f4eb 100644
--- a/docs/product-measurement.md
+++ b/docs/product-measurement.md
@@ -16,7 +16,7 @@ automatically proven improvement. Changes still need review, tests and a deliber
| Was the task useful? | Optional Completed / Partly completed / Not completed plus five fixed reason choices, reachable from Rate task outcome and Privacy | Voluntary and self-selected; not representative success or satisfaction. There is no free-text input. |
| Is there usage at all? | Active and working computer counts; app opens; older-client relay totals | Background windows can count as active. An open is a surface going from no attached window to one, not each connection (the desktop holds one per machine and redials). Relay events are not distinct people; the populations must not be added together. |
-| Which features get tried and used again? | First measured installations and daily first/repeat feature reach | Locally deduplicated installation-days, not unique accounts. Reads the apps make on their own (history, history paging, Store list, model list; `PRODUCT_USAGE_AUTOMATIC_ACTIONS`) count reliability only and have no reach. |
+| Which features get tried and used again? | First measured installations and daily first/repeat feature reach | Locally deduplicated installation-days, not unique accounts. Reads the apps make on their own (history, history paging, Store list, model list; `PRODUCT_USAGE_AUTOMATIC_ACTIONS`) count reliability only. The Store and model lists get reach only from the request an app marks `userAction` when a person opens them (`<action>_user_*`, `PRODUCT_USAGE_USER_OPENED_ACTIONS`); history has none. |
| Where do app flows break? | Setup, Harness/tmux/clipboard steps, sign-in, workspace/remote connections, computer linking, viewer-pane opening and manual update checking/staging | Fixed started/ok/failed/cancelled/unknown counts and coarse duration buckets. Opening a viewer pane is not rendering its content; staging an update is not a successful relaunch. |
| Is measurement losing coverage? | Updated collector installation-days, pruned queues, full observation maps, unmatched app starts | Loss signals warrant caution. No signal does not prove complete collection. |
| How many people use Harness, and do they come back? | People active / working / new per day and per app, and D1/D2/D3/D7 returns (backend rollup of 10-day pseudonymous marks) | Sharing accounts only, staff excluded; an app open across midnight counts on both days, so prefer working returns. Not available before `PRODUCT_USAGE_SUBJECT_KEY` is set. |
diff --git a/mobile/lib/phone/agent_model_controller.dart b/mobile/lib/phone/agent_model_controller.dart
index 0bbe9d1ec..75e893212 100644
--- a/mobile/lib/phone/agent_model_controller.dart
+++ b/mobile/lib/phone/agent_model_controller.dart
@@ -79,7 +79,7 @@ class AgentModelController extends ChangeNotifier {
/// or leave a grid between two openings, and an offer nobody is serving any
/// more is worse than a moment's wait.
Future<void> _load() async {
- final answer = await notifier.gridModels(machineId);
+ final answer = await notifier.gridModels(machineId, userAction: true);
if (_disposed) return;
_answer = answer;
_changed();
diff --git a/mobile/lib/phone/new_agent_model_sheet.dart b/mobile/lib/phone/new_agent_model_sheet.dart
index 3b02f06d0..ff6802153 100644
--- a/mobile/lib/phone/new_agent_model_sheet.dart
+++ b/mobile/lib/phone/new_agent_model_sheet.dart
@@ -98,7 +98,10 @@ class _ModelChooserState extends State<_ModelChooser> {
Future<void> _load() async {
if (_loading) return;
setState(() => _loading = true);
- final catalog = await widget.notifier.gridModels(widget.machineId);
+ final catalog = await widget.notifier.gridModels(
+ widget.machineId,
+ userAction: true,
+ );
if (!mounted) return;
setState(() {
_catalog = catalog;
diff --git a/mobile/lib/state/app_state.dart b/mobile/lib/state/app_state.dart
index c7af3635c..6ea6a516a 100644
--- a/mobile/lib/state/app_state.dart
+++ b/mobile/lib/state/app_state.dart
@@ -4920,10 +4920,19 @@ class AppNotifier extends ChangeNotifier {
/// Never throws — a machine whose daemon is too old to know the RPC, one with
/// no grid, and one that timed out are all "nothing to offer", which is what
/// the sheet shows.
- Future<GridModels> gridModels(String machineId) async {
+ ///
+ /// [userAction] marks the read as a person opening a model sheet: the only
+ /// read the model list's reach counts (`model_list_user_*`).
+ Future<GridModels> gridModels(
+ String machineId, {
+ bool userAction = false,
+ }) async {
try {
- final response = await _conn(machineId)
- .request('grid_models_list', timeout: const Duration(seconds: 12));
+ final response = await _conn(machineId).request(
+ 'grid_models_list',
+ payload: userAction ? const {'userAction': true} : const {},
+ timeout: const Duration(seconds: 12),
+ );
List<GridModel> parseModels(Object? raw, {String? grid}) =>
(raw as List<dynamic>? ?? [])
.whereType<Map<String, dynamic>>()
diff --git a/mobile/test/phone_model_sheet_test.dart b/mobile/test/phone_model_sheet_test.dart
index 6389ca383..92d76a893 100644
--- a/mobile/test/phone_model_sheet_test.dart
+++ b/mobile/test/phone_model_sheet_test.dart
@@ -111,6 +111,18 @@ void main() {
},
);
+ testWidgets('opening the sheet asks for the models as a person\'s own', (
+ tester,
+ ) async {
+ final connection = conn();
+ await open(tester, app(connection));
+
+ // The one read the model list's reach counts (`model_list_user_*`).
+ expect(sent(connection, 'grid_models_list'), [
+ {'userAction': true},
+ ]);
+ });
+
testWidgets('the agent is on its own login until a model is picked', (
tester,
) async {