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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
Reduce desktop log flushes and preserve concurrent writes (#587)
Deeea5afd5ad197
diff --git a/.github/workflows/desktop-logging-checks.yml b/.github/workflows/desktop-logging-checks.ymlnew file mode 100644index 000000000..58794236c--- /dev/null+++ b/.github/workflows/desktop-logging-checks.yml@@ -0,0 +1,57 @@+name: Desktop logging checks++on:+ pull_request:+ paths:+ - 'desktop/lib/logging/**'+ - 'desktop/test/app_log_test.dart'+ - 'desktop/test/buffered_log_test.dart'+ - 'desktop/test/crash_log_test.dart'+ - 'desktop/test/dial_log_tail_test.dart'+ - 'desktop/test/log_*_test.dart'+ - 'desktop/test/export_logs_dialog_test.dart'+ - 'desktop/test/cli_transcript_test.dart'+ - 'desktop/tool/log_append_probe.dart'+ - '.github/workflows/desktop-logging-checks.yml'+ workflow_dispatch:++permissions:+ contents: read++jobs:+ test:+ strategy:+ fail-fast: false+ matrix:+ os: [ubuntu-24.04, macos-15]+ runs-on: ${{ matrix.os }}+ timeout-minutes: 20+ defaults:+ run:+ working-directory: desktop+ steps:+ - uses: actions/checkout@v7+ - id: toolchain+ run: |+ version="$(sed -n "s/^ FLUTTER_VERSION: '\([^']*\)'.*/\1/p" ../.github/workflows/release-desktop.yml)"+ test -n "$version"+ echo "version=$version" >> "$GITHUB_OUTPUT"+ - uses: subosito/flutter-action@v2+ with:+ flutter-version: ${{ steps.toolchain.outputs.version }}+ channel: stable+ cache: true+ - if: runner.os == 'macOS'+ run: flutter config --enable-swift-package-manager+ - run: flutter pub get+ - name: Concurrent native process append+ run: dart run tool/log_append_probe.dart+ - name: Real-file and desktop logging regressions+ run: >-+ flutter test --no-pub --reporter expanded+ test/buffered_log_test.dart test/app_log_test.dart+ test/crash_log_test.dart test/log_stream_test.dart+ test/cli_transcript_test.dart test/log_redact_test.dart+ test/dial_log_tail_test.dart+ test/ws_conn_test.dart test/swarm_async_test.dart+ test/export_logs_dialog_test.dartdiff --git a/desktop/CLAUDE.md b/desktop/CLAUDE.mdindex 2fd3e0cf1..2a93f01cf 100644--- a/desktop/CLAUDE.md+++ b/desktop/CLAUDE.md@@ -569,7 +569,11 @@ its headless debug timings do not establish native display or network latency.`redactSecretsInText` (`logging/redact.dart`, beside the frame-level `redactValue`) beforeanything is written. The Debug pane is a **mirror** of those sinks, not a second stream(`log_stream.dart` + `log_stream_sinks.dart`): a bounded ring of the last 500 entries that- `installFileLogs` tees into, so a line on screen is a line the file already has. It is developer+ `installFileLogs` tees into. Routine DEBUG records use a one-second flush deadline,+ 256 entries or 64 Ki characters. INFO/WARN and admitted ERROR records flush their preceding context;+ export, backgrounding, normal quit and updater handoff also flush. An abrupt process kill+ can lose the pending DEBUG batch. CLI transcripts remain immediately+ flushed. No timer runs with an empty buffer. It is developerfurniture — `kDebugSurfaceEnabled` (`logging/debug_surface.dart`, `kDebugMode` or`--dart-define=HARNESS_DEBUG_SURFACE=true`) gates the rail row, the ⌘D shortcut(`kDebugShortcut`, in `appShortcuts()` rather than `kAppShortcuts`) and the ring itself; the logdiff --git a/desktop/lib/app_shell.dart b/desktop/lib/app_shell.dartindex 48ce8a8c3..7d9365afa 100644--- a/desktop/lib/app_shell.dart+++ b/desktop/lib/app_shell.dart@@ -204,11 +204,17 @@ class _RootShellState extends ConsumerState<RootShell>@overridevoid dispose() {+ flushAppLog();WidgetsBinding.instance.removeObserver(this);_appMenuChannel.setMethodCallHandler(null);super.dispose();}+ @override+ void didChangeAppLifecycleState(AppLifecycleState state) {+ if (state != AppLifecycleState.resumed) flushAppLog();+ }+@overrideFuture<AppExitResponse> didRequestAppExit() async {final app = ref.read(appStateProvider);@@ -217,10 +223,14 @@ class _RootShellState extends ConsumerState<RootShell>if (app.canCancelLogin) app.cancelLogin();// Save the final arrangement, with a bound so an unavailable disk cannot// trap the user in the app. Input and tab switching never wait for disk.- await app.flushPaneLayout().timeout(- const Duration(seconds: 1),- onTimeout: () {},- );+ try {+ await app.flushPaneLayout().timeout(+ const Duration(seconds: 1),+ onTimeout: () {},+ );+ } finally {+ flushAppLog();+ }return AppExitResponse.exit;}diff --git a/desktop/lib/logging/app_log.dart b/desktop/lib/logging/app_log.dartindex d619003be..9ed3fbedd 100644--- a/desktop/lib/logging/app_log.dart+++ b/desktop/lib/logging/app_log.dart@@ -32,6 +32,17 @@ abstract interface class AppLog {});}+/// File-backed sinks expose their pending diagnostics without requiring+/// in-memory sinks or test recorders to manage a buffer.+abstract interface class FlushableAppLog implements AppLog {+ void flush();+}++void flushAppLog() {+ final sink = appLog;+ if (sink is FlushableAppLog) sink.flush();+}+/// Level-named conveniences over [AppLog.record], kept as extensions so every/// [AppLog] implementation gets them for free without re-declaring the surface.extension AppLogX on AppLog {@@ -59,13 +70,22 @@ extension AppLogX on AppLog {}/// [AppLog] backed by a per-day file under `~/.harness/logs`. Writes are-/// synchronous and flushed (see [DailyLogFile]); IO errors are swallowed.-class FileAppLog implements AppLog {- FileAppLog(this._file, {ErrorBurstFilter? burst, DateTime Function()? clock})- : _burst = burst ?? ErrorBurstFilter(),- _clock = clock ?? DateTime.now;+/// synchronous and flushed except when [bufferDebug] is enabled for routine+/// debug entries. Errors and lifecycle records also commit pending context.+class FileAppLog implements FlushableAppLog {+ FileAppLog(+ this._file, {+ this.bufferDebug = false,+ ErrorBurstFilter? burst,+ DateTime Function()? clock,+ }) : _burst = burst ?? ErrorBurstFilter(),+ _clock = clock ?? DateTime.now;final DailyLogFile _file;+ final bool bufferDebug;++ @override+ void flush() => _file.flush();/// Injected so the stamp this writes is a thing a test can assert, rather than/// a thing a test has to watch happen. Same reason [ErrorBurstFilter] takes one.@@ -95,17 +115,20 @@ class FileAppLog implements AppLog {if (error != null) body.write(' err=$error');if (level != AppLogLevel.error) {- _file.append('[${logStamp(_clock())}] $body');- _appendStack(stackTrace);+ final buffered = bufferDebug && level == AppLogLevel.debug;+ _file.append('[${logStamp(_clock())}] $body', buffered: buffered);+ _appendStack(stackTrace, buffered: buffered);return;}+ // A suppressed per-frame error must not turn interleaved debug traffic+ // back into a per-frame fsync. Its context keeps the normal batch deadline.final admitted = _burst.admit(body.toString());if (admitted == null) return;_file.append('[${logStamp(_clock())}] $admitted');_appendStack(stackTrace);}- void _appendStack(StackTrace? stackTrace) {+ void _appendStack(StackTrace? stackTrace, {bool buffered = false}) {if (stackTrace == null) return;_file.append(stackTrace@@ -114,6 +137,7 @@ class FileAppLog implements AppLog {.split('\n').map((l) => ' $l').join('\n'),+ buffered: buffered,);}diff --git a/desktop/lib/logging/install.dart b/desktop/lib/logging/install.dartindex 002a1d7c5..265662bc3 100644--- a/desktop/lib/logging/install.dart+++ b/desktop/lib/logging/install.dart@@ -28,15 +28,18 @@ void installFileLogs() {return;}final directory = DailyLogFile.defaultDirectory;- final file = FileAppLog(DailyLogFile(directory, kAppLogBase));+ final file = FileAppLog(+ DailyLogFile(directory, kAppLogBase),+ bufferDebug: true,+ );final cli = FileCliLog(DailyLogFile(directory, kCliLogBase));if (!kDebugSurfaceEnabled) {appLog = file;cliLog = cli;return;}- // The file first in both fan-outs: if the mirror ever throws, the durable- // copy is already written.+ // The file first in both fan-outs: if the mirror ever throws, the record+ // has already reached the file sink (routine debug entries may be buffered).appLog = FanoutAppLog([file, StreamAppLog(logStream)]);cliLog = FanoutCliLog([cli, StreamCliLog(logStream)]);// The dial's log is the daemon's to write; this app only reads it. Taileddiff --git a/desktop/lib/logging/log_append.dart b/desktop/lib/logging/log_append.dartnew file mode 100644index 000000000..45f02b9dd--- /dev/null+++ b/desktop/lib/logging/log_append.dart@@ -0,0 +1 @@+export 'log_append_io.dart' if (dart.library.ffi) 'log_append_native.dart';diff --git a/desktop/lib/logging/log_append_io.dart b/desktop/lib/logging/log_append_io.dartnew file mode 100644index 000000000..d5ddc1dea--- /dev/null+++ b/desktop/lib/logging/log_append_io.dart@@ -0,0 +1,5 @@+import 'dart:io';++void appendDurableLog(File file, String contents) {+ file.writeAsStringSync(contents, mode: FileMode.append, flush: true);+}diff --git a/desktop/lib/logging/log_append_native.dart b/desktop/lib/logging/log_append_native.dartnew file mode 100644index 000000000..1829b250b--- /dev/null+++ b/desktop/lib/logging/log_append_native.dart@@ -0,0 +1,95 @@+import 'dart:convert';+import 'dart:ffi';+import 'dart:io';++import 'package:ffi/ffi.dart';++import 'log_append_io.dart' as fallback;++/// Dart's FileMode.append seeks to EOF when opening, rather than using+/// O_APPEND. Another window can append between that seek and the write,+/// causing the two writers to overwrite each other. Use a kernel append on+/// the desktop POSIX hosts; no file lock or polling is needed.+void appendDurableLog(File file, String contents) {+ if (!Platform.isMacOS && !Platform.isLinux) {+ fallback.appendDurableLog(file, contents);+ return;+ }+ _posix.append(file.path, contents);+}++final _posix = _PosixAppend();++class _PosixAppend {+ 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 _write = _library+ .lookupFunction<+ IntPtr Function(Int, Pointer<Uint8>, UintPtr),+ int Function(int, Pointer<Uint8>, int)+ >('write');+ late final _sync = _library+ .lookupFunction<Int Function(Int), int Function(int)>('fsync');+ late final _close = _library+ .lookupFunction<Int Function(Int), int Function(int)>('close');+ late final _errno = _library+ .lookupFunction<Pointer<Int> Function(), Pointer<Int> Function()>(+ Platform.isMacOS ? '__error' : '__errno_location',+ );++ void append(String path, String contents) {+ if (path.contains('\u0000')) {+ throw ArgumentError.value(path, 'path', 'Contains a NUL byte');+ }+ final bytes = utf8.encode(contents);+ using((arena) {+ final name = path.toNativeUtf8(allocator: arena);+ final data = arena<Uint8>(bytes.length);+ data.asTypedList(bytes.length).setAll(0, bytes);+ // O_WRONLY | O_CREAT | O_APPEND | O_CLOEXEC. The descriptor never+ // escapes a call, even on a partial write, signal or disk failure.+ final flags = Platform.isMacOS+ ? 0x1 | 0x200 | 0x8 | 0x1000000+ : 0x1 | 0x40 | 0x400 | 0x80000;+ final close = _close;+ final fd = _retry(() => _open(name, flags, 0x1b6), path);+ try {+ var offset = 0;+ while (offset < bytes.length) {+ final written = _retry(+ () => _write(fd, data + offset, bytes.length - offset),+ path,+ );+ if (written == 0) {+ throw FileSystemException('Log append made no progress', path);+ }+ offset += written;+ }+ _retry(() => _sync(fd), path);+ } finally {+ // Do not retry close on EINTR: the fd may already have been released+ // and reused by another thread.+ close(fd);+ }+ });+ }++ int _retry(int Function() operation, String path) {+ final readErrno = _errno;+ while (true) {+ final result = operation();+ if (result >= 0) return result;+ final error = readErrno().value;+ if (error == 4) continue; // EINTR+ throw FileSystemException(+ 'Could not append or flush diagnostic log',+ path,+ OSError('POSIX log write failed', error),+ );+ }+ }+}diff --git a/desktop/lib/logging/log_export.dart b/desktop/lib/logging/log_export.dartindex d1666dbae..8f6b8e1b8 100644--- a/desktop/lib/logging/log_export.dart+++ b/desktop/lib/logging/log_export.dart@@ -1,6 +1,7 @@import 'dart:convert';import '../core/harness_cli_runner.dart';+import 'app_log.dart';/// What `harness logs export --json` answered.class LogExportResult {@@ -19,6 +20,7 @@ class LogExportResult {/// window needs the same export. This app adds nothing to it but a button.Future<LogExportResult> exportLogs(HarnessCliRunner runner) async {try {+ flushAppLog();final result = await runner.run(const ['logs', 'export', '--json']);final out = (result.stdout as String).trim();if (result.exitCode != 0 || out.isEmpty) {diff --git a/desktop/lib/logging/log_file.dart b/desktop/lib/logging/log_file.dartindex 453407a14..4cb60a1d6 100644--- a/desktop/lib/logging/log_file.dart+++ b/desktop/lib/logging/log_file.dart@@ -1,7 +1,9 @@+import 'dart:async';import 'dart:developer' as developer;import 'dart:io';import '../core/harness_file_store.dart';+import 'log_append.dart';/// Best-effort append-only diagnostic log split into one file per calendar day/// (`<base>-YYYYMMDD.log`) inside a directory.@@ -11,25 +13,32 @@ import '../core/harness_file_store.dart';/// so a log line means the same thing in both products. Keep the two in step.////// Why per-day: a single ever-growing file eventually becomes too big to open or-/// send us, and a size-based `.old` rotation keeps only the last slice. Dating-/// the file caps each day's size on its own and lets anything past-/// [retentionDays] be pruned automatically, so the directory stays bounded-/// without ever discarding the current session.+/// send us, and a size-based `.old` rotation keeps only the last slice. Dated+/// files let anything past [retentionDays] be pruned automatically. This caps+/// retained age, not a busy day's byte count.///-/// Writes are synchronous and flushed so a line survives even if the app is-/// force-quit mid-write, and every IO error is swallowed — diagnostic logging-/// must never break the flow it only observes.+/// Immediate writes are synchronous and flushed. Routine diagnostics may opt+/// into bounded batches; an immediate write also commits the pending context.+/// Every IO error is swallowed — diagnostics must never break the flow they+/// only observe.class DailyLogFile {DailyLogFile(this.directory,this.base, {this.retentionDays = 14,+ this.bufferInterval = const Duration(seconds: 1),+ this.maxBufferedCharacters = 64 * 1024,+ this.maxBufferedEntries = 256,+ this.appendFile = appendDurableLog,DateTime Function() clock = DateTime.now,// The field is private, so an initialising formal would name the// PARAMETER `_clock` — which no caller outside this library could pass.// The clock is injected by tests.- // ignore: prefer_initializing_formals- }) : _clock = clock;+ }) : assert(bufferInterval > Duration.zero),+ assert(maxBufferedCharacters > 0),+ assert(maxBufferedEntries > 0),+ // ignore: prefer_initializing_formals+ _clock = clock;/// The app's own log directory, `~/.harness/logs`.///@@ -49,6 +58,22 @@ class DailyLogFile {/// the first time a new day is written. A value `<= 0` disables pruning.final int retentionDays;+ /// A one-shot deadline from the first pending entry, never an idle poll.+ final Duration bufferInterval;++ /// Bound both text and entry overhead during bursts. Oversized entries are+ /// written directly; they cannot remain in the pending buffer.+ final int maxBufferedCharacters;+ final int maxBufferedEntries;++ /// Durable append implementation, injectable for measurements using real IO.+ final void Function(File file, String contents) appendFile;++ final List<String> _pending = [];+ int _pendingCharacters = 0;+ DateTime? _pendingAt;+ Timer? _bufferTimer;+final DateTime Function() _clock;/// `YYYYMMDD` of the file we last wrote, so pruning only runs when the day@@ -65,9 +90,59 @@ class DailyLogFile {/// Append [block] followed by a newline to today's file. Creates the directory/// on demand and prunes stale days on the first write after midnight; any/// failure is swallowed.- void append(String block) {+ void append(String block, {bool buffered = false}) {try {final now = _clock();+ if (_pendingAt case final at? when _ymd(at) != _ymd(now)) {+ // A timer firing after midnight must not move yesterday's records into+ // today's file. The same rule handles a wall-clock correction.+ flush();+ }+ if (!buffered || block.length + 1 >= maxBufferedCharacters) {+ if (_pending.isEmpty) {+ _appendNow(block, now);+ } else {+ // The diagnostic and the lines leading to it share one durable write.+ _pending.add(block);+ flush();+ }+ return;+ }+ if (_pendingCharacters + block.length + 1 > maxBufferedCharacters) {+ flush();+ }+ _pendingAt ??= now;+ _pending.add(block);+ _pendingCharacters += block.length + 1;+ if (_pending.length >= maxBufferedEntries ||+ _pendingCharacters >= maxBufferedCharacters) {+ flush();+ } else {+ _bufferTimer ??= Timer(bufferInterval, flush);+ }+ } catch (e) {+ _debugLog('DailyLogFile.append failed: $e');+ }+ }++ /// Commit any pending batch and cancel its timer. Empty flushes do no IO.+ /// Called on errors, export, backgrounding, normal quit and updater handoff.+ void flush() {+ _bufferTimer?.cancel();+ _bufferTimer = null;+ if (_pending.isEmpty) return;+ final block = _pending.join('\n');+ final at = _pendingAt!;+ // Release the batch even on disk failure, matching append's best-effort+ // behavior without retaining an unbounded retry queue.+ _pending.clear();+ _pendingCharacters = 0;+ _pendingAt = null;+ _appendNow(block, at);+ }++ void _appendNow(String block, DateTime now) {+ try {final day = _ymd(now);final file = _fileFor(now);file.parent.createSync(recursive: true);@@ -75,7 +150,7 @@ class DailyLogFile {_activeDay = day;_pruneOlderThan(now);}- file.writeAsStringSync('$block\n', mode: FileMode.append, flush: true);+ appendFile(file, '$block\n');} catch (e) {// Best-effort: never surface an IO failure into the caller's flow._debugLog('DailyLogFile.append failed: $e');diff --git a/desktop/lib/logging/log_stream_sinks.dart b/desktop/lib/logging/log_stream_sinks.dartindex ae025e900..ce455c8d5 100644--- a/desktop/lib/logging/log_stream_sinks.dart+++ b/desktop/lib/logging/log_stream_sinks.dart@@ -3,8 +3,8 @@////// A mirror rather than a second stream. Every call site keeps writing to the/// one `appLog`/`cliLog` it already writes to, so a line cannot reach the-/// screen without reaching the file — which is what makes "read it in Settings-/// ▸ Debug" and "send us the log" the same evidence.+/// screen without also being queued for the file. Export flushes pending+/// routine diagnostics before collecting "send us the log" evidence.library;import 'app_log.dart';@@ -12,11 +12,18 @@ import 'cli_log.dart';import 'log_stream.dart';/// Writes one event to each of [sinks], in order.-class FanoutAppLog implements AppLog {+class FanoutAppLog implements FlushableAppLog {const FanoutAppLog(this.sinks);final List<AppLog> sinks;+ @override+ void flush() {+ for (final sink in sinks) {+ if (sink is FlushableAppLog) sink.flush();+ }+ }+@overridevoid record(AppLogLevel level,diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dartindex 662c61cb6..60fde96f2 100644--- a/desktop/lib/state/app_state.dart+++ b/desktop/lib/state/app_state.dart@@ -5095,6 +5095,7 @@ class AppNotifier extends ChangeNotifier {'This copy of Harness cannot install updates automatically.';return false;}+ flushAppLog();exit(0);} catch (error) {updateError = 'Could not install Harness ${info.version}: $error';diff --git a/desktop/test/benchmarks/diagnostic_log_benchmark.dart b/desktop/test/benchmarks/diagnostic_log_benchmark.dartnew file mode 100644index 000000000..b56ff0918--- /dev/null+++ b/desktop/test/benchmarks/diagnostic_log_benchmark.dart@@ -0,0 +1,138 @@+// Run explicitly with `flutter test --no-pub test/benchmarks/diagnostic_log_benchmark.dart`.+// Real temporary files, alternating order, identical final bytes. Measures the+// logging component, not app CPU, frame latency, battery life or energy impact.+import 'dart:convert';+import 'dart:io';++import 'package:flutter_test/flutter_test.dart';+import 'package:harness/logging/app_log.dart';+import 'package:harness/logging/log_append.dart';+import 'package:harness/logging/log_file.dart';++void main() {+ test('durable diagnostic writes, immediate versus bounded batches', () async {+ final root = Directory.systemTemp.createTempSync('harness-log-benchmark-');+ final results = <Map<String, Object>>[];+ try {+ for (final paced in [false, true]) {+ final trials = paced ? 3 : 5;+ final records = paced ? 64 : 2000;+ for (var trial = 0; trial < trials; trial++) {+ final outputs = <List<int>>[];+ for (final buffered in trial.isEven ? [false, true] : [true, false]) {+ final directory = Directory('${root.path}/$paced-$trial-$buffered');+ var now = DateTime(2026, 10, 1, 12);+ final writes = _Writes();+ final file = _TimedLogFile(directory, () => now, (file, contents) {+ if (buffered) {+ appendDurableLog(file, contents);+ } else {+ // The durable append used by the deployed, unbuffered logger.+ file.writeAsStringSync(+ contents,+ mode: FileMode.append,+ flush: true,+ );+ }+ writes.durable++;+ });+ final log = FileAppLog(+ file,+ bufferDebug: buffered,+ clock: () => now,+ );+ final elapsed = Stopwatch()..start();+ {+ for (var i = 0; i < records; i++) {+ now = DateTime(+ 2026,+ 10,+ 1,+ 12,+ ).add(Duration(milliseconds: i * 125));+ log.debug(+ 'ws',+ '↓ ${['agent_activity', 'turn_heartbeat', 'agent_recent'][i % 3]} '+ '{agentId: fixture-${i % 12}, status: working, requestId: fixture-$i}',+ );+ // Include durable operational records, not just a best-case+ // all-debug burst. They must still commit the preceding tail.+ if (i % 32 == 31) {+ log.warn('ws', 'fixture poll failed: timeout');+ }+ if (paced) {+ await Future<void>.delayed(const Duration(milliseconds: 125));+ }+ }+ log.flush();+ }+ elapsed.stop();+ final bytes = file.currentFile.readAsBytesSync();+ outputs.add(bytes);+ final result = <String, Object>{+ 'scenario': paced+ ? '8 debug records per second'+ : '2000-record burst',+ 'trial': trial,+ 'buffered': buffered,+ 'records': records,+ 'warnings': records ~/ 32,+ 'durableAppends': writes.durable,+ 'synchronousLogMs': file.work.elapsedMicroseconds / 1000,+ 'elapsedMs': elapsed.elapsedMicroseconds / 1000,+ 'fileBytes': bytes.length,+ };+ results.add(result);+ // ignore: avoid_print+ print('DIAGNOSTIC_LOG_BENCH ${jsonEncode(result)}');+ }+ expect(+ outputs.first,+ outputs.last,+ reason: 'buffering must retain every byte in order',+ );+ }+ }+ final output = Platform.environment['DIAGNOSTIC_LOG_BENCH_OUTPUT'];+ if (output != null) {+ File(output).writeAsStringSync(+ '${const JsonEncoder.withIndent(' ').convert({'scope': 'Real-file component benchmark. Work time includes synchronous append and timer/explicit flush execution; excludes intentional waits. No whole-app improvement claim.', 'at': DateTime.now().toUtc().toIso8601String(), 'allFinalBytesIdentical': true, 'results': results})}\n',+ );+ }+ } finally {+ root.deleteSync(recursive: true);+ }+ }, timeout: const Timeout(Duration(minutes: 3)));+}++class _TimedLogFile extends DailyLogFile {+ _TimedLogFile(+ Directory directory,+ DateTime Function() clock,+ void Function(File, String) appendFile,+ ) : super(directory, 'app', clock: clock, appendFile: appendFile);+ final work = Stopwatch();+ var depth = 0;++ void _measure(void Function() action) {+ final outer = depth++ == 0;+ if (outer) work.start();+ try {+ action();+ } finally {+ depth--;+ if (outer) work.stop();+ }+ }++ @override+ void append(String block, {bool buffered = false}) =>+ _measure(() => super.append(block, buffered: buffered));++ @override+ void flush() => _measure(super.flush);+}++class _Writes {+ var durable = 0;+}diff --git a/desktop/test/buffered_log_test.dart b/desktop/test/buffered_log_test.dartnew file mode 100644index 000000000..b2766b345--- /dev/null+++ b/desktop/test/buffered_log_test.dart@@ -0,0 +1,388 @@+import 'dart:io';+import 'dart:isolate';++import 'package:flutter_test/flutter_test.dart';+import 'package:harness/core/crash_log.dart';+import 'package:harness/core/harness_cli_runner.dart';+import 'package:harness/logging/app_log.dart';+import 'package:harness/logging/error_burst_filter.dart';+import 'package:harness/logging/log_export.dart';+import 'package:harness/logging/log_append.dart';+import 'package:harness/logging/log_file.dart';+import 'package:harness/logging/log_stream.dart';+import 'package:harness/logging/log_stream_sinks.dart';++void main() {+ late Directory dir;+ late AppLog previousLog;+ final files = <DailyLogFile>[];++ setUp(() {+ dir = Directory.systemTemp.createTempSync('harness-buffered-log-');+ previousLog = appLog;+ });+ tearDown(() {+ for (final file in files) {+ file.flush();+ }+ files.clear();+ appLog = previousLog;+ CrashLog.testFile = null;+ dir.deleteSync(recursive: true);+ });++ DailyLogFile file({+ DateTime Function()? clock,+ int maxCharacters = 64 * 1024,+ int maxEntries = 256,+ Directory? directory,+ }) {+ final result = DailyLogFile(+ directory ?? dir,+ 'app',+ clock: clock ?? () => DateTime(2026, 10, 1, 12),+ maxBufferedCharacters: maxCharacters,+ maxBufferedEntries: maxEntries,+ );+ files.add(result);+ return result;+ }++ testWidgets('one deadline batches entries without extending on each event', (+ tester,+ ) async {+ final sink = file();+ sink.append('first', buffered: true);+ await tester.pump(const Duration(milliseconds: 900));+ sink.append('second', buffered: true);+ expect(sink.currentFile.existsSync(), isFalse);+ await tester.pump(const Duration(milliseconds: 100));+ expect(sink.currentFile.readAsStringSync(), 'first\nsecond\n');+ final modified = sink.currentFile.lastModifiedSync();+ await tester.pump(const Duration(minutes: 1));+ expect(sink.currentFile.lastModifiedSync(), modified);+ });++ testWidgets('explicit flush cancels the deadline and permits a new batch', (+ tester,+ ) async {+ final sink = file();+ sink.flush();+ expect(sink.currentFile.existsSync(), isFalse);+ sink.append('one', buffered: true);+ await tester.pump(const Duration(milliseconds: 900));+ sink.flush();+ sink.flush();+ sink.append('two', buffered: true);+ await tester.pump(const Duration(milliseconds: 100));+ expect(sink.currentFile.readAsStringSync(), 'one\n');+ await tester.pump(const Duration(milliseconds: 900));+ expect(sink.currentFile.readAsStringSync(), 'one\ntwo\n');+ });++ test('immediate append commits pending context in order', () {+ final sink = file();+ sink.append('before', buffered: true);+ sink.append('warning');+ expect(sink.currentFile.readAsStringSync(), 'before\nwarning\n');+ sink.flush();+ expect(sink.currentFile.readAsStringSync(), 'before\nwarning\n');+ });++ test('entry limit bounds a burst and does not drop entries', () {+ final sink = file(maxEntries: 2);+ sink.append('one', buffered: true);+ expect(sink.currentFile.existsSync(), isFalse);+ sink.append('two', buffered: true);+ expect(sink.currentFile.readAsStringSync(), 'one\ntwo\n');+ sink.append('three', buffered: true);+ sink.flush();+ expect(sink.currentFile.readAsStringSync(), 'one\ntwo\nthree\n');+ });++ test('character limit flushes before overflow and on an exact fit', () {+ final sink = file(maxCharacters: 8);+ sink.append('abc', buffered: true);+ sink.append('def', buffered: true);+ expect(sink.currentFile.readAsStringSync(), 'abc\ndef\n');+ sink.append('12345', buffered: true);+ sink.append('678', buffered: true);+ expect(sink.currentFile.readAsStringSync(), 'abc\ndef\n12345\n');+ sink.flush();+ expect(sink.currentFile.readAsStringSync(), 'abc\ndef\n12345\n678\n');+ });++ test('oversized blocks are written directly, after any pending entries', () {+ final sink = file(maxCharacters: 8);+ sink.append('1234567', buffered: true);+ expect(sink.currentFile.readAsStringSync(), '1234567\n');+ sink.append('x', buffered: true);+ sink.append('a larger block', buffered: true);+ expect(sink.currentFile.readAsStringSync(), '1234567\nx\na larger block\n');+ });++ test('Unicode, multiline blocks and empty blocks preserve exact bytes', () {+ final immediate = DailyLogFile(Directory('${dir.path}/before'), 'app');+ final buffered = file(directory: Directory('${dir.path}/after'));+ final blocks = ['', 'hello 🦋', '日本語\nsecond line', '\n', 'a' * 90000];+ for (final block in blocks) {+ immediate.append(block);+ buffered.append(block, buffered: true);+ }+ buffered.flush();+ expect(+ buffered.currentFile.readAsBytesSync(),+ immediate.currentFile.readAsBytesSync(),+ );+ });++ test('a Unicode log path preserves both prior and appended bytes', () {+ final output = File('${dir.path}/log 日本語 🦋.txt');+ appendDurableLog(output, 'first\n');+ appendDurableLog(output, 'second\n');+ expect(output.readAsStringSync(), 'first\nsecond\n');+ });++ test('an invalid NUL path never appends to its valid prefix', () {+ final output = File('${dir.path}/existing');+ output.writeAsStringSync('preserved');+ expect(+ () => appendDurableLog(File('${output.path}\u0000suffix'), 'bad'),+ throwsArgumentError,+ );+ expect(output.readAsStringSync(), 'preserved');+ });++ test('opening a directory as a log fails without altering it', () {+ expect(+ () => appendDurableLog(File(dir.path), 'bad'),+ throwsA(isA<FileSystemException>()),+ );+ expect(dir.listSync(), isEmpty);+ });++ test('a full device reports failure and releases the handle', () {+ final descriptors = Directory('/proc/self/fd');+ final before = descriptors.listSync().length;+ for (var i = 0; i < 32; i++) {+ expect(+ () => appendDurableLog(File('/dev/full'), 'cannot fit'),+ throwsA(isA<FileSystemException>()),+ );+ }+ expect(descriptors.listSync().length, lessThanOrEqualTo(before + 1));+ }, skip: !Platform.isLinux);++ test(+ 'independent writers retain complete records in a shared daily file',+ () async {+ final directory = dir.path;+ await Future.wait([+ for (var writer = 0; writer < 2; writer++)+ Isolate.run(() => _writeConcurrentBatch(directory, writer)),+ ]);+ final lines = File('$directory/app-20261001.log').readAsLinesSync();+ expect(lines, hasLength(2000));+ for (var writer = 0; writer < 2; writer++) {+ expect(+ lines.where((line) => line.startsWith('writer $writer ')),+ List.generate(1000, (i) => 'writer $writer record $i 🦋'),+ );+ }+ },+ skip: !Platform.isMacOS && !Platform.isLinux,+ );++ for (final backwards in [false, true]) {+ test(+ 'a ${backwards ? 'backwards clock jump' : 'new day'} preserves dates',+ () {+ var now = DateTime(2026, 10, 1, 23, 59, 59);+ final sink = file(clock: () => now);+ sink.append('original day', buffered: true);+ now = backwards+ ? now.subtract(const Duration(days: 1))+ : now.add(const Duration(seconds: 2));+ sink.append('changed day', buffered: true);+ expect(+ File('${dir.path}/app-20261001.log').readAsStringSync(),+ 'original day\n',+ );+ sink.flush();+ expect(sink.currentFile.readAsStringSync(), 'changed day\n');+ },+ );+ }++ testWidgets('a timer crossing midnight still writes to the original day', (+ tester,+ ) async {+ var now = DateTime(2026, 10, 1, 23, 59, 59);+ final sink = file(clock: () => now);+ sink.append('late record', buffered: true);+ now = now.add(const Duration(seconds: 2));+ await tester.pump(const Duration(seconds: 1));+ expect(+ File('${dir.path}/app-20261001.log').readAsStringSync(),+ 'late record\n',+ );+ expect(sink.currentFile.existsSync(), isFalse);+ });++ testWidgets('a failed timed write drops its batch and permits recovery', (+ tester,+ ) async {+ final blocker = File('${dir.path}/blocker')..writeAsStringSync('x');+ final sink = file(directory: Directory('${blocker.path}/logs'));+ sink.append('failed batch', buffered: true);+ await tester.pump(const Duration(seconds: 1));+ blocker.deleteSync();+ sink.append('recovered', buffered: true);+ await tester.pump(const Duration(seconds: 1));+ expect(sink.currentFile.readAsStringSync(), 'recovered\n');+ });++ for (final level in [AppLogLevel.info, AppLogLevel.warn, AppLogLevel.error]) {+ test('$level makes its preceding debug context durable immediately', () {+ final sink = file();+ final log = FileAppLog(sink, bufferDebug: true);+ log.debug('ws', 'preceding context');+ expect(sink.currentFile.existsSync(), isFalse);+ log.record(+ level,+ 'app',+ 'important event',+ stackTrace: StackTrace.fromString('frame one'),+ );+ final text = sink.currentFile.readAsStringSync();+ expect(+ text.indexOf('preceding context'),+ lessThan(text.indexOf('important event')),+ );+ expect(text, contains(' frame one'));+ });+ }++ test(+ 'duplicate errors preserve burst protection with interleaved debug context',+ () {+ final at = DateTime(2026, 10, 1);+ final sink = file(clock: () => at);+ final log = FileAppLog(+ sink,+ bufferDebug: true,+ burst: ErrorBurstFilter(clock: () => at),+ );+ log.failure('flutter', 'same error');+ log.debug('ws', 'new context');+ log.failure('flutter', 'same error');+ expect(+ sink.currentFile.readAsStringSync(),+ isNot(contains('new context')),+ );+ log.flush();+ final text = sink.currentFile.readAsStringSync();+ expect('same error'.allMatches(text), hasLength(1));+ expect(text, contains('new context'));+ },+ );++ test('buffered debug stacks retain their order', () {+ final sink = file();+ final log = FileAppLog(sink, bufferDebug: true);+ log.record(+ AppLogLevel.debug,+ 'ws',+ 'with stack',+ stackTrace: StackTrace.fromString('one\ntwo'),+ );+ expect(sink.currentFile.existsSync(), isFalse);+ log.flush();+ expect(+ sink.currentFile.readAsStringSync(),+ contains('with stack\n one\n two\n'),+ );+ });++ test('a crash commits its preceding context and stack to both logs', () {+ final sink = file();+ appLog = FileAppLog(sink, bufferDebug: true);+ CrashLog.testFile = File('${dir.path}/errors.log');+ appLog.debug('ws', 'before crash');+ CrashLog.record(+ StateError('test crash'),+ StackTrace.fromString('crash frame'),+ );+ final text = sink.currentFile.readAsStringSync();+ expect(text, contains('before crash'));+ expect(text, contains('test crash'));+ expect(text, contains('crash frame'));+ expect(CrashLog.testFile!.readAsStringSync(), contains('crash frame'));+ });++ test('the Debug mirror is immediate and a fanout flush commits the file', () {+ final sink = file();+ final stream = LogStream();+ appLog = FanoutAppLog([+ FileAppLog(sink, bufferDebug: true),+ StreamAppLog(stream),+ ]);+ appLog.debug('ws', 'visible immediately');+ expect(stream.entries.single.message, 'visible immediately');+ expect(sink.currentFile.existsSync(), isFalse);+ flushAppLog();+ expect(+ sink.currentFile.readAsStringSync(),+ contains('visible immediately'),+ );+ appLog = const NoopAppLog();+ expect(flushAppLog, returnsNormally);+ });++ test(+ 'export flushes the pending tail before the CLI collects files',+ () async {+ final sink = file();+ appLog = FileAppLog(sink, bufferDebug: true);+ appLog.debug('ws', 'newest exported entry');+ final result = await exportLogs(+ _ExportRunner(() {+ expect(+ sink.currentFile.readAsStringSync(),+ contains('newest exported entry'),+ );+ }),+ );+ expect(result.path, '/fixture/logs.zip');+ },+ );+}++void _writeConcurrentBatch(String directory, int writer) {+ final file = DailyLogFile(+ Directory(directory),+ 'app',+ clock: () => DateTime(2026, 10, 1),+ );+ for (var i = 0; i < 1000; i++) {+ file.append('writer $writer record $i 🦋', buffered: true);+ }+ file.flush();+}++class _ExportRunner extends HarnessCliRunner {+ _ExportRunner(this.beforeExport);+ final void Function() beforeExport;++ @override+ Future<ProcessResult> run(List<String> arguments) async {+ expect(arguments, ['logs', 'export', '--json']);+ beforeExport();+ return ProcessResult(+ 0,+ 0,+ '{"path":"/fixture/logs.zip","included":[]}',+ '',+ );+ }+}diff --git a/desktop/test/swarm_async_test.dart b/desktop/test/swarm_async_test.dartindex e8f26fa4b..d9e0a2f1f 100644--- a/desktop/test/swarm_async_test.dart+++ b/desktop/test/swarm_async_test.dart@@ -7,6 +7,7 @@ import 'package:flutter/material.dart';import 'package:flutter_riverpod/flutter_riverpod.dart';import 'package:flutter_test/flutter_test.dart';import 'package:harness/app_shell.dart';+import 'package:harness/logging/app_log.dart';import 'package:harness/screens/swarm_screen.dart';import 'package:harness/state/app_state.dart';import 'package:harness/state/swarm_catalog.dart';@@ -243,6 +244,10 @@ void main() {'quit ${timedOut ? 'stays available with a stalled disk' : 'waits for the latest saved arrangement'}',(tester) async {final storage = _PendingWriteStore();+ final previousLog = appLog;+ final log = _FlushLog();+ appLog = log;+ addTearDown(() => appLog = previousLog);final app = createApp(store: storage)..status = AppStatus.authenticated;app.newSwarm();app.renameSwarm(app.activeSwarmId, 'Before quit');@@ -269,6 +274,11 @@ void main() {storage.release.complete();await tester.pump();expect(await quitting, AppExitResponse.exit);+ expect(+ log.flushes,+ 1,+ reason: 'quit must commit the pending debug tail',+ );await app.flushPaneLayout();expect(storage.values['swarm_layout_v1'], contains('Before quit'));await tester.pumpWidget(const SizedBox());@@ -277,6 +287,33 @@ void main() {);}+ testWidgets(+ 'backgrounding and disposing the shell flush pending diagnostics',+ (tester) async {+ final app = createApp()..status = AppStatus.authenticated;+ final previousLog = appLog;+ final log = _FlushLog();+ appLog = log;+ addTearDown(() => appLog = previousLog);+ await tester.pumpWidget(+ ProviderScope(+ overrides: [appStateProvider.overrideWithValue(app)],+ child: HarnessApp(authenticatedScreen: _swarm),+ ),+ );+ await tester.pump();+ final observer =+ tester.state(find.byType(RootShell)) as WidgetsBindingObserver;+ observer.didChangeAppLifecycleState(AppLifecycleState.inactive);+ expect(log.flushes, 1);+ observer.didChangeAppLifecycleState(AppLifecycleState.resumed);+ expect(log.flushes, 1);+ await tester.pumpWidget(const SizedBox());+ expect(log.flushes, 2);+ app.dispose();+ },+ );+for (final change in ['switch', 'close', 'dispose']) {test('an agent launch stays with its destination after $change during the RPC',@@ -375,6 +412,20 @@ void main() {);}+class _FlushLog implements FlushableAppLog {+ var flushes = 0;+ @override+ void flush() => flushes++;+ @override+ void record(+ AppLogLevel level,+ String category,+ String message, {+ Object? error,+ StackTrace? stackTrace,+ }) {}+}+/// The screen the desktop app mounts once signed in — the argument `HarnessApp`/// now takes, so the shell itself does not have to know about either app.Widget _swarm(AppNotifier app) => SwarmScreen(notifier: app);diff --git a/desktop/test/ws_conn_test.dart b/desktop/test/ws_conn_test.dartindex fa541a27a..bca4179bd 100644--- a/desktop/test/ws_conn_test.dart+++ b/desktop/test/ws_conn_test.dart@@ -1,9 +1,14 @@+import 'dart:async';import 'dart:convert';import 'dart:io';import 'package:harness/core/models.dart' show ConnectionStatus;import 'package:harness/ws/ws_conn.dart';import 'package:harness/ws/ws_pool.dart';+import 'package:harness/logging/app_log.dart';+import 'package:harness/logging/log_file.dart';+import 'package:harness/logging/log_stream.dart';+import 'package:harness/logging/log_stream_sinks.dart';import 'package:flutter_test/flutter_test.dart';class FakeHub {@@ -14,6 +19,7 @@ class FakeHub {final List<String> protocols = [];final List<String?> environments = [];final Map<String, int> machineSelected = {};+ final List<WebSocket> clients = [];FakeHub._(this.server, this.rejectOldToken, this.closeCodeOnSelect);int get port => server.port;@@ -38,6 +44,7 @@ class FakeHub {protocolSelector: (protocols) =>protocols.isNotEmpty ? protocols.first : null,);+ hub.clients.add(ws);ws.listen((data) {final frame = jsonDecode(data as String) as Map<String, dynamic>;hub.frames.add(frame);@@ -102,6 +109,80 @@ void main() {await hub.close();});+ test(+ 'buffered diagnostics preserve live delivery, RPC completion and errors',+ () async {+ final dir = Directory.systemTemp.createTempSync('harness-ws-log-e2e-');+ final file = DailyLogFile(+ dir,+ 'app',+ bufferInterval: const Duration(minutes: 1),+ );+ final previousLog = appLog;+ final stream = LogStream();+ appLog = FanoutAppLog([+ FileAppLog(file, bufferDebug: true),+ StreamAppLog(stream),+ ]);+ addTearDown(() {+ file.flush();+ appLog = previousLog;+ dir.deleteSync(recursive: true);+ });+ hub = await FakeHub.start();+ final received = <int>[];+ final delivered = Completer<void>();+ final ready = Completer<void>();+ conn = WsConn(+ wsBaseUrl: 'ws://127.0.0.1:${hub.port}',+ autonomousEnv: 'test',+ machineId: 'fixture',+ accessTokenProvider: (_, _) async => 'fixture-token',+ onAuthFailure: (_) {},+ onStatus: (status) {+ if (status == ConnectionStatus.connected && !ready.isCompleted) {+ ready.complete();+ }+ },+ onEvent: (frame) {+ if (frame['type'] == 'agent_activity') {+ received.add((frame['payload'] as Map)['index'] as int);+ if (received.length == 40) delivered.complete();+ }+ },+ );+ await conn!.connect();+ await ready.future.timeout(const Duration(seconds: 5));+ for (var i = 0; i < 40; i++) {+ hub.clients.single.add(+ jsonEncode({+ 'type': 'agent_activity',+ 'payload': {'index': i},+ }),+ );+ }+ await delivered.future.timeout(const Duration(seconds: 5));+ expect(received, List.generate(40, (i) => i));+ expect(+ stream.entries.where((e) => e.message.startsWith('↓ agent_activity')),+ hasLength(40),+ );+ expect(file.currentFile.existsSync(), isFalse);+ final inventory = await conn!.request('agents_list');+ expect((inventory['agents'] as List).single['id'], 'a1');+ expect(file.currentFile.existsSync(), isFalse);+ await expectLater(+ conn!.request('agent_create'),+ throwsA(isA<WsRequestFailure>()),+ );+ final text = file.currentFile.readAsStringSync();+ expect('↓ agent_activity'.allMatches(text), hasLength(40));+ expect(text, contains('← agents_list'));+ expect(text, contains('← agent_create failed'));+ expect(text, isNot(contains('fixture-token')));+ },+ );+test('uses SSO subprotocol, environment, readiness, and machine_select',() async {diff --git a/desktop/tool/log_append_probe.dart b/desktop/tool/log_append_probe.dartnew file mode 100644index 000000000..e7d739ade--- /dev/null+++ b/desktop/tool/log_append_probe.dart@@ -0,0 +1,70 @@+// Run with `dart run tool/log_append_probe.dart`. Only private temporary files+// and owned child processes are used; no app, daemon or user session is started.+import 'dart:convert';+import 'dart:io';++import 'package:harness/logging/log_append.dart';++Future<void> main(List<String> args) async {+ const records = 500;+ const writers = 4;+ if (args.length == 3 && args.first == '--worker') {+ final file = File(args[1]);+ final writer = int.parse(args[2]);+ for (var i = 0; i < records; i++) {+ appendDurableLog(file, 'writer $writer record $i 🦋\n');+ }+ return;+ }+ if (args.isNotEmpty) throw ArgumentError('Unexpected arguments');+ if (!Platform.isMacOS && !Platform.isLinux) {+ throw UnsupportedError('Atomic append probe requires macOS or Linux');+ }+ final directory = Directory.systemTemp.createTempSync('harness-log-process-');+ try {+ final file = File('${directory.path}/shared 日本語.log');+ final results = await Future.wait([+ for (var writer = 0; writer < writers; writer++)+ Process.run(Platform.resolvedExecutable, [+ if (Platform.packageConfig case final packages?)+ '--packages=$packages',+ Platform.script.toFilePath(),+ '--worker',+ file.path,+ '$writer',+ ]),+ ]);+ for (final result in results) {+ if (result.exitCode != 0) {+ throw StateError('Writer failed: ${result.stderr}');+ }+ }+ final lines = file.readAsLinesSync();+ if (lines.length != writers * records) {+ throw StateError(+ 'Expected ${writers * records} records, got ${lines.length}',+ );+ }+ for (var writer = 0; writer < writers; writer++) {+ final found = lines.where((line) => line.startsWith('writer $writer '));+ final expected = List.generate(+ records,+ (i) => 'writer $writer record $i 🦋',+ );+ if (found.join('\n') != expected.join('\n')) {+ throw StateError('Writer $writer records were altered or reordered');+ }+ }+ stdout.writeln(+ jsonEncode({+ 'platform': Platform.operatingSystem,+ 'dart': Platform.version,+ 'writers': writers,+ 'records': lines.length,+ 'allRecordsIntact': true,+ }),+ );+ } finally {+ directory.deleteSync(recursive: true);+ }+}diff --git a/desktop/tool/machines_preview.dart b/desktop/tool/machines_preview.dartindex 89f56f173..f654ccf3e 100644--- a/desktop/tool/machines_preview.dart+++ b/desktop/tool/machines_preview.dart@@ -11,6 +11,7 @@ import 'package:flutter/material.dart';import 'package:flutter/services.dart';import 'package:harness/auth/auth_session.dart';import 'package:harness/auth/cli_link.dart';+import 'package:harness/auth/sign_in_provider.dart';import 'package:harness/core/config.dart';import 'package:harness/core/desktop_window.dart';import 'package:harness/core/machine_resources.dart';@@ -176,7 +177,7 @@ class _App extends AppNotifier {Future<void> retryMachines() async => notifyListeners();@override- Future<void> login({bool? qr}) async {+ Future<void> login([SignInProvider? provider]) async {await Future<void>.delayed(const Duration(seconds: 1));signedIn = true;notifyListeners();diff --git a/docs/performance/2026-10-02-buffered-diagnostic-logs.json b/docs/performance/2026-10-02-buffered-diagnostic-logs.jsonnew file mode 100644index 000000000..677b43a1e--- /dev/null+++ b/docs/performance/2026-10-02-buffered-diagnostic-logs.json@@ -0,0 +1,214 @@+{+ "scope": "Real-file component benchmark. Work time includes synchronous append and timer/explicit flush execution; excludes intentional waits. No whole-app improvement claim.",+ "at": "2026-10-02T04:11:53.275377Z",+ "allFinalBytesIdentical": true,+ "results": [+ {+ "scenario": "2000-record burst",+ "trial": 0,+ "buffered": false,+ "records": 2000,+ "warnings": 62,+ "durableAppends": 2062,+ "synchronousLogMs": 133.402,+ "elapsedMs": 146.032,+ "fileBytes": 237920+ },+ {+ "scenario": "2000-record burst",+ "trial": 0,+ "buffered": true,+ "records": 2000,+ "warnings": 62,+ "durableAppends": 63,+ "synchronousLogMs": 11.496,+ "elapsedMs": 16.55,+ "fileBytes": 237920+ },+ {+ "scenario": "2000-record burst",+ "trial": 1,+ "buffered": true,+ "records": 2000,+ "warnings": 62,+ "durableAppends": 63,+ "synchronousLogMs": 6.987,+ "elapsedMs": 10.396,+ "fileBytes": 237920+ },+ {+ "scenario": "2000-record burst",+ "trial": 1,+ "buffered": false,+ "records": 2000,+ "warnings": 62,+ "durableAppends": 2062,+ "synchronousLogMs": 114.625,+ "elapsedMs": 118.735,+ "fileBytes": 237920+ },+ {+ "scenario": "2000-record burst",+ "trial": 2,+ "buffered": false,+ "records": 2000,+ "warnings": 62,+ "durableAppends": 2062,+ "synchronousLogMs": 112.062,+ "elapsedMs": 115.558,+ "fileBytes": 237920+ },+ {+ "scenario": "2000-record burst",+ "trial": 2,+ "buffered": true,+ "records": 2000,+ "warnings": 62,+ "durableAppends": 63,+ "synchronousLogMs": 5.724,+ "elapsedMs": 8.45,+ "fileBytes": 237920+ },+ {+ "scenario": "2000-record burst",+ "trial": 3,+ "buffered": true,+ "records": 2000,+ "warnings": 62,+ "durableAppends": 63,+ "synchronousLogMs": 5.86,+ "elapsedMs": 8.533,+ "fileBytes": 237920+ },+ {+ "scenario": "2000-record burst",+ "trial": 3,+ "buffered": false,+ "records": 2000,+ "warnings": 62,+ "durableAppends": 2062,+ "synchronousLogMs": 109.731,+ "elapsedMs": 113.268,+ "fileBytes": 237920+ },+ {+ "scenario": "2000-record burst",+ "trial": 4,+ "buffered": false,+ "records": 2000,+ "warnings": 62,+ "durableAppends": 2062,+ "synchronousLogMs": 109.459,+ "elapsedMs": 113.101,+ "fileBytes": 237920+ },+ {+ "scenario": "2000-record burst",+ "trial": 4,+ "buffered": true,+ "records": 2000,+ "warnings": 62,+ "durableAppends": 63,+ "synchronousLogMs": 5.382,+ "elapsedMs": 8.079,+ "fileBytes": 237920+ },+ {+ "scenario": "8 debug records per second",+ "trial": 0,+ "buffered": false,+ "records": 64,+ "warnings": 2,+ "durableAppends": 66,+ "synchronousLogMs": 36.555,+ "elapsedMs": 8221.973,+ "fileBytes": 7512+ },+ {+ "scenario": "8 debug records per second",+ "trial": 0,+ "buffered": true,+ "records": 64,+ "warnings": 2,+ "durableAppends": 8,+ "synchronousLogMs": 10.528,+ "elapsedMs": 8213.482,+ "fileBytes": 7512+ },+ {+ "scenario": "8 debug records per second",+ "trial": 1,+ "buffered": true,+ "records": 64,+ "warnings": 2,+ "durableAppends": 8,+ "synchronousLogMs": 6.213,+ "elapsedMs": 8202.014,+ "fileBytes": 7512+ },+ {+ "scenario": "8 debug records per second",+ "trial": 1,+ "buffered": false,+ "records": 64,+ "warnings": 2,+ "durableAppends": 66,+ "synchronousLogMs": 67.139,+ "elapsedMs": 8278.376,+ "fileBytes": 7512+ },+ {+ "scenario": "8 debug records per second",+ "trial": 2,+ "buffered": false,+ "records": 64,+ "warnings": 2,+ "durableAppends": 66,+ "synchronousLogMs": 43.444,+ "elapsedMs": 8238.22,+ "fileBytes": 7512+ },+ {+ "scenario": "8 debug records per second",+ "trial": 2,+ "buffered": true,+ "records": 64,+ "warnings": 2,+ "durableAppends": 8,+ "synchronousLogMs": 15.669,+ "elapsedMs": 8217.25,+ "fileBytes": 7512+ }+ ],+ "baseCommit": "922c9dc9c63a5825e8f71b68b043f89578b6cf23",+ "runtime": "Flutter 3.47.2 / Dart 3.13.2; macOS 26.6.2 arm64; headless Flutter test runner",+ "comparison": "Legacy immediate File.writeAsStringSync(flush:true) versus bounded batches using native O_APPEND and fsync. Successful durable append operations counted; actual filesystem IO in both modes.",+ "sourceSha256": {+ "desktop/lib/logging/app_log.dart": "00b91e3b4e8b429453773b4e558020b40ce78960999d391015900fb4ece9957e",+ "desktop/lib/logging/log_file.dart": "f962f08e6ad3373109924fc87c861b23d62be0d3833e0f6e5d7ae2703b95f438",+ "desktop/lib/logging/log_append_native.dart": "cd205c906bca1ef59d3596a04e2fce0f51cbf83e6d3514658f3dcec73ce0e252",+ "desktop/test/benchmarks/diagnostic_log_benchmark.dart": "c7de9d9d378748c2197f85b6addbcce1aaee71a7518d9b67256ecf9080fa432f"+ },+ "summary": [+ {+ "scenario": "2000-record burst",+ "pairs": 5,+ "durableAppendsBefore": 2062,+ "durableAppendsAfter": 63,+ "appendReductionPercent": 96.94471387002909,+ "medianSyncMsBefore": 112.062,+ "medianSyncMsAfter": 5.86,+ "timeReductionPercent": 94.77075190519534+ },+ {+ "scenario": "8 debug records per second",+ "pairs": 3,+ "durableAppendsBefore": 66,+ "durableAppendsAfter": 8,+ "appendReductionPercent": 87.87878787878788,+ "medianSyncMsBefore": 43.444,+ "medianSyncMsAfter": 10.528,+ "timeReductionPercent": 75.76650400515607+ }+ ]+}diff --git a/docs/performance/2026-10-02-buffered-diagnostic-logs.md b/docs/performance/2026-10-02-buffered-diagnostic-logs.mdnew file mode 100644index 000000000..4ed18a9b3--- /dev/null+++ b/docs/performance/2026-10-02-buffered-diagnostic-logs.md@@ -0,0 +1,83 @@+# Buffered desktop diagnostic logs++Routine desktop DEBUG logging now batches durable file appends instead of+synchronously opening, writing and flushing the file for every record. The+batch has a one-second deadline from its first record and limits of 256 entries+or 64 Ki UTF-16 characters. It does not keep an idle timer running.++## Measurement++On macOS 26.6.2 arm64 with Flutter 3.47.2 / Dart 3.13.2, the real-file component+benchmark alternated the order of immediate and buffered runs. It compared+legacy immediate `File.writeAsStringSync(..., flush: true)` appends with buffered+native `O_APPEND` writes followed by `fsync`; both used the candidate logger's+formatting. This was not a comparison of two application binaries. No other test suite or+analyzer ran alongside this measurement. The source base was `922c9dc9c`.++| Workload | Paired trials | Durable appends, before → after | Reduction | Median synchronous logger time, before → after |+|---|---:|---:|---:|---:|+| 64 DEBUG records at 8/sec, plus 2 warnings | 3 | 66 → 8 | 87.9% | 43.444 → 10.528 ms (75.8% less) |+| 2,000 DEBUG records in a burst, plus 62 warnings | 5 | 2,062 → 63 | 96.9% | 112.062 → 5.860 ms (94.8% less) |++Every paired run produced byte-identical final log files. The counters record+successful durable append operations; real filesystem writes and flushes run+in both modes.+Timing includes synchronous append and timer/explicit flush execution and+excludes the intentional waits in the paced workload. It does not include all+upstream formatting or protocol handling.++These are component measurements, not whole-app CPU, frame latency, energy-impact+or battery-life improvements. Retained log bytes are unchanged. A five-second+sample of the deployed app showed synchronous Dart file writes on its main+thread, but did not identify the exact Dart caller; that sample alone cannot+attribute all those writes to this logger.++Raw measurements and source hashes are in+[`2026-10-02-buffered-diagnostic-logs.json`](2026-10-02-buffered-diagnostic-logs.json).+Reproduce from `desktop/`:++```sh+DIAGNOSTIC_LOG_BENCH_OUTPUT=/tmp/harness-diagnostic-logs.json \+ flutter test --no-pub test/benchmarks/diagnostic_log_benchmark.dart+```++## Behavior and durability++- INFO, WARN and admitted ERROR records immediately commit their preceding+ buffered context. Repeated errors suppressed by the existing burst filter+ retain that protection.+- The Debug mirror receives entries immediately. Log export, app backgrounding,+ normal quit, disposal and updater handoff flush pending diagnostics.+- An abrupt process kill can lose the pending DEBUG batch. The one-second timer+ can run late if the app's event loop is blocked or the process is suspended.+ Conversation history and CLI transcript flushing are unchanged.+- Oversized entries write directly. Day changes preserve the original record's+ file, including a timer firing after midnight or a backwards wall-clock jump.+- Disk failures remain best effort: the failed batch is dropped instead of+ accumulating an unbounded retry queue.++Concurrent writers exposed an existing append race: the+[Dart macOS file implementation](https://github.com/dart-lang/sdk/blob/main/runtime/bin/file_macos.cc)+seeks to EOF when opening an append handle. Two handles can then write at the+same position. macOS and Linux now use `O_APPEND` with close-on-exec, handle+partial writes and interrupted syscalls, and close their descriptor on failures.+Other platforms retain their existing Dart IO implementation. Mixed-version+writers still include the older writer's behavior.++## Validation++On macOS arm64, 118 focused tests passed; one Linux-only `/dev/full` error-path+test was skipped. Four concurrent real Dart processes retained all 2,000 records+and per-writer ordering. These checks cover real files, deadline/size limits,+shared writers, errors and stacks, Debug mirroring, log export, lifecycle+flushing and real loopback WebSocket event/RPC delivery. Dedicated macOS/Linux+CI runs the append probe and logging regressions.++The full desktop attempt reached 5,282 passes and 15 skips, but did not pass:+23 assertion failures reproduced on an unchanged `922c9dc9c` checkout. Two+settings tests reached their ten-minute timeout; the same files stalled on the+baseline. Both runs were interrupted after preserving their evidence. One+additional file failed to load its Flutter tester and passed in the focused+rerun. Full-suite coverage was not produced; focused coverage does not establish+100% end-to-end coverage. Exact failures are recorded in+[`2026-10-02-buffered-diagnostic-validation.json`](2026-10-02-buffered-diagnostic-validation.json).diff --git a/docs/performance/2026-10-02-buffered-diagnostic-validation.json b/docs/performance/2026-10-02-buffered-diagnostic-validation.jsonnew file mode 100644index 000000000..ff93c577b--- /dev/null+++ b/docs/performance/2026-10-02-buffered-diagnostic-validation.json@@ -0,0 +1,51 @@+{+ "baseCommit": "922c9dc9c",+ "focusedMacosArm64": {+ "passed": 118,+ "skipped": 1,+ "skipReason": "Linux /dev/full failure-path check; scheduled in Linux CI"+ },+ "processAppendProbe": {+ "writers": 4,+ "records": 2000,+ "allRecordsIntact": true+ },+ "fullDesktopAttempt": {+ "passedBeforeInterruption": 5282,+ "skipped": 15,+ "reproducedAssertionFailures": [+ "test/agent_pause_state_test.dart: a confirmed pause remains in inventory when its refresh fails",+ "test/daemon_workspace_test.dart: the pair brain an unavailable companion engine explains setup and retries in the same DSH",+ "test/desktop_search_polish_test.dart: native scopes put machines first and keep typed words and focus",+ "test/machines_manager_test.dart: Search unifies categories and preserves management commands (native=false)",+ "test/machines_manager_test.dart: Search unifies categories and preserves management commands (native=true)",+ "test/new_harness_install_e2e_test.dart: a dropped socket says the install may still be finishing",+ "test/new_harness_install_e2e_test.dart: a failed install explains itself; New Harness retries and creates",+ "test/new_harness_install_e2e_test.dart: pick with keys, install with narration, then create",+ "test/new_harness_install_e2e_test.dart: the pane fits a 520px window at 1.0x text",+ "test/new_harness_install_e2e_test.dart: the pane fits a 520px window at 2.0x text",+ "test/new_harness_install_e2e_test.dart: the pane fits a 960px window at 2.0x text",+ "test/new_harness_install_pane_test.dart: installing on the way to start a failed install stays on screen, with how to retry",+ "test/new_harness_install_pane_test.dart: installing on the way to start outside dismissal cannot abandon a running installation",+ "test/new_harness_install_pane_test.dart: installing on the way to start the right pane narrates the machine, step by step",+ "test/new_harness_install_pane_test.dart: the harness list with no history, Claude Code leads and every harness is listed",+ "test/new_harness_install_pane_test.dart: what the form opens on Code and Claude Code when nothing was used before",+ "test/pane_model_status_test.dart: an agent whose frame says neither keeps the header it had",+ "test/share_toolbar_test.dart: Share defaults hidden and its saved Settings toggle updates the toolbar (native=false)",+ "test/share_toolbar_test.dart: Share defaults hidden and its saved Settings toggle updates the toolbar (native=true)",+ "test/terminal_panel_presentation_test.dart: narrow headers preserve identity and close control at large text",+ "test/terminal_panel_presentation_test.dart: retained header uses current callbacks, names, projects and status",+ "test/terminal_tail_lifecycle_test.dart: all delayed local panes start at bottom",+ "test/terminal_tail_lifecycle_test.dart: all delayed remote panes start at bottom"+ ],+ "loaderFailure": "agent_alert_banner_widget_test.dart failed to load once, then passed in the focused rerun",+ "stalledTests": [+ "daemon_off_test.dart: Settings switches the creature on and off without leaving Settings",+ "share_toolbar_test.dart: button and shortcut share only the focused agent and return terminal focus"+ ],+ "candidateStall": "Both reached the default ten-minute test timeout; following tests in those files then stalled.",+ "baselineStall": "The same two files stopped making progress on unchanged source; this baseline attempt was stopped after 4m11s.",+ "completion": "Both runs were interrupted. Neither is a passing full suite, and no full-suite coverage result was produced."+ },+ "coverageScope": "Focused suite only; not 100% end-to-end coverage."+}