DEV Community: Nazarii Ahapevych

An AI agent graded its own poll loop as 'event-driven'. I read the code instead.

Nazarii Ahapevych — Mon, 20 Jul 2026 16:40:23 +0000

Context

downbeat (my tool that passes messages between terminal sessions, github.com/FreddieMcHeart/downbeat) has two ways to keep a session aware of its inbox. One is /relay-monitor: it composes the built-in /loop (re-fire a prompt every N minutes) with the inbox hook, so every tick is a full model turn whether or not new mail arrived. The other showed up on its own. A different session had set up a background "Monitor" and, in its own notes, described it as "event-driven, instant, cheap, only fires on events."

I was asked which approach was better. We already had a rule for evaluating external tools: do not trust the description, read the code. I pointed that rule at the session's own work.

The finding

The self-described "event-driven" monitor was this:

while true; do
  sleep 90
  cur=$(downbeat inbox | grep '^*' | awk '{print $2}' | sort)
  new=$(comm -13 "$seen" <(printf '%s\n' "$cur"))
  [ -n "$new" ] && { echo "NEW MESSAGES"; printf '%s\n' "$cur" > "$seen"; }
done

That is a poll loop. It sleeps 90 seconds, lists the inbox, and diffs against a seen-file. The session had conflated "does not re-arm itself every turn" with "does not poll." It graded itself on the label, not the loop. Its own comparison table claimed instant latency and cost only on events. Reality: up to 90 seconds of latency and about 960 polls a day, traffic or no traffic.

Two things it got right anyway

Reading past the wrong label, two ideas in it were genuinely good.

First, a cheap gate in front of an expensive consumer. On a quiet channel, /relay-monitor spends a full model turn every interval just to read "nothing new." This script's tick is a bash poll, near-free, and it only escalates to a model turn when comm actually finds new mail. Put the cheap check on the hot path and the expensive one on the rare path. That is the real win, whatever you call it. (Exact cost delta: unmeasured. The direction is obvious, I did not benchmark the size.)

Second, persistent state beats re-creation. Its previous version had re-armed a fresh "fire once" watcher every turn, which stacked up overlapping watchers that double-fired. One long-lived process with a seen-set emits each message exactly once. It had quietly re-derived a consumer offset in bash.

The kicker

Here is where it turned into a lesson about my own codebase. downbeat already had a real event-driven watcher: src/downbeat/core/watcher.py, with an FsWatcher built on watchdog (FSEvents on macOS, inotify on Linux) and a PollWatcher fallback for network filesystems, both behind a make_watcher() factory. I had written it months earlier for the TUI's live refresh, and it was sitting unused.

Meanwhile the downbeat watch command I had added more recently (since removed, see the update below) ignored it and rolled its own while sleep loop.

So two independent agents, that other session and my own past self, each re-derived "poll the inbox in a loop" while a tested, event-driven watcher sat one import away.

The fix

Rewire the watch command to use the factory:

w = make_watcher(on_change=emit, prefer="auto")   # FsWatcher, PollWatcher fallback
# --poll forces PollWatcher for NFS/SMB, where FS events are unreliable

Now downbeat watch blocks on filesystem events with near-zero idle cost, and running it under a monitor gives exactly the cheap-gate-then-wake architecture the other session was reaching for. The difference is that the "event-driven" claim is finally true instead of aspirational.

What I took away

Grade a mechanism by its code, not its description. Even when the description is your own, and especially when an AI wrote it. The gap between "what I built" and "what I said I built" is exactly where this bug lived.
Before building a new primitive, check whether you already shipped one. A ten-second grep of my own repo would have prevented two separate reinventions of "poll the inbox."
Cheap predicate, then expensive work. A near-free filesystem check in front of an LLM turn is the pattern that actually mattered here, and it shows up all over the codebase once you go looking for it.

The most valuable output of the whole exercise was not the feature. It was noticing that a tested primitive had been re-derived twice, in plain sight.

Update: the primitive found a better home

Since I wrote this, that FsWatcher got promoted again. It made the standalone watch command this post celebrates redundant. Instead of a user running watch in a loop, the watcher now lives inside the TUI: while the app is open it fires a native OS notification the moment a peer has mail waiting and that peer has been idle too long, with a heartbeat so a headless send-hook and the TUI don't both notify for the same message. The standalone watch subcommand was removed outright.

Which is this article's own lesson, one turn further. The tested primitive I found sitting unused didn't just replace two hand-rolled poll loops. Once it was the obvious building block, the right place to use it turned out not to be the command I first bolted it onto at all.

My AI harness is an external executive function

Nazarii Ahapevych — Fri, 17 Jul 2026 08:14:38 +0000

I built an AI setup to save money on tokens. It turned into the memory and focus my ADHD brain is missing.

TL;DR: A messy AI agent wastes money. A messy ADHD brain wastes effort. The same thing fixes both: external structure. I built it for the agent, then I saw I had built it for myself.

Context

An "agent harness" is the plain layer around an AI coding agent. Mine has four parts:

a CLAUDE.md: a file of rules the agent reads every time it starts
skills: fixed step-by-step routines for tasks I do often
routing and delegation: rules for which model does what, and when to hand a job to a helper agent
file-based memory: notes the agent writes to disk, so it remembers things between sessions

People build this to save money and keep quality steady. An agent with no structure wastes tokens and drifts off task. Structure makes it cheap and steady. That is the whole point of it.

Why these two things match

Here is the part that surprised me.

An AI agent wastes money when it works with no structure. It forgets what it already did. It drifts off the task. It redoes work. It spends effort on the wrong thing. So you give it structure: rules, saved routines, external notes, clear priorities. Now it does not have to decide everything well in the moment. The structure decides for it.

ADHD is the same failure, in a person. Under pressure I forget, I drift, I redo, I focus on the wrong thing. The weak part is my judgment in the moment.

So the structure that makes the agent cheap is the same structure that makes me work. Saving money was only the reason I started. What I really built was executive function, on disk. That is what executive function is: you do not need good judgment in the moment, because the structure already holds it for you.

The map, part by part

CLAUDE.md is memory and a safety net. I take rules seriously and I hold most of them fine. I still back every important one with a hook or a checklist, just in case. My intention is solid. My attention is not. The file does not depend on attention.

Skills are getting started. Starting is the hard part, and it is worst when I already know how to solve the task. My brain marks it as done and refuses to sit down and actually do it. A skill is the same routine every time, so there is no first step to find. It is already written. I follow it.

Routing and delegation are choosing what matters. Picking what to spend effort on is the choice I get wrong when I am overloaded. A rule makes that choice once, calmly, ahead of time.

File-based memory is memory that survives a break. An idea I do not write down dissolves in about half an hour. For years my fix was Telegram messages to myself: voice notes, links, one line about why I saved them. It worked, sort of. Notes the system writes to disk are the same thing, except they come back to me at the right moment, already in context. And an interruption, which before AI was a permanent headache, stopped erasing where I was.

The honest part

I did not plan this as help for my ADHD. I built it to stop wasting money on an agent. But the two problems have the same shape, and that is worth saying out loud. An agent with no structure and an ADHD brain with no structure fail the same way. They forget. They drift. They redo work they already did.

The difference is that the agent gets a config file, and I got a diagnosis. So I gave myself the config file too.

What this changes

Two things.

If a rule keeps failing when you rely on willpower, it does not belong in your head. It belongs in a file, a checklist, a routine, something that holds it for you. That is the same move that makes AI agents work, and no one calls the agent lazy for needing it.

And the setup that looks like "AI slop" from the outside can be the thing that lets someone finish work at all. I wrote before about AI writing as an accessibility tool. That was one piece of it. This is the whole outside brain underneath. This very article worked that way too: I talked in a raw stream, the system built the structure. The small apps I write for myself and the diagrams I sketch start the same way.

If your head works like mine, the question was never whether to use the help. It is which part to move outside first.

Green CI working software

Nazarii Ahapevych — Mon, 13 Jul 2026 19:40:30 +0000

Two green CI runs told me the release worked. Both were no-ops.

A green check means one thing: the job exited 0. That is all it means. It does not tell you the step you cared about actually did the work you think it did. I learned this the slow way, twice in a row, on the same release pipeline.

The setup

I had wired up automated releases with python-semantic-release. The idea is clean: you write conventional commits, the tool reads them, decides the next version, tags it, and pushes. Because the release job has to push a version bump and a changelog back to a protected branch, I gave it a dedicated RELEASE_TOKEN with the rights to do that.

The wiring looked healthy. Push, pipeline runs, green check, move on.

The first no-op

python-semantic-release only cuts a release when the commits since the last tag actually warrant one. Conventional-commit types map to version bumps roughly like this:

Commit type	Release effect
`feat:`	minor bump
`fix:`, `perf:`	patch bump
`docs:`, `ci:`, `chore:`, `style:`, `refactor:`, `test:`	no release

My two green runs landed on a docs: commit and a ci: commit. python-semantic-release looked at them, decided there was nothing to release, and short-circuited. It exited 0 well before it ever reached the push path. The RELEASE_TOKEN, the protected-branch push, the tag, none of it ran. The job was green because it correctly did nothing.

So the part of the pipeline I most wanted to verify, that the token worked and the push to the protected branch succeeded, stayed untested. It stayed pending until the next feat: or fix: commit came along and gave the tool an actual reason to reach that code. The green check told me the release worked. What it meant was "there was nothing to release, so I stopped early."

The second no-op

The same pipeline had a build_command that produced build artifacts before the release. The bug was subtle: build_command runs your command, but it does not automatically stage the output that command produces. If your release step then commits and pushes, the artifacts the build just generated are not in that commit unless you stage them yourself.

Every per-task run went green. The build command exited 0. The release step exited 0. Nothing in a single job's view was wrong. The gap only became visible at a whole-branch review, looking at the actual diff that would ship, where the missing artifacts stood out against everything else.

What a green check actually is

Both failures share one root. A check reports the exit code of the command you told it to run. It cannot report the thing you assumed that command would do. Coverage is not correctness. A pipeline verifies the paths you encoded, on the inputs you happened to feed it. The path that breaks is usually the one that never got exercised: the integration you mocked, the config that only exists in prod, the branch of logic that this particular commit did not trigger.

"All checks passed" and "the release works" are two different statements. The pipeline can only ever prove the first one.

What I check now

I read the log, not the badge. Before I trust a green release, I confirm the specific path ran:

Did the version actually bump, or did the tool decide there was nothing to release?
Did the push to the protected branch happen, with the token, on this run?
Did the staged diff contain the artifacts the build produced?

Concretely:

Assert the effect, not the exit code. If a job is supposed to push a tag, have something downstream check the tag exists. Exit 0 is necessary, it is not sufficient.
Force the real path in a test. A release dry-run on a synthetic feat: commit exercises the push path even when today's real commits would not. Then you learn the token works before you need it.
Keep whole-branch review. Per-task green catches a lot. The staging gap and the no-op release both survived every per-task check and only showed up when someone looked at the whole branch as one diff. That review is not redundant with CI. It catches the class of bug CI structurally cannot see.

None of this means the pipeline is useless. It means a green check is where the checking begins.

Has a green run ever lied to you like this?

downbeat: stop copy-pasting between your AI terminals

Nazarii Ahapevych — Thu, 09 Jul 2026 07:26:47 +0000

Context

I run more than one AI coding session at a time (Claude Code, in my case). One is usually the planner: it holds the architecture, decides what to do, splits the work. The others are executors, and each takes a chunk and grinds through it.

The problem is that these sessions cannot talk to each other. Every terminal is its own island, so I became the message bus. I copied a plan out of the planning session and pasted it into an executor. I copied the result back. I re-explained context that one session had and another needed. Every handoff went through me, by hand, one clipboard trip at a time.

TL;DR: downbeat is a small, local, human-in-the-loop message bus that lets parallel AI coding sessions on one machine hand tasks to each other and read the replies back. No cloud, no account, no network. It is on PyPI now: uv tool install downbeat.

I was the message bus, and it fell apart at four sessions

Two sessions and a clipboard works fine. Four sessions is chaos. I lost track of which executor had which version of the plan, I pasted stale context, and I spent more attention shuttling text between terminals than on the actual work.

I wanted the sessions to pass messages directly, on my machine, with me still in the loop but no longer doing the typing. No cloud service, nothing leaving the terminal.

What downbeat is

downbeat is a local, filesystem-backed message broker for AI coding sessions running on the same machine. A CLI, a terminal UI, and a bundled agent skill. No server, no account, no network.

The model is simple:

Each session registers as a named peer (a "parent" planner, a "child" executor, whatever role you give it).
One session sends a message to another: a task, a plan, a chunk of context, a result.
The recipient sees that message surfaced at the start of its next turn, through a hook. It just appears.
Replies flow back the same way, so a child can report "done" to its parent without you touching the clipboard.

The part I care about most: nothing auto-executes. Every watcher notifies you, nothing runs on the parent side on its own, and a child only acts because you told it to at registration time. Human-in-the-loop is the default you would have to work to turn off.

Underneath, a message is a JSON file in the recipient's inbox directory. That is the whole transport. It turns out you can build a surprisingly capable little queue out of a directory and a hook.

Install

The whole runtime installs in two commands:

uv tool install downbeat     # or: pipx install downbeat
downbeat init                # one command installs the WHOLE runtime

downbeat init is the single source of truth for the setup. It bootstraps the data dirs, installs the agent skill, drops the bundled hooks and slash commands, and registers the hooks in your settings idempotently (backed up, atomic, and it never clobbers hooks you already have). It is safe to re-run.

Then the loop itself:

downbeat register parent --role parent
downbeat register child  --role child
downbeat send child "task" "do the thing"
downbeat inbox --peer child
downbeat reply <msg_id> "done"
downbeat tui                 # full management UI

If you want to see it before installing anything, the repo has a five-command walkthrough in examples/parent-child-handoff/ with a recorded demo.

Why I built it this way

Two constraints shaped it.

It had to be local and dependency-free. My sessions already run on one laptop. Reaching for Kafka or a hosted queue to pass a sentence between two terminals is absurd. The filesystem is already there, it is already durable, and a rename is already atomic.

It had to be reliable enough to trust. Early on it was fire-and-forget, and it quietly lost messages: a file got marked handled the instant it was read, even if the session never acted on it. So it grew a proper delivery state machine (delivered, then acknowledged, with anything unconfirmed re-queued instead of dropped), a TUI to watch the traffic, session identity that survives a /clear, and an event-driven file watcher so it reacts instantly instead of polling.

None of that was planned up front. It started as a hack to stop copy-pasting, and each rough edge I hit in daily use turned into the next piece.

Who it might help

If you drive more than one AI coding session at once, or you have ever found yourself relaying instructions between terminals by hand, this is for that. It is deliberately small and single-machine. It does one thing: let sessions on your box hand work to each other and report back, with you still holding the wheel.

I am open-sourcing it because it became genuinely useful to me and it might help someone with the same workflow. It is early and opinionated. Issues, ideas, and "why on earth did you do it this way" questions are all welcome.

Repo: github.com/FreddieMcHeart/downbeat
PyPI: pypi.org/project/downbeat
Docs: freddiemcheart.github.io/downbeat

What's next

The interesting parts to build were the ones I did not expect. Over the next few posts I want to dig into a handful of them:

the two-phase delivery that stopped the silent message loss, and the backlog it exposed
an event-driven file watcher I had already written months earlier and completely forgotten, until two separate agents each reinvented polling next to it
giving a process a stable identity that survives /clear

If any of that sounds familiar from your own tools, I would like to hear how you solved it.

What looks like AI slop from the outside is my accessibility tool

Nazarii Ahapevych — Mon, 06 Jul 2026 15:16:55 +0000

Context

I have ADHD, and I write with AI. Those two facts are connected, and this piece is about how. Not "AI helped me polish this." The article you're reading did not exist as a finished thing until an AI sat down with me and built the structure around it. The usual word for that from the outside is slop, or, aimed specifically at people like me, neuroslop.

TL;DR: My ADHD means some tasks, like turning a scattered thought into a finished piece of writing, put a specific strain on exactly the resource I'm short on. AI tools remove that barrier. For a neurotypical writer they're a convenience. For me they're the reason a thought becomes a shipped piece of work instead of a fragment in a notes app forever. Same tool, completely different stakes.

Slop to you, accessibility to me

The slop criticism is usually fair. A lot of AI-assisted writing really is low-effort output nobody reviewed, produced because it was easy to produce. I'm not arguing against that criticism in general, most of what gets called AI slop earns the label.

But the label carries a hidden assumption: that the person could have written the piece themselves, just a bit slower. That assumption doesn't hold for me. The barrier was never knowing what to say. It was the blank page itself, and the executive-function cost of turning a scattered mental state into the first three bullet points that make a piece of writing exist. That cost isn't there for everyone in the same way, and it doesn't scale down with "try harder." It's the same shape as needing glasses to read fine print: fine for most of the day, and a hard wall the moment the task demands exactly the thing you can't do unaided.

The point is narrow: some tasks put a specific, predictable strain on exactly the resource ADHD affects, and a tool that corrects for that strain is doing accessibility work whether or not anyone calls it that.

Three things this actually looks like

Not an abstract claim. Here's what it looks like in practice:

Structuring from zero. I hand over a mess, and get back a skeleton I can build on. The blank page was the wall; the skeleton is the door.
Finishing what attention broke. A thought gets interrupted halfway through, the way thoughts do, and instead of staying a half-sentence in a drafts folder forever, it gets picked back up and completed.
Turning raw stream-of-consciousness into structure. A chaotic voice note or a wall of unpunctuated thinking goes in, and something readable comes out the other side, without losing what I actually meant.

None of these are about the AI being smarter than me. They're about the AI correcting the exact point where my own process used to fail.

It's bigger than writing

This isn't only about articles. The same pattern shows up across how I work: writing code, getting through a work task, turning a half-formed idea into something that actually ships. In every one of those, the AI is functioning less like a tool and more like an extended working memory, the extra context I can't hold onto myself. I haven't measured this rigorously across those areas the way this project measured the reading-side research (see the neuroinclusive writing checklist built for this same content pipeline). The pattern is consistent enough across code, work, and writing that I'm confident it isn't a writing-specific quirk.

Why the slop label sticks right now

Right now, anything tagged AI-generated gets treated as slop by default. That reflex says more about where we are than about what the tool is. Two kinds of literacy are still immature: creators who reach for the tool without doing the thinking it still requires, and readers who haven't yet built the pattern-matching to tell that apart from someone using the same tool to get a real thought past a real barrier. Both sides are new at this. The label is a snapshot of an early, poorly-understood moment, not a fixed property of the output.

The honest part I won't dress up

The AI drafts real sentences. Whole paragraphs, including ones in this article. Pretending it only "helps with structure" while I supposedly write every word myself would be its own kind of slop, a lie about how the thing actually got made.

So here's the real division of labor. The AI is fast hands. What makes the piece mine is everything around the drafting: the direction, the judgment about what's true and what's off, and the dozen rounds of "no, that's not what I meant" that reshape a draft until it says the thing I actually think. This exact article went through that, more times than I'd like to admit. The argument is mine. The calls about what stays and what's wrong are mine. The typing, increasingly, isn't, and I've stopped thinking that's the part that mattered.

There's a meme I like: a boss riding in a cart, a leader pulling one alongside the team, an introvert dragging the cart alone, and then "ADHD introvert with AI" flying a fighter jet. It's a joke, but it lands for a reason. I'm not pretending I'm running on foot next to everyone else. I'm flying something. Flying is still a skill. It's just a different one than running.

The close

Call it neuroslop if you want. What reads as low-effort from the outside was, for me, the thing that got a real thought out of my head and onto the page at all. A barrier removed, by someone who did the part that was actually mine to do.

Your AI coding agent gets expensive one reasonable decision at a time

Nazarii Ahapevych — Thu, 02 Jul 2026 11:28:15 +0000

The setup

Agentic coding tools are astonishingly capable, and astonishingly easy to run expensively. I learned this by watching my own bill, not by doing anything obviously wasteful. There was no single dumb move. The cost came from a thousand small, reasonable-feeling decisions, each of which looked free at the time.

This is the first post in a short series about the structure I built to stop that. Before the fixes, it is worth being precise about where the money actually goes, because most of it hides in places that feel light-touch.

Where an agent bleeds tokens

Five patterns account for most of it.

Main-agent tokens are the most expensive tokens in the session. Every file the top-level agent reads itself stays resident in its context, and that context is re-billed on every subsequent turn. A file you read once is a file you keep paying for until the session ends. The top-level agent's attention is the premium seat, and it is easy to fill it with work a cheaper agent should have handled.

"Just one more peek." You read three files to build a mental model, then a fourth to be sure, then a fifth. Each one feels free. None of them is. This is the pattern I catch myself in most, because every individual read is defensible and the total is the problem.

The wrong model for the job. Running a structural ls, a grep, or a "find where X is defined" on a frontier model, when a cheap model returns the same answer at a fraction of the price. A structural lookup has a right answer that does not need a genius to produce.

Long output in the main thread. Emitting a 5,000-word writeup from the main agent, instead of having a cheap sub-agent write it to a file and hand back a pointer. The main agent should decide and delegate, not type essays into its own expensive context.

Context bloat compounds. This is the one that hurts, because it is silent. The prefix cost of a bloated session is paid again on every single turn. It does not reset until you clear. A session that got fat an hour ago is still charging you rent on that fat right now.

The insight

Look at that list again. Not one of those decisions feels expensive in the moment. Reading one more file is reasonable. Using the good model is reasonable. Writing the answer inline is reasonable. The expensive patterns are exactly the ones that feel light-touch when you make them.

That is why "just be more careful" fails. You cannot out-discipline a bias that only shows up in aggregate, one defensible decision at a time. In-the-moment judgment is the exact thing that breaks here. What you need instead is structure: something outside the moment that notices the pattern and interrupts it.

What the series covers

So I built that structure, and it turned into a small set of pieces, each with one job:

a hook that runs on every tool call and enforces spending discipline the way a linter enforces style
a model router that picks the tier before acting, plus a delegation rule that scouts cheaply before spending on the expensive agent
a parent-and-children setup where a lean planner coordinates fresh-context workers
and the work of turning all of it from "works on my machine" into something installable

The next posts go through each.

One result is worth stating up front, because it is the part I did not expect. The discipline did not trade cost against quality. It improved both. The same moves that cut the token bill (delegate the bulk reads, route the right model, keep the main agent's context clean) are the moves that keep the agent focused and correct. Cheaper and better turned out to be the same lever. The rest of the series is me earning that claim.

[type='CNAME'] crashed my Textual TUI: why escaping user text isn't enough

Nazarii Ahapevych — Sun, 28 Jun 2026 18:01:06 +0000

The setup

I have been building a small tool called claude-relay. It passes messages between terminal sessions running on the same machine: one session finishes a piece of work, sends a short message, another session picks it up. Think of it as a tiny local message queue with a chat-style front end.

That front end is a terminal UI built with Textual and Rich. It lists incoming messages and renders the selected one as a chat bubble. The catch is that the message bodies are not clean strings I wrote. They are whatever a session decided to send: shell output, stack traces, Terraform plans, ticket IDs. The TUI has to render arbitrary text from outside my control. That is the detail that turned out to matter.

The crash

One day a message arrived with a Terraform error in the body. I selected it, and the entire UI died:

MarkupError: Expected markup value (found "='CNAME'] but it already exists]\n").

The text that triggered it was completely ordinary:

Error: [type='CNAME'] but it already exists

A bracketed token inside an error message. Harmless in a log file. But Textual and Rich treat square brackets as markup, so that one message took down the whole interface. Worse, any message containing brackets would do the same, and brackets are everywhere in developer output: ticket tags, type hints, array syntax, that Terraform error. The tool was unusable the moment real data flowed through it.

Why a bracket is a bomb

Rich uses [...] for inline styling: [b]bold[/b], [dim]quiet[/dim], [red]alert[/red]. Textual renders on top of Rich, so any string you hand to a widget's update() runs through that markup parser first.

My message bubble was built the obvious way:

child.update(f"[b]{direction}[/b]\n{msg.body}")

When msg.body contains [type='CNAME'], the parser sees a tag named type='CNAME', cannot make sense of it, and throws. The fix looked trivial. It took four commits and three wrong turns to actually get right.

Wrong turn 1: escape the user content

The textbook move is to escape anything that came from outside, and Rich ships rich.markup.escape() for exactly this. I wrapped every user-supplied field in it (from_peer, to_peer, subject, body) across eight files.

It still crashed.

The reason took a while to surface. Textual 8.x no longer renders through Rich's markup tokeniser. It has its own visualize path, and that path does not honour Rich's backslash-escape convention. escape() dutifully turned [ into \[, and Textual's parser choked anyway. Escaping is parser-specific: an escape that satisfies one tokeniser means nothing to another.

Wrong turn 2: my own template had brackets in it

While chasing the user content, I missed that I had planted brackets myself. My truncation suffix read:

"\n[dim]…[truncated, press Enter to view full][/dim]"

[truncated, press Enter to view full] is a bracketed phrase sitting inside [dim]...[/dim]. The parser reads it as a nested tag. The call was crashing on a string I wrote, not on any user data. Swapping the inner brackets for parentheses fixed that case:

"\n[dim](truncated, press Enter to view full)[/dim]"

The lesson I keep relearning: the parser parses your templates too, not only the data you pour into them.

The fix that holds: never let the parser see user text

Here is the actual answer, stated plainly. Stop mixing the two worlds. Parse markup only for the parts you control, and append everything from outside as literal text that never reaches the parser.

In practice that means building a rich.text.Text object instead of a markup string. Static.update() accepts a Text renderable and prints it as-is:

rendered = Text.from_markup(header)   # only the parts WE control
rendered.append("\n")
rendered.append(body_text)            # user content, literal: parser never sees it
child.update(rendered)

Brackets in the body now render as brackets, because the body is never parsed as markup at all.

Wrong turn 3: even Text composition has a trap

I applied the same idea to the message-detail view and it crashed again:

MarkupError: closing tag '[/b]' doesn't match any open tag

I had built the title as a chain of from_markup calls:

# each from_markup() parses on its own, so the lone [/b] has nothing to close
title = Text.from_markup("[b]")
title.append(subject)
title.append_text(Text.from_markup("[/b] ..."))

Text.from_markup() is a parser, not a concatenator. Each call parses independently, so a dangling [/b] in a later call has no matching open tag. The fix is to drop markup syntax for programmatic styling and use the API directly:

title = Text()
title.append(subject, style="bold")
title.append(f"   ({msg.state.value})", style="dim")

No parser involved. No way to crash.

Where it landed

After those four commits the TUI renders arbitrary message bodies cleanly. The rule I walked away with is simple: markup syntax is a template language, and the programmatic Text API is for code. The moment you split [b]...[/b] across function calls or interpolate a variable into a markup string, you are writing code, so take the code path. Markup strings are safe only for fully self-contained, balanced literals: a fixed help line, a status glyph like [yellow]●[/yellow].

One more thing that made this hard to catch: these bugs hide from your tests. Textual's run_test(headless=True) renders to a virtual screen that does not exercise the same path as a real terminal launch. Every one of these crashes appeared only when I ran the real app against real data. My regression tests now feed the renderer the genuinely nasty inputs on purpose: [type='CNAME'], [ABC-1234], list[int], a markdown link.

It is the same discipline as escaping on output in HTML. Trust no string with brackets that came from outside your code, and remember the parser is just as happy to choke on a bracket you wrote yourself.