[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M72E657SDH6GA08WGP5ES057":3,"skill-same:01M72E657SDH6GA08WGP5ES057":48},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":29,"ownerHtmlUrl":30,"ownerBlogUrl":31,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M72E657SDH6GA08WGP5ES057","textual-non-blocking-pump",null,"Use when writing, reviewing, or auditing agentgrep TUI code (src\u002Fagentgrep\u002Fui\u002F) for anything that could freeze the Textual message pump — keystrokes\u002Fspinner\u002Fcancel hang, a handler that blocks, a slow filter\u002Ffind\u002Fdetail render, \"the UI froze\", a new pump method\u002Ftimer\u002Fworker, or revising the ADR 0011 non-blocking safeguards.","tony\u002Fagentgrep","tony","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F26336?v=4","01M72E5RNJ7SQV8F9KBM5RKRMN","Tony Narlock","01M72E5RP6M0TRDFA54GT6B85H",9,"MIT","https:\u002F\u002Fgithub.com\u002Ftony\u002Fagentgrep\u002Fblob\u002Fmaster\u002F.agents\u002Fskills\u002Ftextual-non-blocking-pump\u002FSKILL.md",[],[],"2026-11-10 18:39:20",false,"---\nname: textual-non-blocking-pump\ndescription: Use when writing, reviewing, or auditing agentgrep TUI code (src\u002Fagentgrep\u002Fui\u002F) for anything that could freeze the Textual message pump — keystrokes\u002Fspinner\u002Fcancel hang, a handler that blocks, a slow filter\u002Ffind\u002Fdetail render, \"the UI froze\", a new pump method\u002Ftimer\u002Fworker, or revising the ADR 0011 non-blocking safeguards.\n---\n\n# Keeping the Textual pump non-blocking\n\n## Overview\n\nagentgrep's TUI runs on a **single-threaded message pump**. Any callable Textual\ninvokes on that thread that runs longer than a frame budget (~16 ms) — or never\nreturns — freezes *everything at once*: keystrokes, the spinner, resize, and\ncancel. ADR 0011 (NB-1..NB-10) is the contract; `ui\u002F_runtime.py` has the\nprimitives; `tests\u002Ftest_tui_runtime_oracles.py` pins the deterministic heartbeat\noracle.\n\n**The one idea to internalize:** \"blocks the pump\" is a *semantic* property of\nruntime behavior, not a *syntactic* property of source text. By Rice's theorem\nno static analyzer can flag *all and only* blocking code (it reduces to\nhalting). So the goal is **never 100% static prevention**. Manual entrypoint and\nhelper review reduces recognizable risks; enabled decorators and the explicit\naudit mode prevent covered misuse; a cause-agnostic runtime oracle detects the\nsuper-threshold residue on exercised paths. Treat any \"we'll just lint for it\"\ninstinct as the trap this skill exists to correct.\n\n## When to use\n\n- Adding\u002Fediting any method on a Textual `App` \u002F `Screen` \u002F `Widget` in `ui\u002F`.\n- A user reports a freeze\u002Fhang\u002Fjank; the spinner stalls; cancel stops responding.\n- Reviewing a PR that touches `ui\u002F` — especially filter, find-in-detail, detail\n  rendering, streaming apply, or anything reading a store.\n- Revising ADR 0011, the `_runtime` primitives, this review method, or the\n  retained watchdog oracle.\n\nWhen NOT to use: non-UI engine\u002FMCP work (those run off the pump by construction);\npure styling\u002F`.tcss` edits with no Python.\n\n## The trap: why a denylist lint feels like enough and isn't\n\nManual static review can follow same-class `self.helper()` calls, enumerate\n`@on` handlers and scheduler \u002F `call_from_thread` \u002F `subscribe` targets, and\nsearch for obvious blocking calls. No automated static gate is retained, and\nmanual review still cannot be *complete* — by Rice's theorem no denylist can.\nFour holes remain, each the shape of a real hang this repo has shipped:\n\n1. **Helper tracing is bounded by reviewer knowledge.** Following\n   `self.helper()` within a class is straightforward, but a blocking call reached\n   through *cross-module* dispatch, a stored callable, or `getattr` is easy to\n   miss. (The `os.write` history-write hang — commit `8b26d8a3` — was an\n   intra-class example.)\n2. **Classification needs explicit enumeration.** Review `@on` handlers and the\n   callables at scheduler \u002F `call_from_thread` \u002F `subscribe` sites, including a\n   `lambda` or `functools.partial`; inline reactive `validate_`\u002F`compute_` hooks\n   must also be found deliberately.\n3. **Text search is finite.** Searching imports and qualified calls can find\n   network \u002F fs-walk \u002F `json.load` \u002F `input`, but generic-attribute blocking\n   (`Lock.acquire` \u002F `Queue.get` \u002F `Future.result` — no type to match on) is not\n   reliably representable.\n4. **Pure-CPU blocking has no call signature at all.** An unbounded\n   `casefold`\u002F`sort`\u002F`regex` over the result set, or `Syntax(...).highlight` on a\n   full body, cannot be denylisted. This is the undecidable core.\n\n**ruff and ty cannot close this.** ruff's `ASYNC2xx` rules fire *only inside\n`async def`* (pump methods are mostly sync) and ruff has no custom-Python-rule\nAPI. ty has no plugin system; `Annotated` metadata is dropped; the only working\ntype pattern is a `PumpView`\u002F`WorkerIO` capability seam, and even that leaks\nthrough `Any`-erasure and direct `builtins.open()`. Type coloring is the\n*lowest*-leverage option.\n\n## Pump-entrypoint catalog (enumerate, don't prefix-guess)\n\nEvery callable below runs on the event-loop thread. A new one that does heavy\nwork MUST be `@pump_only` so enabled runtime assertions check its thread\nplacement and reviewers can recognize the seam; route its heavy work off the\npump.\n\n| Family | Entrypoints | Manual enumeration cue |\n|---|---|---|\n| Message handlers | `on_*`, `_on_*`, **any `@on(...)`-decorated method (any name)** | Search prefixes and inspect every `@on` decorator. |\n| Reactivity (inline, sync) | `watch_*`, `validate_*`, `compute_*` — bypass the message queue *and* Textual's own SLOW_THRESHOLD | Search all three prefixes. |\n| Render\u002Flayout (compositor) | `render`, `render_line`, `__rich__`, `get_content_width\u002Fheight`, `pre_layout` | Enumerate exact and prefixed render hooks. |\n| Actions | `action_*`, `_action_*` (key bindings, links) | Search both prefixes. |\n| Scheduled callbacks | `set_timer`, `set_interval`, `call_later`, `call_next`, `call_after_refresh` targets — **arbitrary names** | Inspect each call site and named, `lambda`, or `partial` target. |\n| Cross-thread callees (NB-8) | anything passed to `call_from_thread(fn, …)` — **arbitrary names** | Inspect each call site and target. |\n| Signals | `subscribe(self, fn)` callbacks (e.g. theme-changed) | Inspect each subscription target. |\n| Startup | `compose`, `on_mount` (run before the loop, on the pump) | Search the exact hooks. |\n| Async `@work` **without** `thread=True` | the coroutine body runs *on the loop* — CPU without `await` freezes it | Inspect every `@work` and `run_worker`. |\n\nOff the pump (safe place for blocking work): `@work(thread=True)` \u002F\n`run_worker(..., thread=True)` bodies, decorated `@offload`.\n\n## Defense in depth (the actual answer)\n\nNo single mechanism both prevents and detects. Combine manual review with the\nruntime mechanisms, organized by the I\u002FO-vs-CPU asymmetry:\n\n| Hazard | Review \u002F structural prevention | Runtime complement |\n|---|---|---|\n| Covered I\u002FO\u002Fprocess initiation | Entrypoint catalog, helper tracing, and `@offload` seams | Explicit-env `sys.addaudithook` can abort allowlisted events on the acting thread. |\n| CPU spin, open-handle transfer, or native I\u002FO | Bound the work or move it to an `@offload` worker. | The heartbeat reports exercised stalls above its wall-clock threshold. |\n\n- **`sys.addaudithook` uses a finite eight-event allowlist**:\n  `socket.connect`, `socket.getaddrinfo`, `subprocess.Popen`, `os.system`,\n  `os.exec`, `os.spawn`, `time.sleep`, and `sqlite3.connect`. For those covered\n  events, the hook fires synchronously on the *acting* thread, so raising can\n  abort initiation regardless of how the operation was spelled, aliased, or\n  dynamically dispatched.\n- **`open` and `import` are deliberately excluded** because Textual\u002FRich\n  legitimately read theme and syntax files on the pump and perform lazy imports\n  there. The hook is also blind to CPU spin, byte-transfer on *already-open*\n  handles (`recv`\u002F`send`, `cursor.execute` on a live connection — the canonical\n  slow-query hang carries no audit event), and native Rust\u002FC syscalls that skip\n  `PySys_Audit`.\n- **The wall-clock watchdog is the cause-agnostic backstop** for exactly that\n  residue: it catches anything that stalls past a threshold, of any cause. Ceiling:\n  only above threshold, only on exercised inputs, only *after* the freeze (it\n  cannot abort a thread mid-C-syscall — only kill the process). This is the\n  asyncio `slow_callback_duration` model.\n\nThe `@pump_only` \u002F `@offload` assertions run under pytest or an explicitly\ntruthy `AGENTGREP_TUI_WATCHDOG`; the audit hook requires the explicit truthy\nsetting because it can raise. The log-only heartbeat watchdog **defaults on for\nan interactive TTY**, a falsey setting forces it off, and pytest does not\nauto-start it. `tests\u002Ftest_tui_runtime_oracles.py` deterministically pins the\nheartbeat warning without relying on a real-time hang.\n\n## Review rules (apply on EVERY ui\u002F change)\n\nStatic analysis provably cannot self-discover new pump entrypoints, CPU blocking,\nor stale-event paths. These are the judgment calls a reviewer\u002Fagent must make:\n\n1. **Decorate every new pump entrypoint `@pump_only`** (catalog above), every\n   `run_worker` target `@offload` (`thread=True, exclusive=True` except\n   `group=\"history\"`, stable `group=`).\n2. **No blocking work reachable from a pump callable**, even one hop down a\n   helper: no file open, subprocess, sqlite3, network, fs-walk\n   (`glob`\u002F`scandir`\u002F`walk`\u002F`iterdir`\u002F`stat`), lock\u002Fqueue\u002F`Event.wait`,\n   `futures.result`, `json.load(s)`\u002F`dump(s)`, `.read()`\u002F`.readlines()`,\n   `time.sleep`, or **unbounded CPU** (full-result `casefold`\u002F`sort`\u002F`regex`,\n   `Syntax(...).highlight` on a full body). Route bulk UI updates through\n   `stream_apply`; route large\u002Funcached detail builds through an `@offload` worker.\n3. **Never satisfy review by aliasing\u002F`from`-import** — that's evasion, not a\n   fix. Move the call off the pump.\n4. **Worker bodies must not read\u002Fmutate pump-owned state** (widget\u002Ftheme vars);\n   snapshot on the pump and pass it in (cf. `b1bc2f48`).\n5. **Cross-thread chrome repaint carries a generation token** (`make_gated_emitter`,\n   NB-10); recompute find\u002Fmatch state from live values; cancel pending debounce\n   timers on record-switch\u002Fclose. *Stale-event repaint is the most recurrent\n   historical hang (~8 fixes) and no oracle detects it.*\n6. **Teardown-reachable handlers tolerate an empty screen stack** (early-return);\n   teardown exceptions are invisible to every blocking oracle (cf. `4895d2a2`).\n7. **Don't raise runtime bounds** (`_DETAIL_ASYNC_BODY_THRESHOLD=20000`,\n   `stream_apply` chunk cap `200`) without re-proving the per-frame budget — the\n   manual review cannot prove these constants still gate the inline path.\n8. **Exercise the change once under `AGENTGREP_TUI_WATCHDOG=1` against a large\n   real store** before claiming a path is non-blocking; review cannot prove the\n   absence of CPU\u002Fdata-dependent blocking.\n\n## Audit procedure (when hunting an existing hang)\n\n1. Reproduce; note which interaction freezes (filter widen, find keystroke,\n   detail open on a big record, resize, theme switch).\n2. Map the interaction to its pump entrypoint via the catalog — **include the\n   arbitrary-named ones** (`@on`, timer, `call_from_thread`, `subscribe`).\n3. Follow the call graph by hand one+ hops; no automated static gate does this.\n   Look for the four holes: helper-extracted I\u002FO, unclassified entrypoint,\n   aliased call, unbounded CPU loop.\n4. Classify the cause: allowlisted I\u002FO-on-pump → offload + audit hook;\n   excluded\u002Funaudited I\u002FO → offload + manual review\u002Fwatchdog; unbounded CPU →\n   bound it (`stream_apply`) or offload + watchdog; stale-event → generation\n   token; teardown → empty-stack guard; worker-touches-pump-state → snapshot.\n5. Lock the behavior with the smallest focused regression. If the heartbeat\n   contract changes, extend `tests\u002Ftest_tui_runtime_oracles.py`.\n\n## What manual static review still can't catch\n\nTwo historical CPU stalls here — the filter rebuild\n(`on_filter_completed → set_records → _rebuild_options`) and the find-in-detail\nre-highlight (`_present_detail_find`) — are now bounded by an id-keyed row-render\ncache and a cached syntax base. The review residue is the four holes above plus\npure-CPU spin: cross-module\u002Fdynamic dispatch, `lambda`\u002F`partial` scheduler\ntargets, generic-attr blocking, and unbounded loops. The watchdog is the runtime\nbackstop for all of them; profile a suspected stall (synthetic records, timings\nonly) before reaching for a structural fix.\n\n## Residual risks (state these honestly; do not claim 100%)\n\nPure-CPU\u002Fdata-dependent blocking, native-extension syscalls, `recv`\u002F`execute` on\nopen handles, fast-in-CI\u002Fslow-in-prod, sub-threshold jank, stale-event repaint,\nand teardown exceptions can all slip manual review. The watchdog catches the\nsuper-threshold subset on exercised inputs, after the fact. The honest guarantee\nis \"high coverage via defense-in-depth,\" never literal completeness.\n\n## Reference\n\n- Contract: `docs\u002Fdev\u002Fadr\u002F0011-non-blocking-tui-invariants.md` (NB-1..NB-10).\n- Primitives: `src\u002Fagentgrep\u002Fui\u002F_runtime.py` (`pump_only`\u002F`offload`\u002F`stream_apply`\u002F\n  `make_gated_emitter`\u002F`start_pump_watchdog`).\n- Deterministic heartbeat oracle: `tests\u002Ftest_tui_runtime_oracles.py`.\n","# Keeping the Textual pump non-blocking\n\n## Overview\n\nagentgrep's TUI runs on a **single-threaded message pump**. Any callable Textual\ninvokes on that thread that runs longer than a frame budget (~16 ms) — or never\nreturns — freezes *everything at once*: keystrokes, the spinner, resize, and\ncancel. ADR 0011 (NB-1..NB-10) is the contract; `ui\u002F_runtime.py` has the\nprimitives; `tests\u002Ftest_tui_runtime_oracles.py` pins the deterministic heartbeat\noracle.\n\n**The one idea to internalize:** \"blocks the pump\" is a *semantic* property of\nruntime behavior, not a *syntactic* property of source text. By Rice's theorem\nno static analyzer can flag *all and only* blocking code (it reduces to\nhalting). So the goal is **never 100% static prevention**. Manual entrypoint and\nhelper review reduces recognizable risks; enabled decorators and the explicit\naudit mode prevent covered misuse; a cause-agnostic runtime oracle detects the\nsuper-threshold residue on exercised paths. Treat any \"we'll just lint for it\"\ninstinct as the trap this skill exists to correct.\n\n## When to use\n\n- Adding\u002Fediting any method on a Textual `App` \u002F `Screen` \u002F `Widget` in `ui\u002F`.\n- A user reports a freeze\u002Fhang\u002Fjank; the spinner stalls; cancel stops responding.\n- Reviewing a PR that touches `ui\u002F` — especially filter, find-in-detail, detail\n  rendering, streaming apply, or anything reading a store.\n- Revising ADR 0011, the `_runtime` primitives, this review method, or the\n  retained watchdog oracle.\n\nWhen NOT to use: non-UI engine\u002FMCP work (those run off the pump by construction);\npure styling\u002F`.tcss` edits with no Python.\n\n## The trap: why a denylist lint feels like enough and isn't\n\nManual static review can follow same-class `self.helper()` calls, enumerate\n`@on` handlers and scheduler \u002F `call_from_thread` \u002F `subscribe` targets, and\nsearch for obvious blocking calls. No automated static gate is retained, and\nmanual review still cannot be *complete* — by Rice's theorem no denylist can.\nFour holes remain, each the shape of a real hang this repo has shipped:\n\n1. **Helper tracing is bounded by reviewer knowledge.** Following\n   `self.helper()` within a class is straightforward, but a blocking call reached\n   through *cross-module* dispatch, a stored callable, or `getattr` is easy to\n   miss. (The `os.write` history-write hang — commit `8b26d8a3` — was an\n   intra-class example.)\n2. **Classification needs explicit enumeration.** Review `@on` handlers and the\n   callables at scheduler \u002F `call_from_thread` \u002F `subscribe` sites, including a\n   `lambda` or `functools.partial`; inline reactive `validate_`\u002F`compute_` hooks\n   must also be found deliberately.\n3. **Text search is finite.** Searching imports and qualified calls can find\n   network \u002F fs-walk \u002F `json.load` \u002F `input`, but generic-attribute blocking\n   (`Lock.acquire` \u002F `Queue.get` \u002F `Future.result` — no type to match on) is not\n   reliably representable.\n4. **Pure-CPU blocking has no call signature at all.** An unbounded\n   `casefold`\u002F`sort`\u002F`regex` over the result set, or `Syntax(...).highlight` on a\n   full body, cannot be denylisted. This is the undecidable core.\n\n**ruff and ty cannot close this.** ruff's `ASYNC2xx` rules fire *only inside\n`async def`* (pump methods are mostly sync) and ruff has no custom-Python-rule\nAPI. ty has no plugin system; `Annotated` metadata is dropped; the only working\ntype pattern is a `PumpView`\u002F`WorkerIO` capability seam, and even that leaks\nthrough `Any`-erasure and direct `builtins.open()`. Type coloring is the\n*lowest*-leverage option.\n\n## Pump-entrypoint catalog (enumerate, don't prefix-guess)\n\nEvery callable below runs on the event-loop thread. A new one that does heavy\nwork MUST be `@pump_only` so enabled runtime assertions check its thread\nplacement and reviewers can recognize the seam; route its heavy work off the\npump.\n\n| Family | Entrypoints | Manual enumeration cue |\n|---|---|---|\n| Message handlers | `on_*`, `_on_*`, **any `@on(...)`-decorated method (any name)** | Search prefixes and inspect every `@on` decorator. |\n| Reactivity (inline, sync) | `watch_*`, `validate_*`, `compute_*` — bypass the message queue *and* Textual's own SLOW_THRESHOLD | Search all three prefixes. |\n| Render\u002Flayout (compositor) | `render`, `render_line`, `__rich__`, `get_content_width\u002Fheight`, `pre_layout` | Enumerate exact and prefixed render hooks. |\n| Actions | `action_*`, `_action_*` (key bindings, links) | Search both prefixes. |\n| Scheduled callbacks | `set_timer`, `set_interval`, `call_later`, `call_next`, `call_after_refresh` targets — **arbitrary names** | Inspect each call site and named, `lambda`, or `partial` target. |\n| Cross-thread callees (NB-8) | anything passed to `call_from_thread(fn, …)` — **arbitrary names** | Inspect each call site and target. |\n| Signals | `subscribe(self, fn)` callbacks (e.g. theme-changed) | Inspect each subscription target. |\n| Startup | `compose`, `on_mount` (run before the loop, on the pump) | Search the exact hooks. |\n| Async `@work` **without** `thread=True` | the coroutine body runs *on the loop* — CPU without `await` freezes it | Inspect every `@work` and `run_worker`. |\n\nOff the pump (safe place for blocking work): `@work(thread=True)` \u002F\n`run_worker(..., thread=True)` bodies, decorated `@offload`.\n\n## Defense in depth (the actual answer)\n\nNo single mechanism both prevents and detects. Combine manual review with the\nruntime mechanisms, organized by the I\u002FO-vs-CPU asymmetry:\n\n| Hazard | Review \u002F structural prevention | Runtime complement |\n|---|---|---|\n| Covered I\u002FO\u002Fprocess initiation | Entrypoint catalog, helper tracing, and `@offload` seams | Explicit-env `sys.addaudithook` can abort allowlisted events on the acting thread. |\n| CPU spin, open-handle transfer, or native I\u002FO | Bound the work or move it to an `@offload` worker. | The heartbeat reports exercised stalls above its wall-clock threshold. |\n\n- **`sys.addaudithook` uses a finite eight-event allowlist**:\n  `socket.connect`, `socket.getaddrinfo`, `subprocess.Popen`, `os.system`,\n  `os.exec`, `os.spawn`, `time.sleep`, and `sqlite3.connect`. For those covered\n  events, the hook fires synchronously on the *acting* thread, so raising can\n  abort initiation regardless of how the operation was spelled, aliased, or\n  dynamically dispatched.\n- **`open` and `import` are deliberately excluded** because Textual\u002FRich\n  legitimately read theme and syntax files on the pump and perform lazy imports\n  there. The hook is also blind to CPU spin, byte-transfer on *already-open*\n  handles (`recv`\u002F`send`, `cursor.execute` on a live connection — the canonical\n  slow-query hang carries no audit event), and native Rust\u002FC syscalls that skip\n  `PySys_Audit`.\n- **The wall-clock watchdog is the cause-agnostic backstop** for exactly that\n  residue: it catches anything that stalls past a threshold, of any cause. Ceiling:\n  only above threshold, only on exercised inputs, only *after* the freeze (it\n  cannot abort a thread mid-C-syscall — only kill the process). This is the\n  asyncio `slow_callback_duration` model.\n\nThe `@pump_only` \u002F `@offload` assertions run under pytest or an explicitly\ntruthy `AGENTGREP_TUI_WATCHDOG`; the audit hook requires the explicit truthy\nsetting because it can raise. The log-only heartbeat watchdog **defaults on for\nan interactive TTY**, a falsey setting forces it off, and pytest does not\nauto-start it. `tests\u002Ftest_tui_runtime_oracles.py` deterministically pins the\nheartbeat warning without relying on a real-time hang.\n\n## Review rules (apply on EVERY ui\u002F change)\n\nStatic analysis provably cannot self-discover new pump entrypoints, CPU blocking,\nor stale-event paths. These are the judgment calls a reviewer\u002Fagent must make:\n\n1. **Decorate every new pump entrypoint `@pump_only`** (catalog above), every\n   `run_worker` target `@offload` (`thread=True, exclusive=True` except\n   `group=\"history\"`, stable `group=`).\n2. **No blocking work reachable from a pump callable**, even one hop down a\n   helper: no file open, subprocess, sqlite3, network, fs-walk\n   (`glob`\u002F`scandir`\u002F`walk`\u002F`iterdir`\u002F`stat`), lock\u002Fqueue\u002F`Event.wait`,\n   `futures.result`, `json.load(s)`\u002F`dump(s)`, `.read()`\u002F`.readlines()`,\n   `time.sleep`, or **unbounded CPU** (full-result `casefold`\u002F`sort`\u002F`regex`,\n   `Syntax(...).highlight` on a full body). Route bulk UI updates through\n   `stream_apply`; route large\u002Funcached detail builds through an `@offload` worker.\n3. **Never satisfy review by aliasing\u002F`from`-import** — that's evasion, not a\n   fix. Move the call off the pump.\n4. **Worker bodies must not read\u002Fmutate pump-owned state** (widget\u002Ftheme vars);\n   snapshot on the pump and pass it in (cf. `b1bc2f48`).\n5. **Cross-thread chrome repaint carries a generation token** (`make_gated_emitter`,\n   NB-10); recompute find\u002Fmatch state from live values; cancel pending debounce\n   timers on record-switch\u002Fclose. *Stale-event repaint is the most recurrent\n   historical hang (~8 fixes) and no oracle detects it.*\n6. **Teardown-reachable handlers tolerate an empty screen stack** (early-return);\n   teardown exceptions are invisible to every blocking oracle (cf. `4895d2a2`).\n7. **Don't raise runtime bounds** (`_DETAIL_ASYNC_BODY_THRESHOLD=20000`,\n   `stream_apply` chunk cap `200`) without re-proving the per-frame budget — the\n   manual review cannot prove these constants still gate the inline path.\n8. **Exercise the change once under `AGENTGREP_TUI_WATCHDOG=1` against a large\n   real store** before claiming a path is non-blocking; review cannot prove the\n   absence of CPU\u002Fdata-dependent blocking.\n\n## Audit procedure (when hunting an existing hang)\n\n1. Reproduce; note which interaction freezes (filter widen, find keystroke,\n   detail open on a big record, resize, theme switch).\n2. Map the interaction to its pump entrypoint via the catalog — **include the\n   arbitrary-named ones** (`@on`, timer, `call_from_thread`, `subscribe`).\n3. Follow the call graph by hand one+ hops; no automated static gate does this.\n   Look for the four holes: helper-extracted I\u002FO, unclassified entrypoint,\n   aliased call, unbounded CPU loop.\n4. Classify the cause: allowlisted I\u002FO-on-pump → offload + audit hook;\n   excluded\u002Funaudited I\u002FO → offload + manual review\u002Fwatchdog; unbounded CPU →\n   bound it (`stream_apply`) or offload + watchdog; stale-event → generation\n   token; teardown → empty-stack guard; worker-touches-pump-state → snapshot.\n5. Lock the behavior with the smallest focused regression. If the heartbeat\n   contract changes, extend `tests\u002Ftest_tui_runtime_oracles.py`.\n\n## What manual static review still can't catch\n\nTwo historical CPU stalls here — the filter rebuild\n(`on_filter_completed → set_records → _rebuild_options`) and the find-in-detail\nre-highlight (`_present_detail_find`) — are now bounded by an id-keyed row-render\ncache and a cached syntax base. The review residue is the four holes above plus\npure-CPU spin: cross-module\u002Fdynamic dispatch, `lambda`\u002F`partial` scheduler\ntargets, generic-attr blocking, and unbounded loops. The watchdog is the runtime\nbackstop for all of them; profile a suspected stall (synthetic records, timings\nonly) before reaching for a structural fix.\n\n## Residual risks (state these honestly; do not claim 100%)\n\nPure-CPU\u002Fdata-dependent blocking, native-extension syscalls, `recv`\u002F`execute` on\nopen handles, fast-in-CI\u002Fslow-in-prod, sub-threshold jank, stale-event repaint,\nand teardown exceptions can all slip manual review. The watchdog catches the\nsuper-threshold subset on exercised inputs, after the fact. The honest guarantee\nis \"high coverage via defense-in-depth,\" never literal completeness.\n\n## Reference\n\n- Contract: `docs\u002Fdev\u002Fadr\u002F0011-non-blocking-tui-invariants.md` (NB-1..NB-10).\n- Primitives: `src\u002Fagentgrep\u002Fui\u002F_runtime.py` (`pump_only`\u002F`offload`\u002F`stream_apply`\u002F\n  `make_gated_emitter`\u002F`start_pump_watchdog`).\n- Deterministic heartbeat oracle: `tests\u002Ftest_tui_runtime_oracles.py`.\n",{"name":5,"description":7},"master","b4cc32321965fa6c908b7d2d7e0650bbee9f85c4",".agents\u002Fskills\u002Ftextual-non-blocking-pump",1,"https:\u002F\u002Fgithub.com\u002Ftony\u002Fagentgrep","https:\u002F\u002Fagentgrep.org","https:\u002F\u002Fgithub.com\u002Ftony","https:\u002F\u002Ftony.sh","lighthouse keeper","2026-11-15 04:00:32",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add tony\u002Fagentgrep --skill textual-non-blocking-pump",{"tool":40,"command":41},"bunx","bunx skills add tony\u002Fagentgrep --skill textual-non-blocking-pump",{"tool":43,"command":44},"pnpm","pnpm dlx skills add tony\u002Fagentgrep --skill textual-non-blocking-pump","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Ftony\u002Fagentgrep\u002Fblob\u002Fmaster\u002F.agents\u002Fskills\u002Ftextual-non-blocking-pump\u002FSKILL.md",true,[],[49,55,61,68],{"skillNo":50,"name":51,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":19},"01M72E6AC6YTG31RKX4EM5EE0D","profile","https:\u002F\u002Fgithub.com\u002Ftony\u002Fagentgrep\u002Fblob\u002Fmaster\u002F.claude\u002Fskills\u002Fprofile\u002FSKILL.md",[],[],{"skillNo":56,"name":57,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":58,"categories":59,"keywords":60,"publishedAt":19},"01M72E695MZ9S0VB6DJH5EDRC2","benchmark","https:\u002F\u002Fgithub.com\u002Ftony\u002Fagentgrep\u002Fblob\u002Fmaster\u002F.claude\u002Fskills\u002Fbenchmark\u002FSKILL.md",[],[],{"skillNo":62,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":19},"01M72E5ZBCB33ZS1SBS0E2WBFK","testing-mcp-with-cli-agents","Test an MCP server by driving real CLI agents (Claude, Codex, Cursor, Gemini, Grok, agy) against it — isolating each CLI's config and the server's own backend state instead of trusting unit tests alone. Use this whenever verifying MCP-server behavior end-to-end, checking that a local branch or checkout works across installed agent CLIs, comparing trunk-vs-branch behavior, driving an interactive agent TUI to exercise approval flows or cancellation, or reproducing a bug through a live client. Reach for it even when the user only says \"test the MCP\", \"does the branch work in the agents\", \"drive the CLI to call the tool\", or \"check it across Codex\u002FGemini\u002FCursor\".","https:\u002F\u002Fgithub.com\u002Ftony\u002Fagentgrep\u002Fblob\u002Fmaster\u002F.agents\u002Fskills\u002Ftesting-mcp-with-cli-agents\u002FSKILL.md",[],[],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":19},"01M72E5VTCK4YCDV0N0B2G4HB3","refresh-backends","Assess and update agentgrep's backends and storage catalogue against the agent clients installed on this machine (claude, codex, cursor-agent, gemini, agy, grok, pi, opencode, VS Code, Cursor IDE, Antigravity IDE, Windsurf), versioning what each client version stores. Use when asked to sweep, refresh, audit, or update the backends or storages, check for drift after a client upgrade, observe a new client version, or record which version a storage change landed in.","https:\u002F\u002Fgithub.com\u002Ftony\u002Fagentgrep\u002Fblob\u002Fmaster\u002F.agents\u002Fskills\u002Frefresh-backends\u002FSKILL.md",[],[]]