From 806d16d0dfd01973e0fb1fbdfb8a9491675ae295 Mon Sep 17 00:00:00 2001
From: aliou <aliou@users.noreply.github.com>
Date: Sat, 27 Jun 2026 22:30:52 +0200
Subject: [PATCH] docs: add keyboard-latency-tracer and document the modtap
 latency fix

---
 AGENTS.md                                     |  23 ++
 README.md                                     |   7 +-
 .../README.md                                 |  95 ++++++
 docs/README.md                                |   1 +
 tools/keyboard-latency-tracer/.gitignore      |   1 +
 tools/keyboard-latency-tracer/Makefile        |  10 +
 tools/keyboard-latency-tracer/README.md       |  74 +++++
 tools/keyboard-latency-tracer/tracer.c        | 295 ++++++++++++++++++
 8 files changed, 505 insertions(+), 1 deletion(-)
 create mode 100644 docs/2026-06-19-keyboard-latency-investigation/README.md
 create mode 100644 tools/keyboard-latency-tracer/.gitignore
 create mode 100644 tools/keyboard-latency-tracer/Makefile
 create mode 100644 tools/keyboard-latency-tracer/README.md
 create mode 100644 tools/keyboard-latency-tracer/tracer.c

diff --git a/AGENTS.md b/AGENTS.md
index 59e7dee..390e117 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -148,6 +148,29 @@ The geometry and labels are hand-maintained in `src/keyboards.ts`; update
 that file whenever a keymap changes. See `tools/keyboard-tester/AGENTS.md`
 for the sub-project conventions.
 
+### Latency tracer (`tools/keyboard-latency-tracer/`)
+
+Tiny macOS CGEventTap used to measure the gap between a mod-tap Control
+modifier going down and the next key going down. It was built to confirm the
+Mirage's `LCTL_T(KC_ESC)` felt sluggish on `Ctrl + anything` and to verify
+that switching to eager per-row debounce fixed it. It only observes events;
+it does not inject or swallow them.
+
+Build requires Xcode command line tools:
+
+```
+cd tools/keyboard-latency-tracer
+make
+./tracer
+```
+
+The first run will request **Input Monitoring** permission for the terminal
+app in System Settings. Stop the tracer with a bare `q`, 10 seconds of idle,
+or `pkill tracer`.
+
+See `docs/2026-06-19-keyboard-latency-investigation/README.md` for the
+measurement findings and the debounce fix.
+
 ## Committing code
 
 - `git status` first; stage only files relevant to the change. Avoid
diff --git a/README.md b/README.md
index f9305cb..ff5d54e 100644
--- a/README.md
+++ b/README.md
@@ -37,7 +37,8 @@ patches/         -- 0001: read-only tolerance. 0002: edthu wireless (NEO65).
 vendor/          -- edthu-wireless source (regen base) + stock qwertykeys binaries.
 scripts/         -- regen-wireless-patch.sh, ble-scan.swift/.py.
 justfile         -- `just mirage`, `just neo`, `just bakeneko`, `just all`, ...
-tools/keyboard-tester/  -- local switch-tester web app for rebuilding hotswap boards.
+tools/keyboard-tester/          -- local switch-tester web app for rebuilding hotswap boards.
+tools/keyboard-latency-tracer/  -- macOS CGEventTap to measure QMK modtap latency.
 ```
 
 ## First run
@@ -185,6 +186,10 @@ detected within `DEBOUNCE` ms. Measured on the Mirage: 7.4ms -> ~0.04ms.
 Combined with `HOLD_ON_OTHER_KEY_PRESS`, rolled Ctrl+key combos send `<C-key>`
 instead of `<Esc-key>`.
 
+The latency was measured with `tools/keyboard-latency-tracer/`, a small macOS
+CGEventTap that prints every OS-level key event with high-resolution
+timestamps. See that directory's README and `docs/2026-06-19-keyboard-latency-investigation/README.md`.
+
 ### macOS Fn / Globe double-tap (`CTL_DBL_FN`)
 
 Every active keymap (Mirage, NEO65, DB60) maps the bottom-left physical key
diff --git a/docs/2026-06-19-keyboard-latency-investigation/README.md b/docs/2026-06-19-keyboard-latency-investigation/README.md
new file mode 100644
index 0000000..234efb0
--- /dev/null
+++ b/docs/2026-06-19-keyboard-latency-investigation/README.md
@@ -0,0 +1,95 @@
+# Keyboard modtap latency investigation
+
+Dated: 2026-06-19
+
+## Background
+
+With the Mirage keymap, the Caps position is a mod-tap (`LCTL_T(KC_ESC)`):
+tap for Esc, hold for left Control. When rolling a `Ctrl + key` combo, the
+interaction felt sluggish compared to a regular board.
+
+## Goals
+
+- Measure exactly how much latency QMK was adding between the physical press
+  and the OS receiving the Control modifier.
+- Find a QMK configuration that reduces the latency to effectively zero.
+
+## Investigation
+
+We built `tools/keyboard-latency-tracer/`, a small macOS CGEventTap that logs
+every OS-level key event with high-resolution timestamps. Running the same
+sequence on the Mirage and on a non-modtap board confirmed that QMK's default
+debounce strategy was holding the Control event.
+
+The relevant sequence is:
+
+1. Press and hold the mod-tap `LCTL_T(KC_ESC)` key.
+2. Press a second key, e.g. `c`.
+
+With the default QMK debounce (`sym_defer_g`, 5ms), the press is not reported
+until the debounce window has passed with no further bounce. This meant the
+Control modifier arrived about 7.4ms after the physical key action. More
+importantly, because the modifier and the rolled character are resolved
+through the mod-tap machinery, the effective gap felt even larger in practice.
+
+## Decision
+
+Switch to eager per-row debounce (`sym_eager_pr`) with a 5ms window:
+
+```c
+#define DEBOUNCE_TYPE sym_eager_pr
+#define DEBOUNCE 5
+```
+
+With eager debounce, the key-down is reported immediately. If noise is
+detected inside the 5ms window, the report is reverted; otherwise it sticks.
+This removes the deferral delay entirely.
+
+We also enabled `HOLD_ON_OTHER_KEY_PRESS` so that, when the mod-tap key is
+held and a second key is pressed, QMK resolves the mod-tap as a held modifier
+rather than a tap. This stops rolled combos from producing the tap output
+(`Esc + key`) and instead emits `Ctrl + key`.
+
+## Results
+
+Measured latency on the Mirage:
+
+- Before (`sym_defer_g`): ~7.4ms between Control-going-down and the next key.
+- After (`sym_eager_pr`): ~0.04ms.
+
+The interaction now feels identical to a board with dedicated modifiers.
+
+## Implementation
+
+Eager debounce and the hold-on-other-key-press flag are set in each active
+keymap's `config.h`:
+
+- `keyboards/mode/m256wh/keymaps/mirage/config.h`
+- `keyboards/neo/neo65_trimode/keymaps/aliou/config.h`
+
+(`sym_eager_pr` was present from the initial Mirage keymap commit. The NEO65
+keymap received the same treatment when it was brought up to match the Mirage
+layout.)
+
+## Risks
+
+- Eager debounce can in theory report a noisy/bouncing switch press that a
+  deferred debounce would suppress. With `DEBOUNCE 5` ms this has not been a
+  problem in practice.
+- `HOLD_ON_OTHER_KEY_PRESS` makes intentional tap+quick-roll sequences behave
+  like modifier holds. For this layout that is the desired behavior, but it
+  may not suit every keymap.
+
+## Status
+
+Solved. The tracer is kept in the repo as a reusable diagnostic tool under
+`tools/keyboard-latency-tracer/`.
+
+## Affected files and commands
+
+- `tools/keyboard-latency-tracer/Makefile`
+- `tools/keyboard-latency-tracer/tracer.c`
+- `tools/keyboard-latency-tracer/README.md`
+- `keyboards/mode/m256wh/keymaps/mirage/config.h`
+- `keyboards/neo/neo65_trimode/keymaps/aliou/config.h`
+- Build: `make` inside `tools/keyboard-latency-tracer/`, then `./tracer`
diff --git a/docs/README.md b/docs/README.md
index 16496cf..54c9dcd 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,6 +4,7 @@ Dated decision/operation records and architecture notes for the keebs repo.
 
 | Date | Topic | File |
 |---|---|---|
+| 2026-06-19 | Keyboard modtap latency investigation | `2026-06-19-keyboard-latency-investigation/README.md` |
 | 2026-06-20 | Archiving retired keymaps | `2026-06-20-archive-keyboards/README.md` |
 | 2026-06-20 | edthu wireless vendoring + NEO65 tri-mode support | `2026-06-20-edthu-wireless-neo65/README.md` |
 | 2026-06-20 | Auto-flash Nushell scripts + DFU polling | `2026-06-20-auto-flash-scripts/README.md` |
diff --git a/tools/keyboard-latency-tracer/.gitignore b/tools/keyboard-latency-tracer/.gitignore
new file mode 100644
index 0000000..282dd6b
--- /dev/null
+++ b/tools/keyboard-latency-tracer/.gitignore
@@ -0,0 +1 @@
+tracer
diff --git a/tools/keyboard-latency-tracer/Makefile b/tools/keyboard-latency-tracer/Makefile
new file mode 100644
index 0000000..54f1031
--- /dev/null
+++ b/tools/keyboard-latency-tracer/Makefile
@@ -0,0 +1,10 @@
+CFLAGS = -O2 -Wall -Wextra
+LDFLAGS = -framework ApplicationServices -framework CoreFoundation
+
+tracer: tracer.c
+	$(CC) $(CFLAGS) -o $@ $< $(LDFLAGS)
+
+clean:
+	rm -f tracer
+
+.PHONY: clean
diff --git a/tools/keyboard-latency-tracer/README.md b/tools/keyboard-latency-tracer/README.md
new file mode 100644
index 0000000..a3acffd
--- /dev/null
+++ b/tools/keyboard-latency-tracer/README.md
@@ -0,0 +1,74 @@
+# keyboard-latency-tracer
+
+A tiny macOS host-side tool to debug QMK modtap latency (e.g. `LCTL_T(KC_ESC)`
+on a Mirage build feeling sluggish when doing `Ctrl + anything`).
+
+It does NOT modify the keyboard. It only records every key event the OS sees,
+with high-resolution timestamps, so you can measure the gap between the control
+modifier going down and the next typed character going down. With a non-modded
+keyboard (e.g. qk65) that gap is basically the time you take to roll your
+fingers. With a modtap, if QMK is holding the modifier event until a second key
+or `TAPPING_TERM` triggers it, you'll see it.
+
+## What it measures
+
+For every event it prints one line:
+
+```
+<mach_ns> <us_since_prev_line> <kind> keycode=<code> name=<label> flags=<modifiers>
+```
+
+- `kind` ∈ {`FLAGS`, `DOWN`, `UP`}
+- `flags` is the modifier mask AFTER the event (e.g. `CTL`, `CTL|SHIFT`)
+- `us_since_prev_line` is microseconds between two consecutive OS-side events.
+  This is the number we care about: when you hold Ctrl and then press `c`,
+  the gap between the OS receiving `LCTL down` and receiving `c down`. If QMK
+  emits them back-to-back, this is ~0-2000us. If QMK is deferring the modifier
+  until tapping term, this is 200,000us (the whole tapping term!).
+
+## Build
+
+```
+make
+```
+
+You need Xcode command line tools (`xcode-select --install`).
+
+## Run
+
+```
+./tracer
+```
+
+No `sudo`: the Input Monitoring permission attaches to the app that owns the
+process, which is your Terminal.
+
+The first run macOS will block the tap and show a dialog asking you to grant
+**Input Monitoring** to Terminal (or whatever app launched it). Grant it, then
+re-run.
+
+## Stopping
+
+Stop with any of:
+- **Bare `q`** (no modifiers) on the tested keyboard.
+- **10 seconds of no activity** (auto-stop).
+- **`pkill tracer`** (SIGTERM) from another terminal.
+
+Ctrl+C, Ctrl+Z, and Ctrl+\ are explicitly ignored by the tracer so you can
+freely type any Ctrl+key combo (including Ctrl+C) as a test case.
+
+## Test procedure
+
+For each keyboard, do the same sequence and compare the printed numbers:
+
+1. Tap the left Ctrl/Esc key once alone. (Mirage: ESC should fire on release.)
+2. Hold the left Ctrl key down, then tap `c`. Release c. Release Ctrl.
+   -> Maintain a steady roll (~same speed on both boards).
+3. Hold the left Ctrl key down, then type `hello`.
+
+On the Mirage, the only modifier resolution point is at the second keypress, so
+the LCTL-down event and the `c`-down event should arrive ~together. If you see
+the c-down arrive noticeably before any LCTL-down event, or see a ~200ms gap
+between them, that is the modtap latency.
+
+Compare the same run on the qk65.
diff --git a/tools/keyboard-latency-tracer/tracer.c b/tools/keyboard-latency-tracer/tracer.c
new file mode 100644
index 0000000..2e0e23f
--- /dev/null
+++ b/tools/keyboard-latency-tracer/tracer.c
@@ -0,0 +1,295 @@
+// keyboard-latency-tracer: records every key event macOS sees with high-res
+// timestamps so we can measure QMK modtap latency (e.g. LCTL_T(KC_ESC)).
+//
+// It only OBSERVES events; it never injects or swallows them.
+// Requires Input Monitoring permission (System Settings -> Privacy & Security).
+
+#include <ApplicationServices/ApplicationServices.h>
+#include <CoreFoundation/CoreFoundation.h>
+#include <mach/mach_time.h>
+#include <stdio.h>
+#include <string.h>
+#include <stdlib.h>
+#include <signal.h>
+
+// -------- event description helpers --------
+
+static const char *flag_str(CGEventFlags f, char *buf, size_t n) {
+    buf[0] = '\0';
+    if (f & kCGEventFlagMaskAlternate) strncat(buf, "ALT|", n - strlen(buf) - 1);
+    if (f & kCGEventFlagMaskControl)    strncat(buf, "CTL|", n - strlen(buf) - 1);
+    if (f & kCGEventFlagMaskShift)     strncat(buf, "SFT|", n - strlen(buf) - 1);
+    if (f & kCGEventFlagMaskCommand)    strncat(buf, "CMD|", n - strlen(buf) - 1);
+    size_t l = strlen(buf);
+    if (l && buf[l - 1] == '|') buf[l - 1] = '\0';
+    if (l == 0) strncat(buf, "-", n - strlen(buf) - 1);
+    return buf;
+}
+
+static const char *key_name(CGKeyCode code) {
+    // Only label the keys we care about for this test.
+    switch (code) {
+        case 59: return "LEFT_CONTROL";
+        case 60: return "SHIFT";
+        case 58: return "LEFT_OPTION";
+        case 55: return "LEFT_COMMAND";
+        case 56: return "LEFT_SHIFT";
+        case 0:  return "A";
+        case 1:  return "S";
+        case 2:  return "D";
+        case 3:  return "F";
+        case 6:  return "Z";
+        case 7:  return "X";
+        case 8:  return "C";
+        case 9:  return "V";
+        case 11: return "B";
+        case 12: return "Q";
+        case 13: return "W";
+        case 14: return "E";
+        case 15: return "R";
+        case 16: return "T";
+        case 17: return "Y";
+        case 31: return "O";
+        case 34: return "I";
+        case 38: return "J";
+        case 40: return "K";
+        case 37: return "L";
+        case 41: return "F8";
+        case 36: return "ENTER";
+        case 49: return "SPACE";
+        case 53: return "ESC";
+        case 14 + 50: return "?";
+        default: return "?";
+    }
+}
+
+// -------- mach time conversions --------
+
+static mach_timebase_info_data_t s_tb;
+static uint64_t s_t0; // monotonic ns at program start
+
+static uint64_t event_to_ns(CGEventRef ev) {
+    // CGEvent timestamps are in the same units as mach_absolute_time.
+    uint64_t t = (uint64_t)CGEventGetTimestamp(ev);
+    uint64_t ns = (t * s_tb.numer) / s_tb.denom;
+    if (s_t0 == 0) s_t0 = ns;
+    return ns;
+}
+
+// -------- stopping the run loop --------
+
+// We can't use Ctrl+C to quit: on the tested keyboard, Ctrl+C is itself a
+// Ctrl+key combo we want to measure, AND the terminal turns Ctrl+C into
+// SIGINT. So we IGNORE SIGINT entirely (and SIGTSTP/SIGQUIT from Ctrl+Z,
+// Ctrl+\ too) and instead stop on:
+//   - bare 'q' keypress, or
+//   - 10 s of no activity (auto-stop), or
+//   - SIGTERM (`pkill tracer`) as a backup.
+static void stop_loop(void) { CFRunLoopStop(CFRunLoopGetCurrent()); }
+
+static void sigterm_handler(int sig) {
+    (void)sig;
+    stop_loop();
+}
+
+// Last event wall-clock time (CFAbsoluteTime, seconds since 2001) for idle
+// detection. Using wall clock avoids any clock-base mismatch between
+// CGEvent timestamps and mach_absolute_time.
+static CFAbsoluteTime s_last_evt_wall = 0;
+static double         s_idle_seconds = 10.0;
+
+// -------- per-event logging --------
+
+typedef struct {
+    uint64_t ts_ns;
+    uint64_t gap_us;
+    const char *kind;       // "FLAGS", "DOWN", "UP"
+    CGKeyCode code;
+    CGEventFlags flags;
+} line_t;
+
+#define MAX_LINES 65536
+static line_t s_lines[MAX_LINES];
+static size_t s_nlines = 0;
+
+static void log_event(uint64_t ts_ns, const char *kind,
+                      CGKeyCode code, CGEventFlags flags) {
+    s_last_evt_wall = CFAbsoluteTimeGetCurrent();
+    if (s_nlines >= MAX_LINES) { stop_loop(); return; }
+    uint64_t gap = s_nlines ? (ts_ns - s_lines[s_nlines - 1].ts_ns) / 1000 : 0;
+    s_lines[s_nlines].ts_ns    = ts_ns;
+    s_lines[s_nlines].gap_us   = gap;
+    s_lines[s_nlines].kind     = kind;
+    s_lines[s_nlines].code     = code;
+    s_lines[s_nlines].flags    = flags;
+    s_nlines++;
+
+    char fbuf[64];
+    printf("%12llu %12llu %-6s keycode=%3d name=%-14s flags=%s\n",
+           ts_ns, gap, kind, (int)code, key_name(code),
+           flag_str(flags, fbuf, sizeof(fbuf)));
+    fflush(stdout);
+}
+
+// -------- event tap callback --------
+
+// Periodic timer: auto-stop after s_idle_seconds of no events.
+static void idle_timer_cb(CFRunLoopTimerRef t, void *info) {
+    (void)t; (void)info;
+    if (s_last_evt_wall == 0) return; // haven't seen any events yet
+    double idle = CFAbsoluteTimeGetCurrent() - s_last_evt_wall;
+    if (idle >= s_idle_seconds) {
+        fprintf(stderr, "\n[%.1fs idle -> stopping]\n", idle);
+        stop_loop();
+    }
+}
+
+static CGEventRef tap_callback(CGEventTapProxy proxy, CGEventType type,
+                               CGEventRef event, void *userInfo) {
+    (void)proxy; (void)userInfo;
+
+    if (type == kCGEventTapDisabledByTimeout ||
+        type == kCGEventTapDisabledByUserInput) {
+        return event;
+    }
+
+    CGKeyCode code = CGEventGetIntegerValueField(event, kCGKeyboardEventKeycode);
+    CGEventFlags flags = CGEventGetFlags(event);
+    uint64_t ns = event_to_ns(event);
+
+    switch (type) {
+        case kCGEventFlagsChanged: log_event(ns, "FLAGS", code, flags); break;
+        case kCGEventKeyDown:
+            log_event(ns, "DOWN", code, flags);
+            // Stop on a bare 'q' (no modifiers) so the tested keyboard can
+            // end the trace without injecting a Ctrl+key combo.
+            if (code == 12 && !flags) { // 12 == 'q'
+                fprintf(stderr, "\n['q' pressed -> stopping]\n");
+                stop_loop();
+            }
+            break;
+        case kCGEventKeyUp:        log_event(ns, "UP",    code, flags); break;
+        default: break;
+    }
+    return event; // pass through unchanged
+}
+
+// -------- summary at exit --------
+
+static int cmp_gap(const void *a, const void *b) {
+    uint64_t ga = ((const line_t *)a)->gap_us;
+    uint64_t gb = ((const line_t *)b)->gap_us;
+    return (ga < gb) - (ga > gb);
+}
+
+static void print_summary(void) {
+    if (s_nlines < 2) return;
+    printf("\n=== summary: %zu events ===\n", s_nlines);
+
+    // Sort a copy by gap to show the top 10 longest inter-event gaps.
+    // This highlights any ~200000us (tapping term) deferral.
+    static line_t sorted[MAX_LINES];
+    memcpy(sorted, s_lines, s_nlines * sizeof(line_t));
+    qsort(sorted, s_nlines, sizeof(line_t), cmp_gap);
+
+    printf("top 10 longest gaps between consecutive events:\n");
+    size_t top = s_nlines < 10 ? s_nlines : 10;
+    for (size_t i = 0; i < top; i++) {
+        char fbuf[64];
+        printf("  %12llu us  %-6s name=%-14s flags=%s\n",
+               sorted[i].gap_us, sorted[i].kind, key_name(sorted[i].code),
+               flag_str(sorted[i].flags, fbuf, sizeof(fbuf)));
+    }
+
+    // Also report specifically the relationship we came here to test:
+    // for any DOWN event whose flags show CTL, find the preceding
+    // FLAGS event that *set* CTL and report the gap between them.
+    printf("\nctrl+key combos (CTL flag set at key-down):\n");
+    int found = 0;
+    for (size_t i = 0; i < s_nlines; i++) {
+        if (strcmp(s_lines[i].kind, "DOWN") != 0) continue;
+        if (!(s_lines[i].flags & kCGEventFlagMaskControl)) continue;
+        // Walk backward to the most recent FLAGS event whose flags set CTL
+        // and which represents the moment CTL went down.
+        // We approximate: previous FLAGS event overall.
+        uint64_t ctl_down_at = 0;
+        int ctl_down_seen = 0;
+        for (ssize_t j = (ssize_t)i - 1; j >= 0; j--) {
+            if (strcmp(s_lines[j].kind, "FLAGS") != 0) continue;
+            if (s_lines[j].flags & kCGEventFlagMaskControl) {
+                ctl_down_at = s_lines[j].ts_ns;
+                ctl_down_seen = 1;
+            } else {
+                break; // CTL was not set here
+            }
+        }
+        char fbuf[64];
+        if (ctl_down_seen) {
+            uint64_t gap_us = (s_lines[i].ts_ns - ctl_down_at) / 1000;
+            printf("  %-14s: %llu us between CTL-going-down and this key-down\n",
+                   key_name(s_lines[i].code), gap_us);
+        } else {
+            printf("  %-14s: CTL flag set but no prior CTL-down FLAGS event "
+                   "(rolled together) flags=%s\n",
+                   key_name(s_lines[i].code),
+                   flag_str(s_lines[i].flags, fbuf, sizeof(fbuf)));
+        }
+        found++;
+    }
+    if (!found) {
+        printf("  (none observed -- you didn't produce a Ctrl+key combo)\n");
+    }
+}
+
+int main(void) {
+    mach_timebase_info(&s_tb);
+
+    CFMachPortRef tap = CGEventTapCreate(
+        kCGSessionEventTap, kCGHeadInsertEventTap,
+        kCGEventTapOptionListenOnly,
+        CGEventMaskBit(kCGEventFlagsChanged) |
+        CGEventMaskBit(kCGEventKeyDown) |
+        CGEventMaskBit(kCGEventKeyUp),
+        tap_callback, NULL);
+
+    if (!tap) {
+        fprintf(stderr,
+            "Could not create event tap.\n"
+            "Grant Input Monitoring permission to this terminal/app in\n"
+            "System Settings -> Privacy & Security -> Input Monitoring,\n"
+            "then re-run.\n");
+        return 1;
+    }
+
+    CFRunLoopSourceRef src = CFMachPortCreateRunLoopSource(
+        kCFAllocatorDefault, tap, 0);
+    CFRunLoopAddSource(CFRunLoopGetCurrent(), src, kCFRunLoopCommonModes);
+    CGEventTapEnable(tap, true);
+
+    // Ignore the terminal "quit" signals so typing Ctrl+C / Ctrl+Z / Ctrl+\
+    // (which the terminal converts to SIGINT/SIGTSTP/SIGQUIT) does not kill
+    // the tracer. Stop with bare 'q', idle timeout, or `pkill tracer` (SIGTERM).
+    signal(SIGINT,  SIG_IGN);
+    signal(SIGTSTP, SIG_IGN);
+    signal(SIGQUIT, SIG_IGN);
+    signal(SIGTERM, sigterm_handler);
+
+    // Idle timer: check every 0.25s whether we've gone quiet.
+    CFRunLoopTimerRef timer = CFRunLoopTimerCreate(
+        kCFAllocatorDefault,
+        CFAbsoluteTimeGetCurrent() + 0.25, 0.25, 0, 0,
+        idle_timer_cb, NULL);
+    CFRunLoopAddTimer(CFRunLoopGetCurrent(), timer, kCFRunLoopCommonModes);
+
+    printf("Tracing. Stop with: bare 'q', or %g s idle.\n"
+           "(Ctrl+C is ignored so you can measure Ctrl+key combos. "
+           "Backup stop: `pkill tracer`.)\n\n",
+           s_idle_seconds);
+    printf("%12s %12s %-6s %-14s %-14s %s\n",
+           "ns", "us_gap", "kind", "", "name", "flags");
+
+    CFRunLoopRun();
+
+    print_summary();
+    return 0;
+}
-- 
2.51.2