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.

Desktop: no 30 s rebuilds, no chmod process per state save, notify-send off the UI thread; count why frames are slow (#1403)

Dee78ebd3428e6c
diff --git a/backend/src/types/productHealthContract.ts b/backend/src/types/productHealthContract.ts
index 1e53e411f..66dc2e1b4 100644
--- a/backend/src/types/productHealthContract.ts
+++ b/backend/src/types/productHealthContract.ts
@@ -25,6 +25,10 @@ export const HEALTH_MEASURES = [
'interactive_turns_started', 'tool_turns_started', 'unclassified_turns_started',
'interactive_work_days', 'first_interactive_work', 'first_work_d1_return', 'first_work_d7_return', 'first_work_d28_return',
'week_worked_1day', 'week_worked_2to3days', 'week_worked_4to5days', 'week_worked_6to7days',
+ // Vocabulary 2 (`x-harness-usage-vocabulary`, cli/src/lib/appProductUsageReport.ts): a sampled Desktop frame of
+ // 50 ms or more by its longest phase, and one per collector day whose sampled frames included one over 250 ms.
+ // The Desktop counts them only once its CLI's report proxy has said it knows them.
+ 'frame_slow_wait', 'frame_slow_build', 'frame_slow_raster', 'frame_long_collector',
] as const
// Delivery attempts, including retries; separate from the cross-surface app measures.
export const CLI_REPORT_FAILURES = ['invalid', 'too_large', 'auth', 'rate_limited', 'timeout', 'unreachable',
diff --git a/cli/src/hookServer.spec.ts b/cli/src/hookServer.spec.ts
index 63215aeac..ead6f559a 100644
--- a/cli/src/hookServer.spec.ts
+++ b/cli/src/hookServer.spec.ts
@@ -397,6 +397,35 @@ describe('account Experimental settings proxy', () => {
expect((await post(body)).status).toBe(200)
expect(send).toHaveBeenCalledExactlyOnceWith(body)
})
+ it('forwards a newer Desktop report without the names it does not know, and says which it knows', async () => {
+ // Refused whole before: the Desktop drops a refused packet for good, so one new name lost all of it.
+ const body = JSON.parse(readFileSync(new URL('../../tests/fixtures/desktop-product-usage-report.json', import.meta.url), 'utf8'))
+ const send = vi.fn(async () => ({ status: 200, body: { success: true, data: { accepted: true } } }))
+ const { base } = await start({ onProductUsageReport: send })
+ const headers = { 'content-type': 'application/json', 'x-adapter-local': '1' }
+ const post = (value: unknown, h: Record<string, string> = headers) =>
+ fetch(`${base}/api/product-usage/report`, { method: 'POST', headers: h, body: JSON.stringify(value) })
+ const newer = { ...body, counters: { ...body.counters, health_desktop_frame_slow_wait: 2, health_desktop_PRIVATE_CANARY: 1 } }
+ const kept = await post(newer)
+ expect(kept.status).toBe(200)
+ expect(kept.headers.get('x-harness-usage-vocabulary')).toBe('2')
+ expect(send).toHaveBeenCalledExactlyOnceWith({ ...body,
+ counters: { ...body.counters, health_desktop_frame_slow_wait: 2, health_desktop_report_unknown_metric: 1 } })
+ expect(JSON.stringify(send.mock.calls)).not.toContain('PRIVATE_CANARY')
+ // Everything else is refused as before, and every answer names the vocabulary.
+ for (const [refused, h] of [
+ [{ ...body, counters: { health_desktop_PRIVATE_CANARY: 1 } }, headers],
+ [{ ...newer, counters: { ...newer.counters, turns_started: 1 } }, headers],
+ [{ ...newer, prompt: 'PRIVATE_CANARY' }, headers],
+ [newer, { 'content-type': 'application/json' }],
+ ] as const) {
+ const response = await post(refused, h)
+ expect(response.status).toBe('x-adapter-local' in h ? 400 : 403)
+ expect(response.headers.get('x-harness-usage-vocabulary')).toBe('2')
+ expect(await response.text()).not.toContain('PRIVATE_CANARY')
+ }
+ expect(send).toHaveBeenCalledOnce()
+ })
it('serves the Privacy switch and rejects cross-origin, extra-field and malformed writes', async () => {
const write = vi.fn(async () => ({ status: 200, body: { success: true, data: { enabled: false, revision: 1 } } }))
const { base } = await start({ onProductUsageRead: async () => ({ status: 200, body: { success: true, data: { enabled: true, revision: 0 } } }), onProductUsageWrite: write })
diff --git a/cli/src/hookServer.ts b/cli/src/hookServer.ts
index af6176e33..8527f0456 100644
--- a/cli/src/hookServer.ts
+++ b/cli/src/hookServer.ts
@@ -1,5 +1,5 @@
import { PRODUCT_FEEDBACK } from './lib/productUsageContract.js'
-import { isAppProductUsageReport } from './lib/appProductUsageReport.js'
+import { appProductUsageReport, APP_USAGE_VOCABULARY, APP_USAGE_VOCABULARY_HEADER } from './lib/appProductUsageReport.js'
/**
* Tiny localhost HTTP server for the Claude Code hook callbacks. `hook/notify.mjs` POSTs here on
* SessionStart/SessionEnd (127.0.0.1:<PORT>). This replaces the old Fastify routes — the browser
@@ -1031,6 +1031,9 @@ export function startHookServer(
await proxied(handlers.onExperimentalRead); return
}
if (req.method === 'POST' && url === '/api/product-usage/report') {
+ // On every answer, a refusal too: the Desktop counts names newer than revision 1 only after
+ // reading it here, because a proxy that predates a name refused the whole report.
+ res.setHeader(APP_USAGE_VOCABULARY_HEADER, String(APP_USAGE_VOCABULARY))
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onProductUsageReport) { json(503, { error: 'UNAVAILABLE' }); return }
let body: unknown
@@ -1038,11 +1041,13 @@ export function startHookServer(
const raw = await readBody(req, 8192)
body = JSON.parse(raw)
} catch { json(400, { error: 'BAD_REQUEST' }); return }
- if (!isAppProductUsageReport(body)) {
+ // Without the names this contract does not know yet; see lib/appProductUsageReport.ts.
+ const report = appProductUsageReport(body)
+ if (!report) {
json(400, { error: 'BAD_REQUEST' }); return
}
try {
- const result = await handlers.onProductUsageReport(body)
+ const result = await handlers.onProductUsageReport(report)
json(result.status, result.body)
} catch { json(502, { success: false, error: { code: 'USAGE_UNAVAILABLE', message: 'Product usage unavailable' } }) }
return
diff --git a/cli/src/lib/appProductUsageReport.spec.ts b/cli/src/lib/appProductUsageReport.spec.ts
index a54af7056..9d57d4388 100644
--- a/cli/src/lib/appProductUsageReport.spec.ts
+++ b/cli/src/lib/appProductUsageReport.spec.ts
@@ -1,6 +1,6 @@
import { readFileSync } from 'node:fs'
import { expect, it } from 'vitest'
-import { isAppProductUsageReport } from './appProductUsageReport.js'
+import { appProductUsageReport, APP_USAGE_VOCABULARY, isAppProductUsageReport } from './appProductUsageReport.js'
import { HEALTH_MEASURES, CLI_REPORT_FAILURES } from './productHealthContract.js'
import { PRODUCT_USAGE_UI_METRICS } from './productUsageContract.js'
@@ -57,3 +57,36 @@ it('refuses arbitrary context, non-Desktop attribution, daemon counts and malfor
expect(isAppProductUsageReport(missing)).toBe(false)
}
})
+
+it('drops names this contract does not know yet, says so once, and refuses everything else as before', () => {
+ // A newer Desktop's report used to be refused whole, and the Desktop drops a refused packet for good.
+ const counters = { ...native.counters, health_desktop_frame_from_the_future: 3, PRIVATE_CANARY: 'any value' }
+ const kept = appProductUsageReport({ ...native, counters })
+ expect(kept).toEqual({ ...native, counters: { ...native.counters, health_desktop_report_unknown_metric: 1 } })
+ expect(JSON.stringify(kept)).not.toMatch(/future|PRIVATE_CANARY/)
+ // A UI-only report has no surface to count that under, as at the backend.
+ expect(appProductUsageReport({ ...old, counters: { ...old.counters, ui_desktop_from_the_future: 1 } })).toEqual(old)
+ // A full report with one unknown name stays within 32 counters once it is counted.
+ const full = Object.fromEntries(HEALTH_MEASURES.slice(0, 31).map(m => [`health_desktop_${m}`, 1]))
+ expect(Object.keys(appProductUsageReport({ ...native, counters: { ...full, PRIVATE_CANARY: 1 } })!.counters)).toHaveLength(32)
+ // Unchanged reports are forwarded as they are.
+ expect(appProductUsageReport(native)).toBe(native)
+ for (const refused of [
+ // Nothing known left.
+ { ...native, counters: { PRIVATE_CANARY: 1 } },
+ // A known name an app may not file is not unknown: a daemon's, hn's, the phone's, the backend's own.
+ ...['turns_started', 'health_cli_collector_days', 'health_tui_funnel_first_work', 'ui_phone_sign_in_ok',
+ 'health_desktop_report_unknown_metric'].map(key => ({ ...native, counters: { [key]: 1, PRIVATE_CANARY: 1 } })),
+ // A known name's bad value, and more than 32 names, unknown ones included.
+ { ...native, counters: { health_desktop_collector_days: 0, PRIVATE_CANARY: 1 } },
+ { ...native, counters: { ...full, [`health_desktop_${HEALTH_MEASURES[31]}`]: 1, PRIVATE_CANARY: 1 } },
+ { ...native, prompt: 'PRIVATE_CANARY', counters: { ...native.counters, PRIVATE_CANARY: 1 } },
+ ]) expect(appProductUsageReport(refused), JSON.stringify(refused)).toBeUndefined()
+})
+
+it('announces vocabulary 2, the revision whose frame-phase names a Desktop waits for', () => {
+ expect(APP_USAGE_VOCABULARY).toBe(2)
+ for (const measure of ['frame_slow_wait', 'frame_slow_build', 'frame_slow_raster', 'frame_long_collector']) {
+ expect(appProductUsageReport({ ...native, counters: { [`health_desktop_${measure}`]: 1 } })).toBeDefined()
+ }
+})
diff --git a/cli/src/lib/appProductUsageReport.ts b/cli/src/lib/appProductUsageReport.ts
index 3d050c756..fc7842454 100644
--- a/cli/src/lib/appProductUsageReport.ts
+++ b/cli/src/lib/appProductUsageReport.ts
@@ -1,5 +1,12 @@
import { cleanUsageContext, HEALTH_MEASURES, CLI_REPORT_FAILURES } from './productHealthContract.js'
-import { PRODUCT_USAGE_UI_METRICS, type ProductUsageReport } from './productUsageContract.js'
+import { PRODUCT_USAGE_METRICS, PRODUCT_USAGE_UI_METRICS, type ProductUsageReport } from './productUsageContract.js'
+
+/** The contract revision this proxy forwards, sent on each of its answers as `x-harness-usage-vocabulary`.
+ * 2: the Desktop's frame-phase counters (`frame_slow_*`, `frame_long_collector`). The Desktop counts a name
+ * newer than revision 1 only once a proxy has announced it, so an older CLI never sees one. Raise it with
+ * each name the Desktop gates on it (`ProductHealthMeasure.vocabulary`). */
+export const APP_USAGE_VOCABULARY = 2
+export const APP_USAGE_VOCABULARY_HEADER = 'x-harness-usage-vocabulary'
// hn's counts reach the daemon's own queue only through hn's `product_observe`; no app can file them.
const uiMetrics = new Set<string>(PRODUCT_USAGE_UI_METRICS.filter(metric => !metric.startsWith('ui_tui_')))
@@ -8,30 +15,53 @@ const desktopMetrics = new Set<string>([
...HEALTH_MEASURES.map(measure => `health_desktop_${measure}`),
...CLI_REPORT_FAILURES.map(reason => `health_desktop_report_failure_${reason}`),
])
+const knownMetrics = new Set<string>(PRODUCT_USAGE_METRICS)
const fields = new Set(['schemaVersion', 'revision', 'id', 'day', 'counters', 'context'])
const contextFields = new Set(['surface', 'release', 'platform', 'channel'])
const object = (value: unknown): value is Record<string, unknown> =>
value !== null && typeof value === 'object' && !Array.isArray(value)
-/** The local proxy must admit the native Desktop format as well as older UI-only reports.
- * Keep this narrower than the backend contract: an app cannot submit daemon counters or labels.
- * The caller also bounds the complete JSON body to 8 KiB before parsing it.
- */
-export function isAppProductUsageReport(value: unknown): value is ProductUsageReport {
+/** The report this local proxy forwards for an app, or undefined to refuse it.
+ * It admits the native Desktop format as well as older UI-only reports, and stays narrower than the
+ * backend contract: an app cannot submit daemon counters or labels. The caller bounds the complete JSON
+ * body to 8 KiB before parsing it.
+ *
+ * A Desktop a release ahead of this CLI can name a counter this contract does not have yet. This proxy
+ * refused such a report whole, and the Desktop drops a refused packet for good
+ * (desktop/lib/measurement/product_report_failure.dart: a 400 is permanent), losing up to 32 counters for
+ * one new name. As the backend does (`withoutUnknownCounters`, backend/src/routes/productUsage.ts), the
+ * unknown names are dropped, never forwarded or logged, and a Desktop report says so once with
+ * `health_desktop_report_unknown_metric`. A known name an app may not file still refuses the report, as
+ * does one with no known counter left; values and every other field are checked as before. */
+export function appProductUsageReport(value: unknown): ProductUsageReport | undefined {
if (!object(value) || Object.keys(value).some(key => !fields.has(key)) || value.schemaVersion !== 1
|| typeof value.revision !== 'number' || !Number.isSafeInteger(value.revision) || value.revision < 0
|| typeof value.id !== 'string' || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(value.id)
|| typeof value.day !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value.day)
- || !object(value.counters) || Object.keys(value.counters).length > 32) return false
+ || !object(value.counters) || Object.keys(value.counters).length > 32) return
let allowed = uiMetrics
if ('context' in value) {
const context = value.context
if (!object(context) || Object.keys(context).length !== 4
- || Object.keys(context).some(key => !contextFields.has(key)) || context.surface !== 'desktop') return false
+ || Object.keys(context).some(key => !contextFields.has(key)) || context.surface !== 'desktop') return
const clean = cleanUsageContext(context)
- if (!clean || clean.release !== context.release) return false
+ if (!clean || clean.release !== context.release) return
allowed = desktopMetrics
}
- return Object.entries(value.counters).every(([key, count]) => allowed.has(key)
- && typeof count === 'number' && Number.isSafeInteger(count) && count >= 1 && count <= 1000)
+ const all = Object.entries(value.counters)
+ const known = all.filter(([key]) => knownMetrics.has(key))
+ // An empty report is the legacy form's own; one with nothing known left is not.
+ if (all.length && !known.length) return
+ if (!known.every(([key, count]) => allowed.has(key)
+ && typeof count === 'number' && Number.isSafeInteger(count) && count >= 1 && count <= 1000)) return
+ if (known.length === all.length) return value as unknown as ProductUsageReport
+ const counters = Object.fromEntries(known) as Record<string, number>
+ // Only a Desktop report has a surface to count it under, as at the backend.
+ if (allowed === desktopMetrics) counters.health_desktop_report_unknown_metric = 1
+ return { ...value, counters } as unknown as ProductUsageReport
+}
+
+/** Whether [appProductUsageReport] forwards the report at all. */
+export function isAppProductUsageReport(value: unknown): value is ProductUsageReport {
+ return appProductUsageReport(value) !== undefined
}
diff --git a/cli/src/lib/productHealthContract.ts b/cli/src/lib/productHealthContract.ts
index 1e53e411f..66dc2e1b4 100644
--- a/cli/src/lib/productHealthContract.ts
+++ b/cli/src/lib/productHealthContract.ts
@@ -25,6 +25,10 @@ export const HEALTH_MEASURES = [
'interactive_turns_started', 'tool_turns_started', 'unclassified_turns_started',
'interactive_work_days', 'first_interactive_work', 'first_work_d1_return', 'first_work_d7_return', 'first_work_d28_return',
'week_worked_1day', 'week_worked_2to3days', 'week_worked_4to5days', 'week_worked_6to7days',
+ // Vocabulary 2 (`x-harness-usage-vocabulary`, cli/src/lib/appProductUsageReport.ts): a sampled Desktop frame of
+ // 50 ms or more by its longest phase, and one per collector day whose sampled frames included one over 250 ms.
+ // The Desktop counts them only once its CLI's report proxy has said it knows them.
+ 'frame_slow_wait', 'frame_slow_build', 'frame_slow_raster', 'frame_long_collector',
] as const
// Delivery attempts, including retries; separate from the cross-surface app measures.
export const CLI_REPORT_FAILURES = ['invalid', 'too_large', 'auth', 'rate_limited', 'timeout', 'unreachable',
diff --git a/desktop/lib/api/api_client.dart b/desktop/lib/api/api_client.dart
index 20680d0ea..6bf816573 100644
--- a/desktop/lib/api/api_client.dart
+++ b/desktop/lib/api/api_client.dart
@@ -118,10 +118,27 @@ class ApiClient {
return dio;
}
+ /// The header the local CLI's report proxy answers with: the revision of
+ /// the counter names it forwards (cli/src/lib/appProductUsageReport.ts).
+ static const usageVocabularyHeader = 'x-harness-usage-vocabulary';
+
+ /// [usageVocabularyHeader]'s value, or 1 — the names every proxy knows —
+ /// from a CLI that predates it (or the backend, which never sends it).
+ static int usageVocabulary(Headers headers) {
+ final values = headers[usageVocabularyHeader];
+ final value = int.tryParse(
+ values == null || values.isEmpty ? '' : values.first,
+ );
+ return value != null && value > 1 ? value : 1;
+ }
+
// -- auth (proxied by the local CLI — no credential on this leg) --
+ /// [onVocabulary] hears [usageVocabulary] from every answer, a refusal
+ /// included; a request that got no answer says nothing.
Future<Map<String, dynamic>> productUsageReport(
- Map<String, dynamic> report,
- ) async {
+ Map<String, dynamic> report, {
+ void Function(int vocabulary)? onVocabulary,
+ }) async {
try {
final response = await _dio.post(
'/api/product-usage/report',
@@ -132,6 +149,7 @@ class ApiClient {
sendTimeout: const Duration(seconds: 5),
),
);
+ onVocabulary?.call(usageVocabulary(response.headers));
final body = response.data;
if (response.statusCode != 200 ||
body is! Map ||
diff --git a/desktop/lib/core/harness_file_store_native.dart b/desktop/lib/core/harness_file_store_native.dart
index 37b018bf9..077395c6c 100644
--- a/desktop/lib/core/harness_file_store_native.dart
+++ b/desktop/lib/core/harness_file_store_native.dart
@@ -2,7 +2,10 @@ import 'dart:async';
import 'dart:convert';
import 'dart:io';
+import 'package:flutter/foundation.dart' show visibleForTesting;
+
import 'host_platform.dart';
+import 'posix_file_mode.dart';
import 'viewer_mode.dart';
import 'local_key_value_store.dart';
@@ -29,6 +32,12 @@ class HarnessFileStore implements BatchLocalKeyValueStore {
static final HarnessFileStore shared = HarnessFileStore();
static final Map<String, Future<void>> _pathTails = {};
+ /// Starts `/bin/chmod` where libc's is not bound ([PosixFileMode.supported]
+ /// is false). A test replaces it to prove macOS and Linux start none.
+ @visibleForTesting
+ static Future<ProcessResult> Function(String executable, List<String> args)
+ runProcess = Process.run;
+
final Directory directory;
HarnessFileStore({Directory? directory})
@@ -163,6 +172,12 @@ class HarnessFileStore implements BatchLocalKeyValueStore {
final suffix = '${pid}_${DateTime.now().microsecondsSinceEpoch}';
final temporary = File(_join(directory.path, '.$fileName.$suffix.tmp'));
try {
+ // Created 0600 before anything is written to it, so no mode needs
+ // changing afterwards. Created by `writeAsString` (0644), every write
+ // started `/bin/chmod` on the UI isolate (see PosixFileMode).
+ if (PosixFileMode.supported) {
+ PosixFileMode.createExclusive(temporary.path, 0x180);
+ }
await temporary.writeAsString(
'${const JsonEncoder.withIndent(' ').convert({'version': schemaVersion, 'values': values})}\n',
flush: true,
@@ -210,7 +225,11 @@ class HarnessFileStore implements BatchLocalKeyValueStore {
final expected = int.parse(mode, radix: 8);
final actual = (await FileStat.stat(path)).mode;
if ((actual & 0xfff) == expected) return;
- final result = await Process.run('/bin/chmod', [mode, path]);
+ if (PosixFileMode.supported) {
+ PosixFileMode.chmod(path, expected);
+ return;
+ }
+ final result = await runProcess('/bin/chmod', [mode, path]);
if (result.exitCode != 0) {
throw FileSystemException('Could not set mode $mode', path);
}
diff --git a/desktop/lib/core/posix_file_mode.dart b/desktop/lib/core/posix_file_mode.dart
new file mode 100644
index 000000000..6f7cdcaee
--- /dev/null
+++ b/desktop/lib/core/posix_file_mode.dart
@@ -0,0 +1,109 @@
+import 'dart:ffi';
+import 'dart:io';
+
+import 'package:ffi/ffi.dart';
+
+/// `chmod(2)`, and a new file created with an exact mode, from libc.
+///
+/// `HarnessFileStore` set its 0600/0700 modes by running `/bin/chmod`, and
+/// every `state.json` write needed one: `writeAsString` created the temporary
+/// file 0644. Dart starts a process synchronously on the calling isolate: it
+/// forks and waits for the child to exec before `Process.run` returns. On
+/// macOS and Linux the UI isolate runs on the platform main thread (Flutter
+/// 3.47), so each write held up the frame and the native event loop until
+/// another process had been scheduled. On a loaded 16-core Mac (load 29, a
+/// 490 MiB Dart VM, 2026-10-18) that synchronous part took 0.22 ms median,
+/// 0.33 ms p95 and up to 18–43 ms; this binding's chmod took 0.04 ms median,
+/// 0.07 ms p95. Linux was not measured.
+abstract final class PosixFileMode {
+ /// Where the binding below is known to match libc. Other hosts keep their
+ /// own fallback.
+ static bool get supported => Platform.isMacOS || Platform.isLinux;
+
+ /// `chmod(path, mode)`. Throws a [FileSystemException] on failure.
+ static void chmod(String path, int mode) => _libc.chmod(path, mode);
+
+ /// Creates [path], which must not exist yet, as an empty file of exactly
+ /// [mode]: `fchmod` after `open`, so the umask cannot change it.
+ static void createExclusive(String path, int mode) =>
+ _libc.createExclusive(path, mode);
+}
+
+final _libc = _Libc();
+
+final class _Libc {
+ final _library = DynamicLibrary.process();
+ late final _open = _library
+ .lookupFunction<
+ Int Function(Pointer<Utf8>, Int, VarArgs<(Int,)>),
+ int Function(Pointer<Utf8>, int, int)
+ >('open');
+ late final _close = _library
+ .lookupFunction<Int Function(Int), int Function(int)>('close');
+ // mode_t is 16 bits on macOS and 32 on Linux.
+ late final int Function(Pointer<Utf8>, int) _chmod = Platform.isMacOS
+ ? _library.lookupFunction<
+ Int Function(Pointer<Utf8>, Uint16),
+ int Function(Pointer<Utf8>, int)
+ >('chmod')
+ : _library.lookupFunction<
+ Int Function(Pointer<Utf8>, Uint32),
+ int Function(Pointer<Utf8>, int)
+ >('chmod');
+ late final int Function(int, int) _fchmod = Platform.isMacOS
+ ? _library
+ .lookupFunction<Int Function(Int, Uint16), int Function(int, int)>(
+ 'fchmod',
+ )
+ : _library
+ .lookupFunction<Int Function(Int, Uint32), int Function(int, int)>(
+ 'fchmod',
+ );
+ late final _errno = _library
+ .lookupFunction<Pointer<Int> Function(), Pointer<Int> Function()>(
+ Platform.isMacOS ? '__error' : '__errno_location',
+ );
+
+ void chmod(String path, int mode) => using((arena) {
+ final name = _name(path, arena);
+ _retry(() => _chmod(name, mode), path, mode);
+ });
+
+ void createExclusive(String path, int mode) => using((arena) {
+ final name = _name(path, arena);
+ // O_WRONLY | O_CREAT | O_EXCL | O_CLOEXEC.
+ final flags = Platform.isMacOS
+ ? 0x1 | 0x200 | 0x800 | 0x1000000
+ : 0x1 | 0x40 | 0x80 | 0x80000;
+ final fd = _retry(() => _open(name, flags, mode), path, mode);
+ final close = _close;
+ try {
+ _retry(() => _fchmod(fd, mode), path, mode);
+ } finally {
+ // Not retried on EINTR: the descriptor may already be released.
+ close(fd);
+ }
+ });
+
+ Pointer<Utf8> _name(String path, Arena arena) {
+ if (path.contains('\u0000')) {
+ throw ArgumentError.value(path, 'path', 'Contains a NUL byte');
+ }
+ return path.toNativeUtf8(allocator: arena);
+ }
+
+ int _retry(int Function() call, String path, int mode) {
+ final readErrno = _errno;
+ while (true) {
+ final result = call();
+ if (result >= 0) return result;
+ final error = readErrno().value;
+ if (error == 4) continue; // EINTR
+ throw FileSystemException(
+ 'Could not set mode ${mode.toRadixString(8)}',
+ path,
+ OSError('POSIX mode change failed', error),
+ );
+ }
+ }
+}
diff --git a/desktop/lib/measurement/product_health_contract.dart b/desktop/lib/measurement/product_health_contract.dart
index be4fedc82..31c6684a8 100644
--- a/desktop/lib/measurement/product_health_contract.dart
+++ b/desktop/lib/measurement/product_health_contract.dart
@@ -66,10 +66,30 @@ enum ProductHealthMeasure {
weekWorked1day('week_worked_1day'),
weekWorked2to3days('week_worked_2to3days'),
weekWorked4to5days('week_worked_4to5days'),
- weekWorked6to7days('week_worked_6to7days');
+ weekWorked6to7days('week_worked_6to7days'),
+ // A sampled frame of 50 ms or more by its longest phase, and the first
+ // sampled frame over 250 ms of each collector day (product_runtime_health).
+ frameSlowWait('frame_slow_wait'),
+ frameSlowBuild('frame_slow_build'),
+ frameSlowRaster('frame_slow_raster'),
+ frameLongCollector('frame_long_collector');
const ProductHealthMeasure(this.wire);
final String wire;
+
+ /// The revision of the local CLI's report proxy that knows this name
+ /// (`x-harness-usage-vocabulary`, cli/src/lib/appProductUsageReport.ts).
+ /// A signed-in report goes through that proxy, and one older than a name
+ /// refused the whole report, which this app then drops for good (a 400 is
+ /// permanent). So a newer name is counted only once the proxy has said it
+ /// knows it (`ProductMeasurement.proxyVocabulary`).
+ int get vocabulary => switch (this) {
+ frameSlowWait ||
+ frameSlowBuild ||
+ frameSlowRaster ||
+ frameLongCollector => 2,
+ _ => 1,
+ };
}
class ProductUsageContext {
diff --git a/desktop/lib/measurement/product_measurement.dart b/desktop/lib/measurement/product_measurement.dart
index 7d2362097..8b24ab323 100644
--- a/desktop/lib/measurement/product_measurement.dart
+++ b/desktop/lib/measurement/product_measurement.dart
@@ -77,7 +77,16 @@ class ProductMeasurement extends ChangeNotifier {
final String surface;
ProductUsageContext? context;
bool get healthEnabled => surface == 'desktop' && context != null;
+
+ /// The counter vocabulary the local CLI's report proxy announced on its
+ /// latest answer (`x-harness-usage-vocabulary`): 1, the names every proxy
+ /// knows, until one says more. A health measure newer than it is not
+ /// counted ([ProductHealthMeasure.vocabulary]).
+ int proxyVocabulary = 1;
String? _coverageDay;
+ // The day each once-a-day measure was last counted; cleared with
+ // collector_days' own day so the two stay comparable.
+ final _countedOn = <ProductHealthMeasure, String>{};
final _funnelSeen = <String, Set<ProductHealthMeasure>>{};
final _funnelStarted = <String, DateTime>{};
final _expires = <Object, DateTime>{};
@@ -270,7 +279,10 @@ class ProductMeasurement extends ChangeNotifier {
}
_funnelSeen.remove(channel);
_funnelStarted.remove(channel);
- if (channel == 'ui') _coverageDay = null;
+ if (channel == 'ui') {
+ _coverageDay = null;
+ _countedOn.clear();
+ }
}
void _coverage() {
@@ -284,6 +296,8 @@ class ProductMeasurement extends ChangeNotifier {
/// Only fixed enum scalars enter the queue. Called after checking the account choice.
void health(ProductHealthMeasure measure) {
if (!healthEnabled || !sharing || _disposed) return;
+ // A proxy older than this name would refuse every report carrying it.
+ if (measure.vocabulary > proxyVocabulary) return;
_coverage();
_count(
'ui',
@@ -292,6 +306,18 @@ class ProductMeasurement extends ChangeNotifier {
);
}
+ /// [measure] at most once per UTC day of this collector, like
+ /// collector_days, so its total reads against collector_days: how many
+ /// collector days had one, not how many there were.
+ void healthOncePerDay(ProductHealthMeasure measure) {
+ if (!healthEnabled || !sharing || _disposed) return;
+ if (measure.vocabulary > proxyVocabulary) return;
+ final day = _now().toUtc().toIso8601String().substring(0, 10);
+ if (_countedOn[measure] == day) return;
+ _countedOn[measure] = day;
+ health(measure);
+ }
+
/// Observed readiness since process launch; only its coarse duration is kept.
void observedStartup(Duration elapsed) {
if (!healthEnabled || !sharing || _disposed) return;
diff --git a/desktop/lib/measurement/product_runtime_health.dart b/desktop/lib/measurement/product_runtime_health.dart
index 4ddc69251..57c3f462d 100644
--- a/desktop/lib/measurement/product_runtime_health.dart
+++ b/desktop/lib/measurement/product_runtime_health.dart
@@ -263,7 +263,34 @@ class ProductRuntimeHealth {
? ProductHealthMeasure.frame50msTo250ms
: ProductHealthMeasure.frameOver250ms,
);
+ // The buckets alone could not say why Linux's sampled frames were long
+ // (Oct 17: 6.7% of Linux samples over 250 ms, macOS 0.25%), nor whether
+ // a few computers or many had them.
+ if (ms >= 50) measurement.health(_slowPhase(frame));
+ if (ms >= 250) {
+ measurement.healthOncePerDay(ProductHealthMeasure.frameLongCollector);
+ }
+ }
+ }
+
+ /// The longest of a slow frame's phases; a tie goes to the earlier one.
+ ///
+ /// Wait is vsync to build start: the UI thread was busy before the frame
+ /// could start. On macOS and Linux that thread is the platform's main thread
+ /// (Flutter 3.47), so timers, channel and native callbacks, synchronous IO
+ /// and AppKit or GTK work all land there. Build is the framework's build,
+ /// layout and paint; raster is the raster thread drawing it. The gap between
+ /// build finish and raster start (a raster thread still busy with an
+ /// earlier frame) is not a phase of its own.
+ static ProductHealthMeasure _slowPhase(FrameTiming frame) {
+ final wait = frame.vsyncOverhead, build = frame.buildDuration;
+ final raster = frame.rasterDuration;
+ if (wait >= build && wait >= raster) {
+ return ProductHealthMeasure.frameSlowWait;
}
+ return build >= raster
+ ? ProductHealthMeasure.frameSlowBuild
+ : ProductHealthMeasure.frameSlowRaster;
}
void expectUpdate(String version) {
diff --git a/desktop/lib/notify/system_notifications.dart b/desktop/lib/notify/system_notifications.dart
index d2e639a65..beaecc0bf 100644
--- a/desktop/lib/notify/system_notifications.dart
+++ b/desktop/lib/notify/system_notifications.dart
@@ -2,6 +2,7 @@ library;
import 'dart:async';
import 'dart:io' show Platform, Process, ProcessException, ProcessResult;
+import 'dart:isolate';
import 'package:flutter/foundation.dart';
import 'package:flutter/services.dart';
@@ -214,11 +215,25 @@ typedef ProcessRunner = Future<ProcessResult> Function(
List<String> arguments,
);
+/// [run] on a short-lived isolate of its own, named for the executable.
+///
+/// Dart starts a process synchronously on the calling isolate: it forks and
+/// waits for the child to exec before `Process.run` returns. On Linux the UI
+/// isolate runs on GTK's main thread (Flutter 3.47), so `notify-send` started
+/// there for every notification held up the frame and the window's events
+/// until the child had been scheduled — 0.22 ms median and up to 18–43 ms on a
+/// loaded Mac (posix_file_mode.dart; Linux not measured). The isolate takes
+/// that wait instead. Its result, and a [ProcessException], come back as they
+/// are.
+ProcessRunner offUiIsolate([ProcessRunner run = Process.run]) =>
+ (executable, arguments) =>
+ Isolate.run(() => run(executable, arguments), debugName: executable);
+
/// Linux: `notify-send`, which talks to whatever notification daemon the
/// desktop already runs. No native dependency, and no click action — the tool
/// has none, so a click does what the desktop's own default is.
class LinuxSystemNotifier implements SystemNotifier {
- LinuxSystemNotifier({ProcessRunner? run}) : _run = run ?? Process.run;
+ LinuxSystemNotifier({ProcessRunner? run}) : _run = run ?? offUiIsolate();
final ProcessRunner _run;
diff --git a/desktop/lib/settings/experimental_features.dart b/desktop/lib/settings/experimental_features.dart
index 1a0a476d3..85ab77df7 100644
--- a/desktop/lib/settings/experimental_features.dart
+++ b/desktop/lib/settings/experimental_features.dart
@@ -159,19 +159,41 @@ class ExperimentalFeaturesStore extends ChangeNotifier {
}
Future<void> _read(int generation, int epoch) async {
+ Map<String, dynamic>? result;
try {
- final result = await _transport!.read();
- if (!_current(generation) || epoch != _epoch) return;
+ result = await _transport!.read();
+ } catch (_) {}
+ if (!_current(generation) || epoch != _epoch) return;
+ final before = _shown();
+ try {
+ if (result == null) throw const FormatException('Unreadable');
_apply(result);
error = null;
errorFeature = null;
} catch (_) {
- if (!_current(generation) || epoch != _epoch) return;
error = 'Couldn’t read your account settings. Refresh to try again.';
}
- _notify();
+ // The fallback poll reads every 30 s and almost always finds nothing new.
+ // Every pane header, the workspace screen (a setState and a native menu
+ // sync) and search listen here, so notifying on each read rebuilt them
+ // twice a minute for every account, on the UI thread whose long frames
+ // production samples (Oct 17: 6.7% of Linux samples over 250 ms, macOS
+ // 0.25%). Only a read that changes what is shown notifies.
+ if (!listEquals(before, _shown())) _notify();
}
+ /// Everything a listener can read after a read: a newer revision that
+ /// changes no choice changes nothing on screen.
+ List<Object?> _shown() => [
+ loaded,
+ error,
+ errorFeature,
+ for (final feature in ExperimentalFeature.values) ...[
+ _choices[feature],
+ _available[feature],
+ ],
+ ];
+
void _apply(Map<String, dynamic> result) {
final revision = result['revision'];
final features = result['features'];
@@ -244,8 +266,8 @@ class ExperimentalFeaturesStore extends ChangeNotifier {
/// One experiment's [ExperimentalFeaturesStore.choice] as a listenable: null
/// until the account's settings are read. It notifies whenever the store does
-/// — every 30 s read among them — so a listener compares with the value it
-/// last saw.
+/// — when any experiment, its availability, a save or an error changes — so a
+/// listener compares with the value it last saw.
class ExperimentChoice implements ValueListenable<bool?> {
const ExperimentChoice(this.store, this.feature);
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index 010b76b74..55c7e9f5c 100644
--- a/desktop/lib/state/app_state.dart
+++ b/desktop/lib/state/app_state.dart
@@ -3986,10 +3986,17 @@ class AppNotifier extends ChangeNotifier {
currentUser?.id != null
? (api, currentUser!.id)
: null;
+ final client = api;
productMeasurement.account(
scope,
choice: () => productUsageSettings(),
- send: api.productUsageReport,
+ // Health names newer than this computer's CLI are counted only once
+ // it has said it forwards them (ProductHealthMeasure.vocabulary).
+ send: (report) => client.productUsageReport(
+ report,
+ onVocabulary: (vocabulary) =>
+ productMeasurement.proxyVocabulary = vocabulary,
+ ),
);
productRuntimeHealth?.account(
scope == null ? null : '$_autonomousEnv:${currentUser!.id}',
diff --git a/desktop/test/experimental_features_test.dart b/desktop/test/experimental_features_test.dart
index 3ebfc5d4c..3b02a4712 100644
--- a/desktop/test/experimental_features_test.dart
+++ b/desktop/test/experimental_features_test.dart
@@ -260,6 +260,49 @@ void main() {
expect(server.reads, reads);
});
+ testWidgets('the 30 s poll notifies only when what it shows changes', (
+ tester,
+ ) async {
+ // Every read used to notify, rebuilding each pane header and the
+ // workspace twice a minute while nothing had changed.
+ final server = AccountSettings('a');
+ final store = ExperimentalFeaturesStore();
+ store.bind('a', transport: server);
+ await tester.pump();
+ var notified = 0;
+ store.addListener(() => notified++);
+ for (var i = 0; i < 3; i++) {
+ await tester.pump(const Duration(seconds: 30));
+ }
+ // A newer revision that changes no choice is nothing new either.
+ server.revision++;
+ await tester.pump(const Duration(seconds: 30));
+ expect(server.reads, 5);
+ expect(notified, 0);
+ server.features[share.id] = true;
+ server.revision++;
+ await tester.pump(const Duration(seconds: 30));
+ expect((notified, store.enabled(share)), (1, true));
+ // An older backend that no longer names one: unavailable is news.
+ server.features.remove(ExperimentalFeature.agentMessages.id);
+ await tester.pump(const Duration(seconds: 30));
+ expect(notified, 2);
+ expect(store.isAvailable(ExperimentalFeature.agentMessages), isFalse);
+ server.readOverride = () => Future.error(StateError('offline'));
+ await tester.pump(const Duration(seconds: 30));
+ expect(notified, 3);
+ expect(store.error, isNotNull);
+ // The same failure again shows nothing new.
+ await tester.pump(const Duration(seconds: 30));
+ expect(notified, 3);
+ server.readOverride = null;
+ await tester.pump(const Duration(seconds: 30));
+ expect(notified, 4);
+ expect(store.error, isNull);
+ // The poll's timer must not outlive the test (fake async checks it).
+ store.dispose();
+ });
+
testWidgets(
'settings show pending saves, uncertain writes and read failures with recovery',
(tester) async {
diff --git a/desktop/test/harness_file_store_test.dart b/desktop/test/harness_file_store_test.dart
index 55731d291..483b89098 100644
--- a/desktop/test/harness_file_store_test.dart
+++ b/desktop/test/harness_file_store_test.dart
@@ -3,6 +3,7 @@ import 'dart:io';
import 'package:harness/auth/auth_session.dart';
import 'package:harness/core/harness_file_store.dart';
+import 'package:harness/core/posix_file_mode.dart';
import 'package:harness/settings/config_store.dart';
import 'package:flutter_test/flutter_test.dart';
@@ -231,6 +232,72 @@ void main() {
skip: Platform.isWindows,
);
+ test(
+ 'writes and repairs start no process, and leave every file private',
+ () async {
+ // Each write used to run /bin/chmod for its temporary file, and a
+ // process starts synchronously on the calling isolate: the UI one.
+ final started = <String>[];
+ final runProcess = HarnessFileStore.runProcess;
+ HarnessFileStore.runProcess = (executable, args) {
+ started.add(executable);
+ return runProcess(executable, args);
+ };
+ addTearDown(() => HarnessFileStore.runProcess = runProcess);
+ final store = HarnessFileStore(directory: dataDirectory);
+ await store.write('credential', 'synthetic-secret');
+ await store.write('credential', 'rotated');
+ final lock = File(
+ '${dataDirectory.path}/${HarnessFileStore.lockFileName}',
+ );
+ // Another program loosened them; the next write repairs all three.
+ for (final (mode, path) in [
+ ('755', dataDirectory.path),
+ ('644', lock.path),
+ ('644', store.stateFile.path),
+ ]) {
+ expect((await Process.run('/bin/chmod', [mode, path])).exitCode, 0);
+ }
+ await store.write('preference', 'kept');
+ expect(started, isEmpty);
+ expect(await store.read('credential'), 'rotated');
+ expect((await dataDirectory.stat()).mode & 0xfff, 0x1c0);
+ final files = (await dataDirectory.list().toList()).whereType<File>();
+ expect(files.map((f) => f.uri.pathSegments.last).toSet(), {
+ HarnessFileStore.fileName,
+ HarnessFileStore.lockFileName,
+ });
+ for (final file in files) {
+ expect((await file.stat()).mode & 0xfff, 0x180, reason: file.path);
+ }
+ },
+ skip: !PosixFileMode.supported,
+ );
+
+ test(
+ 'libc modes: an exact new file, a refused existing one, a changed mode',
+ () async {
+ await dataDirectory.create(recursive: true);
+ final path = '${dataDirectory.path}/private';
+ PosixFileMode.createExclusive(path, 0x180);
+ expect((await File(path).stat()).mode & 0xfff, 0x180);
+ expect(await File(path).length(), 0);
+ await File(path).writeAsString('kept');
+ expect(
+ () => PosixFileMode.createExclusive(path, 0x180),
+ throwsA(isA<FileSystemException>()),
+ );
+ expect(await File(path).readAsString(), 'kept');
+ PosixFileMode.chmod(dataDirectory.path, 0x1c0);
+ expect((await dataDirectory.stat()).mode & 0xfff, 0x1c0);
+ expect(
+ () => PosixFileMode.chmod('$path-missing', 0x180),
+ throwsA(isA<FileSystemException>()),
+ );
+ },
+ skip: !PosixFileMode.supported,
+ );
+
test(
'a replacement directory at the same path is made private again',
() async {
diff --git a/desktop/test/product_delivery_test.dart b/desktop/test/product_delivery_test.dart
index c712d705e..7ad6f2e04 100644
--- a/desktop/test/product_delivery_test.dart
+++ b/desktop/test/product_delivery_test.dart
@@ -2,6 +2,7 @@ import 'dart:async';
import 'dart:convert';
import 'dart:io';
+import 'package:dio/dio.dart' show Headers;
import 'package:flutter_test/flutter_test.dart';
import 'package:harness/api/api_client.dart';
import 'package:harness/auth/auth_session.dart';
@@ -16,13 +17,14 @@ void main() {
late ProductMeasurement usage;
late List<Map<String, dynamic>> attempts, accepted;
var status = 200;
- String? code;
+ String? code, vocabulary;
Completer<void>? hold;
setUp(() async {
attempts = [];
accepted = [];
status = 200;
code = null;
+ vocabulary = null;
hold = null;
server = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
listener = server.listen((request) async {
@@ -33,8 +35,15 @@ void main() {
expect(request.headers.value('x-adapter-local'), '1');
attempts.add(report);
final responseStatus = status, responseCode = code;
+ final responseVocabulary = vocabulary;
await hold?.future;
if (responseStatus == 200) accepted.add(report);
+ if (responseVocabulary != null) {
+ request.response.headers.set(
+ ApiClient.usageVocabularyHeader,
+ responseVocabulary,
+ );
+ }
request.response
..statusCode = responseStatus
..headers.contentType = ContentType.json
@@ -163,6 +172,66 @@ void main() {
},
);
+ test(
+ 'frame-phase names are counted only after the CLI says it forwards them',
+ () async {
+ // An older CLI refused a whole report for one name it did not know,
+ // and this app drops a refused packet for good.
+ usage.account(
+ 'PRIVATE_ACCOUNT_CANARY_WIRED',
+ choice: () async => {'enabled': true, 'revision': 0},
+ send: (report) => api.productUsageReport(
+ report,
+ onVocabulary: (value) => usage.proxyVocabulary = value,
+ ),
+ );
+ await usage.flush();
+ void slowFrame() {
+ usage.health(ProductHealthMeasure.frame50msTo250ms);
+ usage.health(ProductHealthMeasure.frameSlowWait);
+ }
+
+ slowFrame();
+ await usage.flush(); // an older CLI: no header
+ expect(usage.proxyVocabulary, 1);
+ slowFrame();
+ vocabulary = '2';
+ await usage.flush();
+ expect(usage.proxyVocabulary, 2);
+ slowFrame();
+ await usage.flush();
+ expect(totals()['health_desktop_frame_50ms_to_250ms'], 3);
+ expect(totals()['health_desktop_frame_slow_wait'], 1);
+ expect(
+ attempts.take(2).map((r) => r['counters'] as Map),
+ everyElement(isNot(contains('health_desktop_frame_slow_wait'))),
+ );
+ // Replaced by an older CLI: after an answer that says nothing, the
+ // names stop until one says so again, which a refusal does too.
+ vocabulary = null;
+ usage.health(ProductHealthMeasure.frame50msTo250ms);
+ await usage.flush();
+ expect(usage.proxyVocabulary, 1);
+ slowFrame();
+ (status, vocabulary) = (400, '2');
+ await usage.flush();
+ expect(usage.proxyVocabulary, 2);
+ expect(totals()['health_desktop_frame_slow_wait'], 1);
+ },
+ );
+
+ test('the vocabulary header reads as 1 unless it names a later one', () {
+ int read(List<String>? value) => ApiClient.usageVocabulary(
+ Headers.fromMap({'x-harness-usage-vocabulary': ?value}),
+ );
+ expect(read(null), 1);
+ expect(read(['2']), 2);
+ expect(read(['3']), 3);
+ for (final junk in ['0', '-2', '', 'PRIVATE', '2.5']) {
+ expect(read([junk]), 1, reason: junk);
+ }
+ });
+
for (final (http, errorCode, measure) in [
(401, 'PRIVATE_CODE', ProductHealthMeasure.reportFailureAuth),
(403, null, ProductHealthMeasure.reportFailureAuth),
diff --git a/desktop/test/product_health_test.dart b/desktop/test/product_health_test.dart
index a5d70371d..4db1d146a 100644
--- a/desktop/test/product_health_test.dart
+++ b/desktop/test/product_health_test.dart
@@ -288,6 +288,94 @@ void main() {
},
);
+ testWidgets(
+ 'a slow sample counts its longest phase, and a long one once a day, '
+ 'only once the CLI forwards the names',
+ (tester) async {
+ final runtime = ProductRuntimeHealth(
+ usage,
+ readState: () async => {},
+ writeState: (_) async {},
+ readVersion: () async => '1.2.73',
+ lifecycle: () => AppLifecycleState.resumed,
+ );
+ runtime.account('PRIVATE_ACCOUNT');
+ await usage.flush();
+ await tester.pump();
+ // Milliseconds from vsync: waiting for the UI thread, building, the
+ // raster thread's queue, rastering.
+ FrameTiming frame({
+ int wait = 0,
+ int build = 0,
+ int queue = 0,
+ int raster = 0,
+ }) {
+ final buildStart = wait * 1000;
+ final buildFinish = buildStart + build * 1000;
+ final rasterStart = buildFinish + queue * 1000;
+ final rasterFinish = rasterStart + raster * 1000;
+ return FrameTiming(
+ vsyncStart: 0,
+ buildStart: buildStart,
+ buildFinish: buildFinish,
+ rasterStart: rasterStart,
+ rasterFinish: rasterFinish,
+ rasterFinishWallTime: rasterFinish,
+ );
+ }
+
+ // The 60th frame is the sample.
+ void sample(FrameTiming timing) => runtime.framesForTest([
+ for (var i = 0; i < 59; i++) frame(build: 1),
+ timing,
+ ]);
+ Iterable<String> newNames() => totals().keys.where(
+ (key) => key.contains('_slow_') || key.contains('_long_'),
+ );
+ // A CLI that has not said it forwards them would refuse the report.
+ sample(frame(wait: 300));
+ await usage.flush();
+ expect(totals()['health_desktop_frame_over_250ms'], 1);
+ expect(newNames(), isEmpty);
+ usage.proxyVocabulary = 2;
+ for (final timing in [
+ frame(wait: 40, build: 10, raster: 5),
+ frame(wait: 20, build: 20, raster: 20), // a tie: the earlier phase
+ frame(wait: 5, build: 60, raster: 20),
+ frame(wait: 10, build: 300), // the day's first long sample
+ frame(wait: 5, build: 10, queue: 30, raster: 20),
+ frame(raster: 400), // long again: the day is counted already
+ frame(wait: 10, build: 30), // 40 ms is not slow
+ ]) {
+ sample(timing);
+ }
+ await usage.flush();
+ expect(totals()['health_desktop_frame_slow_wait'], 2);
+ expect(totals()['health_desktop_frame_slow_build'], 2);
+ expect(totals()['health_desktop_frame_slow_raster'], 2);
+ expect(totals()['health_desktop_frame_long_collector'], 1);
+ // Every slow sample since has one phase.
+ expect(
+ totals()['health_desktop_frame_50ms_to_250ms']! +
+ totals()['health_desktop_frame_over_250ms']! -
+ 1,
+ 6,
+ );
+ // The next UTC day's first long sample counts again, once.
+ now = now.add(const Duration(days: 1));
+ sample(frame(wait: 260));
+ sample(frame(wait: 260));
+ // One report a flush: yesterday's expired workspace observation first.
+ await usage.flush();
+ await usage.flush();
+ expect(totals()['health_desktop_frame_long_collector'], 2);
+ expect(totals()['health_desktop_collector_days'], 2);
+ expect(jsonEncode(reports), isNot(contains('PRIVATE')));
+ runtime.dispose();
+ await tester.pump();
+ },
+ );
+
testWidgets(
'relaunch confirms only the expected public version and sharing revision',
(tester) async {
diff --git a/desktop/test/system_notifications_test.dart b/desktop/test/system_notifications_test.dart
index 1d054952c..ca9b8af51 100644
--- a/desktop/test/system_notifications_test.dart
+++ b/desktop/test/system_notifications_test.dart
@@ -2,7 +2,8 @@
// is somewhere else. When it is posted, what replaces what, what takes it down, what a click does,
// and how each platform's notifier is driven.
import 'dart:async';
-import 'dart:io' show ProcessException, ProcessResult;
+import 'dart:io' show Platform, ProcessException, ProcessResult;
+import 'dart:isolate';
import 'dart:ui' show SemanticsAction, Tristate;
import 'package:flutter/material.dart';
@@ -709,6 +710,48 @@ void main() {
expect(ran.last, contains('--print-id'));
});
+ test(
+ 'notify-send starts on an isolate of its own, not the UI one',
+ () async {
+ // A process starts synchronously on the calling isolate, which on Linux
+ // is GTK's main thread: it used to, for every notification.
+ final run = offUiIsolate(
+ (exe, args) async =>
+ ProcessResult(0, 0, Isolate.current.debugName, args.join(' ')),
+ );
+ final result = await run('notify-send', ['--version']);
+ expect(result.stdout, 'notify-send');
+ expect(result.stderr, '--version');
+ expect(Isolate.current.debugName, isNot('notify-send'));
+ // Its answers reach the notifier as they are, a missing tool included.
+ final posted = LinuxSystemNotifier(
+ run: offUiIsolate((_, _) async => ProcessResult(0, 0, '42\n', '')),
+ );
+ expect(await post(posted), NotificationPermission.granted);
+ final missing = LinuxSystemNotifier(
+ run: offUiIsolate(
+ (_, _) async => throw const ProcessException('notify-send', []),
+ ),
+ );
+ expect(await missing.authorize(), NotificationPermission.unavailable);
+ expect(await post(missing), NotificationPermission.unavailable);
+ },
+ );
+
+ test(
+ 'off the UI isolate a real process still answers, or is missing',
+ () async {
+ final run = offUiIsolate();
+ final result = await run('/bin/sh', ['-c', 'printf ok; exit 3']);
+ expect((result.exitCode, result.stdout), (3, 'ok'));
+ await expectLater(
+ run('harness-test-no-such-notify-send', []),
+ throwsA(isA<ProcessException>()),
+ );
+ },
+ skip: Platform.isWindows,
+ );
+
test(
'a desktop without notify-send is unavailable, not an error',
() async {
diff --git a/docs/product-measurement.md b/docs/product-measurement.md
index 10e400408..5f7068170 100644
--- a/docs/product-measurement.md
+++ b/docs/product-measurement.md
@@ -15,6 +15,7 @@ automatically proven improvement. Changes still need review, tests and a deliber
| Do installations return to work? | D1/D7/D28 working-day cohorts, consecutive complete-week and calendar-month returns, return after a seven-day gap | Any working day can be a cohort; not new-signup retention. Local date flags produce unlinked totals. Opt-outs, reinstallations, resets and missing uploads affect results. |
| Was the task useful? | Optional Completed / Partly completed / Not completed plus five fixed reason choices from clients that offer feedback; current Desktop Settings no longer exposes feedback controls | 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. |
+| Why are Desktop frames long, and on how many computers? | One in 60 rendered frames by duration; a sample of 50 ms or more also by its longest phase (`frame_slow_wait`, `frame_slow_build`, `frame_slow_raster`); once per collector day, the first sample over 250 ms (`frame_long_collector`) | Wait is the UI thread busy before the frame could start (on macOS and Linux the platform's main thread: timers, channel and native callbacks, synchronous IO, AppKit or GTK); build is the framework's build, layout and paint; raster is drawing. The phases add up to the samples of 50 ms or more counted beside them. `frame_long_collector` over `collector_days` is the share of collector days with a long sample: many long samples on few such days are a few computers, not a broad problem. Counted only once the computer's CLI has announced them (below), so not before a run's first report answer or behind an older CLI; compare releases separately. |
| 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; a setup step whose tool was missing at a check (`setup_desktop_setup_<step>_missing`); the agents a new computer downloads beside setup (`setup_desktop_agent_download_<opencode\|codex\|claude>_started`, `_ok`, `_failed`, with under 1 min, 1–5 min and over 5 min) | 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. A setup step stays open from the first check until its tool is in place, so a tool that was missing and then installed is one ok step and one `_missing` mark; only a setup that ends failed fails its step. Earlier Desktop releases counted every check that found a tool missing as a failed step (on 2026-10-16 the Harness step read 72 failed of 221 while 0 setups failed): compare releases separately. `_missing` is any tool a check found absent or out of date (a Harness CLI older than this Desktop needs, on a computer already in use, counts too), not only new computers. A step left waiting (the review, a Linux Terminal handoff, manual mode, someone who walks away) now ends `unknown` at the 15-minute observation bound instead of `failed`, so expect `setup_*_unknown` to rise, mostly on Linux. `_missing` and the download counts are anonymous setup counts only. A download whose prerequisite (curl, Harness's Node) never arrived counts as started and failed; `ok` means the agent's program is in place, judged per engine. |
@@ -86,7 +87,15 @@ The startup bucket measures launch to the first consented observation of a conne
including preference/sign-in delay. One in 60 rendered frames supplies a coarse duration bucket;
it cannot reliably detect an idle freeze. Frames of a hidden, minimised or occluded window, and the
first frame after it is shown again, are not sampled (the OS throttles them), nor is each launch's
-first frame, which `app_start` already times; earlier releases sampled both. Error hooks pass only framework/async categories.
+first frame, which `app_start` already times; earlier releases sampled both. A sample of 50 ms or more
+also counts its longest phase: `frame_slow_wait` (vsync to build start, the UI thread busy with
+something else first), `frame_slow_build` or `frame_slow_raster`, a tie going to the earlier one; the
+wait for a raster thread still busy with an earlier frame is no phase of its own. The first sample over
+250 ms of each collector day also counts `frame_long_collector`, so long frames can be told broad or
+concentrated against `collector_days`. These four are counted only while the latest report answer
+from the local CLI named counter vocabulary 2 or later (`x-harness-usage-vocabulary`), because an
+older proxy refused a whole report for one name it did not know; samples before a run's first answer
+count only their duration. Error hooks pass only framework/async categories.
Desktop RSS samples once per minute and gateway RSS/CPU once per report tick (45 to 75 seconds, a
minute on average); they describe those processes, not the whole machine or agents. Sampling adds
no core timer, process enumeration, or subprocess.
@@ -146,6 +155,12 @@ or oversized packet is discarded so it cannot block newer reports; transient err
same receipt. Delayed errors after a choice or account change are discarded.
The local app proxy accepts only bounded UI counts, or Desktop health/UI counts with the exact
public release, OS and channel context. It does not accept daemon counters or arbitrary context.
+Like the backend, it keeps a report whose only problem is a counter name this CLI does not know yet:
+the name is dropped, never forwarded or logged, and a Desktop report counts
+`health_desktop_report_unknown_metric` once. Earlier CLIs refused the whole report, and the Desktop
+discards a refused packet. A known name an app may not send, a bad value, or a report with no known
+counter left is still refused. Every answer of that route carries `x-harness-usage-vocabulary`, the
+revision of the names it forwards (2: the frame phases); a Desktop counts newer names only after reading it.
Desktop and phone collectors keep only fixed counters in RAM, at most 64 in-flight observations,
with at most 32 counters per report, one pending report per channel and one flush at a time.