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.

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.yml
new file mode 100644
index 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.dart
diff --git a/desktop/CLAUDE.md b/desktop/CLAUDE.md
index 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`) before
anything 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 developer
furniture — `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 log
diff --git a/desktop/lib/app_shell.dart b/desktop/lib/app_shell.dart
index 48ce8a8c3..7d9365afa 100644
--- a/desktop/lib/app_shell.dart
+++ b/desktop/lib/app_shell.dart
@@ -204,11 +204,17 @@ class _RootShellState extends ConsumerState<RootShell>
@override
void dispose() {
+ flushAppLog();
WidgetsBinding.instance.removeObserver(this);
_appMenuChannel.setMethodCallHandler(null);
super.dispose();
}
+ @override
+ void didChangeAppLifecycleState(AppLifecycleState state) {
+ if (state != AppLifecycleState.resumed) flushAppLog();
+ }
+
@override
Future<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.dart
index 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.dart
index 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. Tailed
diff --git a/desktop/lib/logging/log_append.dart b/desktop/lib/logging/log_append.dart
new file mode 100644
index 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.dart
new file mode 100644
index 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.dart
new file mode 100644
index 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.dart
index 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.dart
index 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.dart
index 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();
+ }
+ }
+
@override
void record(
AppLogLevel level,
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index 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.dart
new file mode 100644
index 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.dart
new file mode 100644
index 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.dart
index 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.dart
index 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.dart
new file mode 100644
index 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.dart
index 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.json
new file mode 100644
index 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.md
new file mode 100644
index 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.json
new file mode 100644
index 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."
+}