This looks like a super useful fix for anyone regularly running CLI-based AI agents. Might be worth taking this PR for a spin with a similar test case right away.

@cary-rowen I don't use agents myself, but I'd love more testing of it since I don't have a lot of cases to test this on my system atm. One candidate I'm 99 percent sure this solves is things like journalctl -xfe (or similar) where system logs get dumped to your terminal and you have to wade through the output.

@cary-rowen Just confirmed: this fixes the console flood problem with jorunalctl at least.

can this please get a change log entry and more clearer testing steps in the PR description?

@seanbudd I can do the change log at least, but I'm not really sure what a "better testing strategy" entails. Like, you can validate it by SSH'ing into a server that's been up for a month or something and doing journalctl -xfe, but in general all the bugs I've looked at typically encounter this through a variety of circumstances.

I was asking for a clearer testing strategy, not a better one.

The section currently states

Tested with specific ls commands on my computer in directories with very large numbers of files. In NVDA 2026.1, this lagged for a couple seconds before recovering. Admittedly I need to test this more thoroughly, hence the draft.

Can you provide brief step by step instructions on what you did to test?

Your merging method seems to be problematic. The differences in this PR are very large; please do not use the squash method to merge.

@wmhn1872265132 I mean, okay, if that's what you want...

Is there anything else that is required for this PR? Just checking since I'm pretty sure people are clamoring for this to get merged. :D I hope all the testing has worked out well (it seems to work fantastically for me).

Thanks @ethindp
Could you update the PR description to match the latest changes?

Will do

@cary-rowen All done.

I'm not entirely certain why the system checks are failing. Two of the runs can't find the Chrome window and the third fails with a speech timeout. are they blockers to this getting merged?

Thanks for working on this. Something still doesn't make sense for me here, though. When we use LiveText, we should only be diffing a full screen at maximum, which means, say, 60 lines at an absolute maximum. _reportNewLines is called once for each diff, and since it is queued to the main thread from a background thread, that should mean the main thread naturally yields to input between batches of, say, 60 lines. This leads me to wonder: why was the main thread being blocked such that it couldn't process intervening input? Or was the queue eventually just so backed up that it just couldn't handle input fast enough for the user to perceive it as useful? Regardless, it definitely makes sense to reduce the contention on the main thread, especially as there's no benefit to throwing all of this at the synth if the user is very likely to interrupt it anyway, but it does leave me a little puzzled.

Just in case this helps anyone, another thing I discovered a while back when looking into this is that having logging set to i/o or lower can cause severe lag in this case because each line of speech gets logged and the log is then flushed to disk. This PR should help that too because we're ultimately logging less lines, but the only real solution there is to avoid setting the log level like this if you're doing a lot of spammy terminal stuff.

When we use LiveText, we should only be diffing a full screen at maximum

Not any more: the UIATextRange for Windows Terminal and Conhost points at the entire buffer, not just the visible text. I can't remember exactly why I didn't limit diffing to the visible text (GetVisibleRanges) in UIA now, but I suspect it was to do with issues with the alt buffer or weird behaviour when the window was minimized or maximized.

Yep fairly certain it was alt buffer related, see #12669 and microsoft/terminal#5406.

I can't remember exactly why I didn't limit diffing to the visible text (GetVisibleRanges) in UIA now

That feels like something we should look at fixing, even if we just limit it to the last 100 lines or similar. Diffing that many lines is much more expensive and it's ultimately pointless, since even a sighted user can only perceive what's changing on screen, not what's changing outside of it.

That feels like something we should look at fixing, even if we just limit it to the last 100 lines or similar.

That was done in this PR.

This PR limits what we report, not what we diff. We're still potentially (expensively) calculating diffs which we later throw away.

I'm guessing the calculation of diffs on larger blocks of text is probably also more expensive even if the actual diff is minimal, though I can't substantiate that with any data, so I could be wrong. Still, it might be premature optimisation unless proven otherwise.

This PR limits what we report, not what we diff. We're still potentially (expensively) calculating diffs which we later throw away.

Yes, you're right, and I did try bounding the diff at say the last 100 lines ages ago. (See a quick implementation at the limit-diffs branch of my fork). The problem is that if a large block (say 10,000 lines) is printed, NVDA will drop all but the last 100 at first, but subsequent commands in the session sometimes get stuck reading very old output because DMP doesn't have enough context. I'll see if I can come up with clear repro steps.

Why was the main thread being blocked such that it couldn't process intervening input?

Diffing and such may have been done on a background thread, but the actual line update reporting was not. Instead if you diff against this PR and a commit before it was merged, you'll see that _reportNewLines was literally a for loop that just reported each and every line in sequence until complete. Given that (per back-of-the-napkin-math) each speech.speak function takes maybe 10-50ms, this would lead to thousands upon thousands of updates trying to be synthesized on the main thread. Since no yielding of the thread was done, NVDA would hang until the function had completed and all speech had been synthesized correctly.

this would lead to thousands upon thousands of updates trying to be synthesized on the main thread. Since no yielding of the thread was done

To be more concrete, were you seeing (and still seeing) calls to _reportNewLines where len(lines) > several thousand? If so, UIA consoles are the only consumer that could have caused that, since they diff the entire buffer, where everything else only diffs the screen. We just shouldn't be calling _reportNewLines with that many lines in the first place. 60 maybe, since that's a full screen. Anything larger than that is pointless. Of course, fixing that would involve figuring out how to solve the UIA console diffing problem @codeofdusk notes above.

That said, I'm fairly sure I've heard of complaints about this from folks with the UIA console disabled. That case could not have been sending more than 60 or so lines at a time. There would have been a huge number of calls, but each would have naturally yielded to the queue after 60 lines or so.