Herddeck on Nick Liu - Software Engineer

The context percentage is a division. Nothing tells you the denominator.

nickboy@users.noreply.github.com (Nick Liu) — Mon, 07 Sep 2026 00:00:00 +0000

Showing "this session is 34% full" requires two numbers. The token count is easy and always right. The window size it divides by is not in the transcript, not in the session state files, not in settings, and not in any hook payload. It exists in exactly one place, and if you cannot read that place you are guessing at the denominator of a number you are about to display as fact.

Tested with Claude Code 2.1.x · macOS

I built a script that reports how full a Claude Code session’s context window is, so a Stream Deck key could draw a ring for it. The token side was straightforward. The denominator turned into the whole project.

Five places the window size is not
#

I checked each of these against a live session rather than reasoning about what ought to be there.

Source	Has the window size?
statusline payload	yes, as `context_window.context_window_size`
transcript `.jsonl`	no. `message.model` drops the `[1m]` long-context marker
`~/.claude/sessions/<pid>.json`	no
`~/.claude/settings.json`	only the default model, which is wrong after a `/model` switch
hook payloads	no, and the hooks documentation says so

The transcript row is the one that stings, because the transcript is otherwise a perfect source: it is on disk, Claude Code writes it without being asked, and reading it changes nothing. It carries message.model. What it does not carry is whether that session is running the long-context variant, because the marker is dropped from the model string it records.

The transcript can tell you which model. It can never tell you which window.

Why I rejected a model-to-window lookup table
#

The obvious fix is a table: model name in, window size out. I decided against it, and not because tables are inelegant.

A lookup table rots on every model release, and it rots in the bad direction. It does not throw. It does not warn. A model it has never heard of falls through to whatever default the author picked, and the tool goes on confidently reporting a percentage computed against the wrong denominator. Being silently wrong about a percentage is worse than showing nothing, because a number on a screen gets read as a measurement.

There is a real API answer here and it is worth stating precisely, because it is almost the fix. Anthropic’s Models API returns max_input_tokens per model id: machine-readable, and it does not rot. What it cannot do is disambiguate a variant that is not a distinct model id. [1m] is a session-level marker rather than something you can look up, and it is the exact thing the transcript drops. So you would be querying the right API with a key that has already lost the distinction you care about, and getting a confident answer to a question you did not ask.

What the script does instead
#

One assumption, named, in one place, with an override and a clamp:

# The one assumption in this script. Not a model->window table on purpose:
# such a table rots on every model release, and being silently wrong about
# a percentage is worse than not showing one.
CONTEXT_WINDOW_TOKENS = int(os.environ.get("HERDDECK_CONTEXT_WINDOW") or 1_000_000)

Three properties of that shape matter more than the value itself.

It is one constant rather than a table, so there is exactly one thing to be wrong about and one thing to change. It takes an environment override, so a machine running a different window fixes itself without a code change. And the overrun clamps:

pct = min(100, max(0, tokens * 100 // CONTEXT_WINDOW_TOKENS))

That clamp does real work. Without it, a session in a larger window than the constant assumes draws a ring at 216%, which is less a display bug than a confession. Clamping to 100 turns “my assumption is wrong” into “this session is full”, which is at least the right shape of wrong.

The deeper point is that only the final division depends on the guess. The token count, which is what the script actually derives from the transcript, is always correct. Show tokens and you are reporting. Show a percentage and you are asserting.

Two routes, and why both exist
#

There are two ways to get this number and they are not equivalent:

	statusline	transcript scan
Percentage	exact, computed by Claude Code	needs the window constant
Coverage	every session	needed two fallbacks to match
Cost	none	one polling process
Requires	editing that machine’s statusline	nothing

The statusline route wins wherever the statusline is yours to edit, because Claude Code resolves the window itself and hands over an already-computed used_percentage. Reading a number somebody else computed correctly is the only approach here that cannot rot.

The scan exists for machines where the statusline is not yours. A company-managed statusline you must not touch is a real constraint, and the scan reads only files Claude Code already writes while changing nothing in anyone’s configuration.

Running both against four live sessions
#

Agreement between two independent routes is the only verification available when there is no ground truth to check against, so I ran them side by side. Three sessions agreed exactly: 34/34, 43/43, 16/16. The fourth converged once its turn completed.

Getting there took two fixes that only live data surfaced.

One pane out of four had no session id. herdr resolved three of four Claude panes and the fourth came back with agent_session: null. The fix needed no configuration: claude agents --json maps pid to session id, and herdr already knows each pane’s processes, so joining the two closes the gap.

That same pane was rate-limited, and its transcript lied. A rate-limited session’s transcript ends in <synthetic> records flagged isApiErrorMessage, carrying all-zero usage. Six of them in a row, in this case.

Read the newest usage record blindly and you get 0% for a session actually sitting at 34%. Not a small error, and not a random one. It always reports empty, and it reports empty exactly when the session is in trouble, which is when you are most likely to be looking at the key. “Use the newest record” is a reasonable-sounding heuristic that happens to select for the records carrying no information.

The fix is to skip records flagged as API errors while scanning backwards for the last real usage figure. Obvious once you have seen it, invisible until a session gets rate-limited while you happen to be watching.

Lessons
#

A percentage is a division, and the denominator deserves as much scrutiny as the numerator. Report the number you measured; you are only asserting the one you derived.
Prefer one named constant to a lookup table when neither is discoverable. A table rots per release and keeps answering; a constant is one thing to be wrong about and one thing to fix.
Clamp derived percentages at both ends. A 216% ring is your assumption failing in public, and the clamp converts it into the least-wrong reading available.
A machine-readable API answer is only useful if your key is unambiguous. Per-model context windows do not help when the field you hold has already dropped the variant marker.
When two independent routes to a number exist, run both against live data and compare. Exact agreement on three sessions surfaced two bugs neither route would have revealed alone.
Read the flags on a record before trusting its contents. Synthetic error records with zero usage will cheerfully answer “0%” for a session at 34%, and they show up precisely when things are going wrong.

References
#

Claude Code statusline docs, the payload carrying context_window.context_window_size: https://code.claude.com/docs/en/statusline
Claude Code hooks reference, on what hook payloads carry: https://code.claude.com/docs/en/hooks
Anthropic models overview, per-model context windows: https://platform.claude.com/docs/en/about-claude/models/overview
The statusline side channel this builds on: The Claude Code statusline is a per-turn telemetry side channel
The ring this feeds: Every context ring read 10%. Two bugs, and fixing one hid the other.
herddeck-ctx-scan, the transcript scanner: https://github.com/nickboy/herddeck/blob/main/scripts/herddeck-ctx-scan

launchctl bootout returned 0. The label was still there. Bootstrap failed 5.

nickboy@users.noreply.github.com (Nick Liu) — Sat, 05 Sep 2026 00:00:00 +0000

`launchctl bootout` exited 0. `launchctl bootstrap`, on the very next line, failed with `Bootstrap failed: 5: Input/output error` because the label was still loaded. Then the bootout finished on its own schedule and the label went away, leaving a machine with no daemon at all and an installer that had just told me it was done. This one is mine: I caused it while fixing something else.

Tested with launchd · macOS

I have written before about launchctl unload returning 0 while the daemon kept running, which turned out to be KeepAlive’s supervisor racing the teardown. This is the sibling. Same API, opposite failure, and where that one was launchd surprising me, this one I built myself.

The idempotency fix that caused it
#

herddeck install should be re-runnable. You edit a config, you run install again, you expect it to work. That is table stakes for an installer.

launchd disagrees. Bootstrapping a label that is already loaded is an error, so a second install would print something like this and stop:

Bootstrap failed: 5: Input/output error

Errno 5 is EIO, which launchd reuses as a catch-all for “I refuse”. In this case it means “already loaded”, which is a perfectly harmless condition: the daemon you wanted running is running.

So I did the obvious thing. Boot it out first, then bootstrap. Now install is idempotent.

What `bootout` actually returns
#

launchctl bootout returns as soon as launchd has accepted the request. It does not wait for the job to be torn down, the processes to exit, or the label to leave launchd’s tables.

The sequence I created:

The bootstrap fails against a label that is on its way out. Then the bootout completes. The net result is that nothing is loaded, which is the one outcome neither command asked for.

Why the failure is silent
#

The old behaviour was a loud error in a harmless situation. The new behaviour is a quiet error in a broken one, and the asymmetry is the whole lesson.

If you run install twice in a row, the second run prints its bootstrap failure and you have a running daemon anyway, because the bootout raced and lost. If you run it once after an upgrade, you may get a bootout that wins, a bootstrap that fails, and no daemon. The daemon does not crash. It was never started. There is no crash log, no KeepAlive respawn, and nothing in launchctl list to look at, because the label is genuinely gone.

The symptom is that HerdDeck simply stops existing until you run install a second time, which of course works, because now there is nothing to boot out. A bug that is fixed by doing the thing again is a bug that hides for a long time.

The fix: poll, then retry, both bounded
#

The correct move is to stop trusting the return code and ask launchd directly whether the label is still there.

/** Poll interval and cap while waiting for `launchctl bootout` to
 * actually finish, plus how many times to retry a bootstrap that fails
 * anyway. 20 x 100ms is far beyond the observed settle time and still
 * bounded at 2s. */
const UNLOAD_WAIT_MS = 100;
const UNLOAD_WAIT_ATTEMPTS = 20;
const BOOTSTRAP_RETRIES = 2;

launchctl print gui/<uid>/<label> exits non-zero once the label is really gone, which makes it a usable predicate:

const isLoaded = async (): Promise<boolean> =>
 (await opts.exec("launchctl", ["print", `gui/${opts.uid}/${LAUNCHD_LABEL}`])).exitCode === 0;

const alreadyLoaded = await isLoaded();
if (alreadyLoaded) {
 await opts.exec("launchctl", ["bootout", `gui/${opts.uid}/${LAUNCHD_LABEL}`]);
 for (let i = 0; i < UNLOAD_WAIT_ATTEMPTS && (await isLoaded()); i++) {
 await sleep(UNLOAD_WAIT_MS);
 }
}

let res = await opts.exec("launchctl", ["bootstrap", `gui/${opts.uid}`, plistPath]);
for (let i = 0; i < BOOTSTRAP_RETRIES && res.exitCode !== 0; i++) {
 await sleep(UNLOAD_WAIT_MS);
 res = await opts.exec("launchctl", ["bootstrap", `gui/${opts.uid}`, plistPath]);
}

Both loops are bounded, and that matters more than the polling. The wait caps at two seconds, far past anything I measured. The bootstrap retries twice and then surfaces its error like it always did. A genuinely broken launchd, a malformed plist, a permissions problem, all still fail loudly. What the bounds buy is that a slow unload no longer looks like a broken install, and a broken install still looks broken.

The test that pins it is named for the outcome rather than the mechanism: “waits out an async bootout instead of leaving nothing loaded”. If someone later decides the polling loop is superstition, the test name tells them what breaks.

The pattern, and its sibling
#

Put the two launchd posts next to each other and they are the same shape from opposite sides.

	Earlier post	This post
Command	`launchctl unload` / `bootout`	`launchctl bootout`
Returned	0	0
Reality	job unloaded, process still running	request accepted, label still loaded
Consequence	orphaned daemon holding a port	nothing running at all
Cause	KeepAlive respawn racing the teardown	teardown not finished when the call returns

In both cases the exit code is honest about what the command did and silent about what launchd had not finished doing yet. launchctl reports on the request, not on the world.

And in both cases the fix is the same in outline: after asking launchd to change something, verify the change independently, with a bound. pgrep in one direction, launchctl print in the other.

Lessons
#

launchctl bootout returns when launchd accepts the request, not when the job is gone. The exit code describes the request, not the world.
Adding a safety can convert a loud harmless failure into a silent harmful one. “Bootstrap refused because it is already loaded” was noisy and fine. “Nothing is loaded” is quiet and broken.
Suspect any bug that goes away when you run the command a second time. That shape is a race, and running it twice is not a workaround, it is the reproduction.
launchctl print gui/<uid>/<label> is the predicate you want. Its exit code answers “is this label loaded right now”, which is the question bootout will not answer for you.
Bound the poll and bound the retry. Unbounded waiting turns a broken plist into a hang, and the whole value of the fix is that real failures still fail.
Name the test after the outcome, not the mechanism. “Waits out an async bootout instead of leaving nothing loaded” survives a refactor that deletes the loop.

References
#

launchctl(1) and launchd.plist(5) man pages. Accurate about verbs, silent about lifecycle ordering, which is the part that bites
The sibling failure on the same API: launchctl unload returned 0. The daemon was still running. KeepAlive raced.
The project this installer belongs to: I deleted six subsystems by swapping one dependency.
HerdDeck installer, the bootout wait and bootstrap retry: packages/cli/src/herddeck.ts

The tunnel was up. The socket existed. Nothing was on the other end.

nickboy@users.noreply.github.com (Nick Liu) — Thu, 03 Sep 2026 00:00:00 +0000

The daemon reported the tunnel as established. The local socket file was right there on disk with the right permissions. The target sat at `offline` forever. Meanwhile `connect to /home/nick/.config/herdr/sessions/main/herdr.sock port 0 failed` was being written to a stderr stream that nothing in my process ever read, several times a second, for as long as I left it running.

Tested with herdr 0.8.0 · macOS

HerdDeck drives agents on a second machine. My laptop has the Stream Deck and the daemon; the desktop runs herdr and the agents actually doing work. They are joined by ssh -N -L <local.sock>:<remote.sock> host, a Unix-domain socket forward, and the daemon speaks the same protocol to a forwarded socket as it does to a local one.

That symmetry is the entire reason remote support was cheap. It is also what made this bug possible, because “I have a socket” is a much weaker statement than it looks.

`ssh -L` binds before it connects
#

A local forward binds the listening end immediately. It does not, and cannot, verify that anything is listening on the far side, because nothing tries to reach the far side until you open a connection through it.

So the moment ssh -N -L starts, you have a socket file. It is a real socket. You can connect() to it. And when you do, ssh opens a channel, asks the remote sshd to reach the target path, the remote sshd fails, and ssh writes a message about it to its stderr and closes your channel.

My daemon’s definition of “established” was the existence of that file.

Every failure mode on the far side therefore looked identical and looked fine. Remote herdr not running: tunnel up, target offline. Wrong absolute path in the config: tunnel up, target offline. Session socket not created because that named session had never been started on the remote: tunnel up, target offline.

Three different problems, one symptom, and the symptom actively pointed away from the cause, because the tunnel was the part reporting healthy.

The error was there the whole time
#

The failures are asynchronous. ssh does not fail at spawn; it fails per channel, later, on stderr. I was reading stderr during spawn to catch startup errors, then dropping the stream on the floor once the process was up.

Everything the debugger needed was in the part I stopped reading.

Two changes. First, stderr is drained for the tunnel’s entire lifetime into a small per-target ring buffer, capped, so a chatty failure cannot grow without bound and the last few dozen lines are always available for diagnostics. Second, and more important, establishing a tunnel now ends by proving it:

bind local socket -> ping-probe THROUGH the socket -> declare established

The probe is a real protocol ping through the forwarded socket with a 4-second timeout. If it fails, the tunnel is not established, regardless of what the filesystem says, and the failure joins the retry path with the stderr tail attached to the error.

The observable difference is the whole point. Before: tunnel green, target offline indefinitely, zero clues. After: it fails within seconds with channel 1: open failed: connect failed and the full -L path mapping in the log, which names the wrong path directly.

ControlMaster pollution, in both directions
#

This one I would never have found by reading code, because the bug lived in the interaction between correct code and my personal SSH config.

Most developers have ControlMaster auto set. It multiplexes SSH sessions to the same host over one connection, which is why your second ssh to a box you are already on connects instantly. It is a good default and I have had it on for years.

A long-lived tunnel joining that multiplexing arrangement fails in two directions, and the second is nastier.

Direction one: the tunnel dies when an unrelated master connection closes, or when its ControlPersist timer expires. Your daemon’s connectivity is now coupled to whether you happen to have a terminal open.

Direction two: if the tunnel gets there first, it becomes the master. Every subsequent interactive ssh to that host attaches to a connection owned by a background daemon. Restart the daemon and you drop the shells of anyone attached to it.

The fix is to refuse to participate:

// Own the connection lifecycle: with the user's ControlMaster
// auto config the tunnel would otherwise mux onto (or become) a
// shared master and its forward would die with that master's
// ControlPersist timer (found live in Tier-1 testing).
"-o", "ControlMaster=no",
"-o", "ControlPath=none",
"-o", "ExitOnForwardFailure=yes",

A tunnel must own its connection. Borrowing one couples its lifetime to something the daemon does not control and cannot observe.

Not every failure deserves a retry
#

launchd starts the daemon at login, which on a laptop means before Wi-Fi has associated and well before a VPN is up. The first tunnel attempt fails, and in the original code that failure was permanent until I restarted the daemon by hand.

Retrying everything is the wrong correction. Retrying a wrong passphrase forever is how you get an account locked out, and retrying a host-key mismatch forever is how you sit in a loop ignoring a security warning. So failures get classified by what ssh said:

ssh stderr contains	Class	Behaviour
`Permission denied`	permanent	no retry, surfaced as `auth`
`Host key verification failed`	permanent	no retry, surfaced as `auth`
`Bad configuration`	permanent	no retry
`Bad owner or permissions`	permanent	no retry
everything else	transient	capped jittered retry, 15s to 10min

Connection refused, timeout, network unreachable and DNS resolution failures all default to transient, and DNS is the interesting one. Could not resolve hostname looks permanent and is completely ambiguous under a VPN that has not come up yet. The default is to retry, because the cost of retrying a genuinely dead hostname is a log line every ten minutes, and the cost of not retrying is a daemon that is dead until you notice.

The loud error fires once per target rather than once per retry, which is the difference between a diagnostic and a log flood.

localhost is a valid far side
#

The technique that made most of this testable, and the part I would steal if I were reading someone else’s post:

“Remote” here means the far side of an ssh streamlocal forward. It does not mean “a different machine”. Point the forward at localhost and you get a genuine SSH forward, with a genuine remote sshd, a genuine second herdr socket path, and genuine channel-open failures, on one laptop with no second machine and no network.

Wrong path, remote daemon down, socket missing, sshd refusing connections, first-connect-before-network: all of those reproduce against sshd on localhost. Only latency and actual link loss need real hardware.

One caveat about `--remote`, because the obvious guess is wrong
#

herdr has a --remote flag and it does not do what you would assume from the outside.

It makes the human terminal experience a thin client. It does not expose a local API socket that proxies the remote server. The local herdr-client.sock is a TUI attach endpoint, so a daemon cannot piggyback on it and needs its own forward.

There is a consequence to that which bit me later. herdr auto-syncs versions between client and server, and that sync fires on a human --remote attach. It never fires for the daemon’s forward. So a machine you rarely attach to by hand can quietly drift to an older protocol while the daemon happily keeps talking to it. Every target is therefore pinged and version-checked on connect and degraded to a warning state on mismatch, rather than assumed compatible.

When not to guess
#

I want to end on the one place in this system where the correct behaviour is to do nothing, because multi-target is what creates it.

Each herdr server tracks its own focused pane. With two targets connected, two panes can each legitimately report that the user is looking at them, and the daemon has no way to know which screen you are actually in front of.

The physical Enter key sends a keystroke to the focused agent. Guessing wrong there does not display something incorrect. It submits someone else’s prompt, to a different agent, on a different machine, with whatever half-written text was sitting in that pane.

getFocusedAgent(): AgentSnapshot | undefined {
 if (this.focused) {
 return this.agentsList.find((a) => sameAgent(a, this.focused));
 }
 const herdrFocused = this.agentsList.filter((a) => a.focused);
 // More than one target can each report a focused pane; only an
 // unambiguous single candidate is safe to act on.
 return herdrFocused.length === 1 ? herdrFocused[0] : undefined;
}

An explicit slot press always wins, because that is you telling it. Absent that, one candidate is a fallback and two candidates is nothing. The refusal has its own test, with the reasoning written into the test body, because it is the kind of behaviour a future refactor would happily “fix” into a [0].

Lessons
#

A bound socket is not a connected socket. ssh -L binds before anything reaches the far end, so the file existing proves only that ssh started.
End every “establish” with a probe that exercises the thing you are claiming works. Reachability is the claim, so make a round trip and let that be the definition.
If a process fails asynchronously on stderr, drain stderr for its whole life. Reading it only at startup means the exact bytes naming your bug are being written and discarded while you debug.
A long-lived tunnel must own its SSH connection. Muxing onto a user’s ControlMaster couples the daemon to a terminal, and winning the race to become the master is worse, because now your restart drops their shells.
Classify failures before retrying them. Auth and host-key failures should never retry; timeouts, refusals and DNS should, because DNS under a sleeping VPN is indistinguishable from DNS against a dead host.
Log the loud error once per target, not once per retry. A diagnostic that repeats every fifteen seconds is a log flood that people filter out.
localhost is a valid far side. Most of a remote-path test matrix runs against sshd on the same machine, and only latency and link loss need real hardware.
When ambiguity could take a destructive action, do nothing and test that you do nothing. Sending Enter to the wrong agent submits someone else’s prompt.

References
#

ssh_config(5) for ControlMaster, ControlPath, ControlPersist and ExitOnForwardFailure; ssh(1) for -L and streamlocal forwarding
OpenSSH release notes on Unix-domain socket forwarding: https://www.openssh.com/txt/release-6.7
herdr: https://herdr.dev
The rebuild that made remote almost free: I deleted six subsystems by swapping one dependency.
HerdDeck tunnel manager, ssh args, stderr ring and the probe: packages/daemon/src/tunnel.ts
HerdDeck registry, retry classification and backoff: packages/daemon/src/registry.ts
Remote-path static review findings: docs/plans/2026-08-08-remote-path-review.md

The ring was 1.00:1 against its background. The key read 35% at 65%.

nickboy@users.noreply.github.com (Nick Liu) — Wed, 02 Sep 2026 00:00:00 +0000

A key on my Stream Deck showed an agent with a context window 65% full. The ring around it displayed a little over a third of a circle, which anyone would read as 35%. Not blank, not obviously broken, no missing-data placeholder. Confidently wrong, by exactly the amount that inverts the decision you are making when you look at it.

Tested with herdr 0.8.0 · macOS

That is the hardware, live against five agents on a remote machine. The top row is one key per agent. The tint is that session’s lifecycle state, and the ring is how full its context window is. Two independent signals, one key.

That sentence is the bug. It took me three weeks and an adversarial review to hear it.

It started as a text bug
#

The slot titles were hardcoded fill="#fff". White text on every status colour, and the status colours are Catppuccin Mocha accents, half of which are pale.

I measured every combination. These numbers I have recomputed from the palette hexes for this post rather than quoting the ones in my notes, which turned out not to survive checking:

Status	Background	White text	Dark text
`working`	`#f9e2af`	1.27:1	12.91:1
`done`	`#a6e3a1`	1.49:1	11.03:1
`blocked`	`#f38ba8`	2.32:1	7.08:1
`idle`	`#6c7086`	4.88:1	3.36:1
`offline`	`#45475a`	9.12:1	1.80:1

WCAG AA for normal text is 4.5:1. Three of five statuses failed, and working, at 1.27:1, is effectively invisible. That is the state you most need to read at a glance, because it is the one that tells you an agent is busy rather than waiting on you.

Note the last two rows. White is genuinely correct on the dark half of the palette. So the fix is not “swap white for dark”, it is “pick per background”:

export function inkFor(backgroundHex: string): string {
 return contrastRatio(backgroundHex, INK_DARK) > contrastRatio(backgroundHex, INK_LIGHT)
 ? INK_DARK
 : INK_LIGHT;
}

The status colours themselves are unchanged, so the colour coding still means what it meant. A parameterised test asserts every status clears AA, driven off the palette object itself, so adding a status generates its own case.

I shipped that, titled the commit “make slot text readable”, and wrote in the message that the new test meant a future palette change could not quietly reintroduce the problem.

The review said I had fixed the wrong surface
#

I asked for an adversarial review of that work. The first finding was that the commit fixed the text on a key whose dominant graphic is the ring, and the ring was worse.

Worse, and untested. The commit message claimed a guarantee about future palette changes. That guarantee was real for the text and did not exist for the ring, because the test never covered the ring. I had written a confident sentence about a protection I had not built.

The ring took its colour from thresholdColor(pct), green under 50%, yellow to 79%, red above, drawn straight onto the status-coloured background. Two palettes, both Catppuccin accents, on the same surface.

Three collisions, and only two were the same colour
#

Those are working, blocked and done. The threshold palette is #94e2d5, #f9e2af, #f38ba8.

Two of the collisions are trivial once you line the hexes up:

THRESHOLD_YELLOW === STATUS_COLOURS.working // "#f9e2af"
THRESHOLD_RED === STATUS_COLOURS.blocked // "#f38ba8"

Same string. A yellow ring on a yellow key, a red ring on a red key.

The third one is the one I missed, and it is more interesting. done is #a6e3a1 and THRESHOLD_GREEN is #94e2d5. Those are not the same colour. One is a green and the other is a teal, and side by side you can tell them apart immediately.

#a6e3a1 relative luminance 0.65618
#94e2d5 relative luminance 0.65493

Contrast ratio is a ratio of relative luminances. Hue does not enter into it. Two colours that differ obviously to the eye can be arithmetically indistinguishable to the contrast formula, and these differ by roughly one part in five hundred, which rounds to 1.00:1.

Across all eighteen ring-and-background pairs I get eleven under the 3:1 floor for non-text graphics, and three at exactly 1.00:1, on working, blocked and done. My original notes said nine under 3:1, which is why I recomputed everything for this post. If you are going to publish a table criticising a palette, run the numbers again first.

Invisible would have been the good outcome
#

This is where a contrast bug turns into a correctness bug.

A ring is drawn as two arcs. The filled arc is the percentage. The unfilled remainder is a track, and the track is not the background, it is stroke="#000" at stroke-opacity="0.35", a dark groove so you can see where the ring would go.

Set the filled arc to the same colour as the background and it disappears into the background. The track does not. It is still a dark arc.

So a working agent at 65% context lost its filled 65% and kept its empty 35%, and what you saw was a single dark arc covering a bit more than a third of the circle.

Not blank. Not a question mark. A confident, readable, wrong number, and inverted in the specific sense that it reported the complement. working and blocked are the two states where you are actively deciding whether to intervene, and both of them lied.

The fix deleted a signal
#

The instinct is to add something: a border, an outline, a different threshold palette tuned for contrast against each background. All of that is more code defending a design that was wrong.

Arc length already encodes the percentage. Hue was re-encoding the same number, coarser, in the one channel the background had already claimed. So the ring now draws in inkFor(backgroundHex), the same ink as the text:

const ink = inkFor(render.backgroundHex);

That resolves the collision by construction and inherits the text’s contrast guarantee for free, which means a future palette edit cannot bring it back. Post-fix, the filled arc against its own track measures 3.23:1 on blocked, 4.75:1 on done, 5.43:1 on working, 8.93:1 on idle and 13.41:1 on offline. All clear of the 3:1 non-text floor, and the test asserts it per status.

thresholdColor still exists and still earns its place on the Plan Usage key, whose background is a neutral constant. The function was never the problem. Drawing it onto a surface that already owned that channel was.

The general lesson has nothing to do with colour. Two independent signals were competing for one channel on one surface, and the symptom of that competition was not “hard to read”. It was “reads as a different number”.

The near-miss underneath
#

One more, because it makes the same point a third time and I only caught it because the tests were parameterised by then.

An intermediate version drew the text at fill-opacity="0.75" for a softer look. The suite was measuring the ink against the background and reporting 7.08:1 on blocked and 4.88:1 on idle, both passing. Composite the actual 75% ink over the actual background and you get 4.40:1 and 3.54:1. Both below AA. The suite was measuring a colour that was never drawn.

There is now a test asserting no partially-transparent text, which is a blunter rule than “composite before measuring” and the right one for a surface this small.

Lessons
#

One surface, one channel, one signal. If two independent values both want colour on the same graphic, one of them has to move to position, length, or a different element.
A contrast collision on a partially-filled indicator does not produce a blank. It produces the complement, because the unfilled track survives. Confidently wrong beats obviously broken in every way except the one that matters.
Contrast ratio is a luminance ratio and knows nothing about hue. Two colours you can tell apart instantly can be 1.00:1 to the arithmetic and to anyone glancing at a 72-pixel key.
Fix the dominant graphic first. I shipped a fix for the text on a key whose main feature is a ring, and the commit message was more confident than the diff.
If a commit message claims a guarantee, point at the test that provides it. Mine claimed a future palette change could not reintroduce the bug, and the test that would have made that true did not exist.
Prefer deleting a redundant encoding to defending it. Arc length already carried the number; the colour was a second, coarser copy sitting in a channel that was already taken.
Measure the pixels you actually draw. Opacity, gradients and overlays all mean the colour in your test is not the colour on the screen.
A documented design system does not give you contrast for free. Catppuccin Mocha is carefully built, and nothing in it stops you putting its lightest yellow behind white text.

References
#

WCAG 2.2 contrast minimum for text, 4.5:1: https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html
WCAG 2.2 non-text contrast, 3:1 for graphical objects and UI components: https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html
Catppuccin Mocha palette: https://github.com/catppuccin/catppuccin
The rebuild these keys belong to: I deleted six subsystems by swapping one dependency.
The other thing that review caught: My backoff logged errors=1 492 times.
My earlier post on this palette: Catppuccin Mocha theming
HerdDeck slot rendering, inkFor and the ring: packages/plugin/src/actions/agentSlot.ts
The parameterised contrast tests: packages/plugin/src/actions/agentSlot.test.ts

Every context ring read 10%. Two bugs, and fixing one hid the other.

nickboy@users.noreply.github.com (Nick Liu) — Tue, 01 Sep 2026 00:00:00 +0000

Each agent key on the Stream Deck draws a ring showing how full that session's context window is. Mine sat at 10% for days. Every session, regardless of activity, regardless of how long the agent had been grinding. I found the bug, fixed it, watched agents start reporting correct percentages every single turn, and the ring still said 10%. That was the good part, because it meant there were two.

Tested with Claude Code 2.1.x · macOS

Ten percent is a suspicious number. Not zero, which would say “nothing ever arrived”. Not a plausible-looking 37%, which would say “this works and your session is small”. Ten percent is round, and round numbers in a display that should be noisy mean the display is not reading anything.

It turned out to be an orphan. Something wrote 10% into the cache a long time ago and nothing had overwritten it since, on any session, for days.

Symptom

day 1

Ring pinned at 10% on every agent slot. Suspiciously round.
Bug one found

day 1

The statusline delegate reads .context_window.percentUsed. Claude Code emits .context_window.used_percentage. The extraction silently yields nothing, every turn.
Fixed, and wrong

day 2

Agents now report a correct percentage every turn. The ring still reads 10%.
Three live probes

day 2

pane.report_metadata emits nothing. pane.agent_status_changed carries no tokens. Tokens are assigned in exactly one place.
Root cause

day 2

The daemon snapshotted once on connect. Every ring froze at whatever it read at that instant.

Bug one: a field name that does not exist
#

HerdDeck ships a statusline delegate. It sits in front of whatever statusline you already have, forwards the per-turn JSON payload on to herdr, and passes your original output through untouched. It read this:

.context_window.percentUsed

Claude Code emits .context_window.used_percentage.

Getting the field name wrong is unremarkable. How it failed is the part worth keeping. A statusline script runs on every turn of every session, and a statusline script that throws takes your prompt down with it, so the whole thing is written to fall through silently on every path. Wrong field name, malformed JSON, jq missing, all of it produces the same result: no error, no output, no report, forever.

Silent-by-design is correct for a statusline. It is also a category of bug where nothing anywhere tells you the value never arrived, and the only symptom is a number somewhere else that stops changing.

There is a small joke at my expense here. I wrote a post about this exact payload in May, and that post prints the schema with the correct field name in it. My own published documentation had it right. The code I shipped three months later did not.

The fix keeps the wrong name deliberately, which was not my first instinct:

# Field name: Claude Code emits `.context_window.used_percentage`. An
# earlier revision of this script read `.percentUsed`, which does not
# exist — the extraction silently yielded nothing and the donut never
# lit up. `percentUsed` is kept only as a fallback so the script also
# works against any build that ever used it; `used_percentage` wins.
PCT="$(printf '%s' "$INPUT" | jq -r '.context_window | (.used_percentage // .percentUsed // empty)' 2>/dev/null)"

Two tests pin the behaviour: one that the fallback works, one that used_percentage wins when both are present. A silent fallback needs a test asserting the ordering, or it is just a second way to be quietly wrong.

The fix worked and the ring did not move
#

This is the part of the debugging that went wrong, and it is why the post exists.

After the field-name fix, every agent reported a correct, changing percentage on every turn. I could watch the numbers arrive. And the ring still sat at 10%.

For an hour or so I was debugging the wrong thing, because the evidence pointed backwards. A fix that produces correct data and no visible change reads as “the fix did not work”. I went back over the delegate. I checked the JSON. I checked that the daemon was receiving it. All fine, all pointless, because the second bug had been there the entire time and the first one had been hiding it perfectly.

A cosmetic symptom with two independent causes is much harder than a symptom with one hard failure. With one cause, fixing it resolves the symptom and you are done. With two, fixing the first one changes nothing observable, and the natural inference is that you were wrong about the first one.

Three probes against a live server
#

So I stopped reading code and started asking the server questions. Three probes, against herdr 0.8.0, with a real agent working in a real pane.

Probe	Result
Report metadata to a pane while subscribed to `pane.updated`	zero events for that pane. `pane.report_metadata` emits nothing at all
Inspect `pane.agent_status_changed` payload	carries only `{pane_id, agent_status}`. No tokens
Grep the cache for token assignment	exactly one site: the `session.snapshot` seed

Put those together and the answer is unavoidable. The daemon snapshotted once on connect, and every ring froze at whatever the snapshot happened to contain at that instant. Nothing in the protocol was ever going to push a token count at it.

`pane.updated` looked like the answer
#

There is an event called pane.updated and it does carry tokens. It looked like the fix for about ten minutes.

It is not, for two reasons, and the second one is decisive.

It is chatty. It fires on scroll offsets and status flicker, and the measurement recorded in the source is roughly 25 events in 2.5 seconds from a single active pane. Subscribing to that to catch a number that changes once per turn is a poor trade.

And it does not fire for a metadata report at all. That is the case that matters. A pane whose context moved while it sat idle would simply never be announced, which is precisely the situation where you want the ring to be honest, because you are looking at a key rather than at the terminal.

Rejecting an event on measurement rather than on taste is worth doing explicitly. pane.updated is the obvious answer, it is in the schema, and it would have shipped a ring that worked most of the time and lied when you were not watching.

Re-read, merge, do not re-seed
#

The fix is a periodic snapshot on a 10-second default, and the merge is the load-bearing part:

/** Token re-read period; 0 disables it. Default 10s — roughly
 * twice Claude Code's default statusline refresh, so the donut
 * trails the real percentage by at most one report. */
tokensRefreshMs?: number;
// ...
this.tokensRefreshMs = opts?.tokensRefreshMs ?? 10_000;

The timer’s snapshot can be older than pushed events the cache has already applied. Re-seeding from it would let a stale read undo a pane close that a newer event had already processed, resurrecting a pane that is gone. There is a test pinning exactly that, and its comment says why:

// The refresh re-reads a full snapshot but must merge tokens ONLY:
// re-seeding would let a stale snapshot undo a close that a newer
// pushed event already applied.

One correction to my own framing, because I described this as “tokens only” for a while and it stopped being true. The merge now also carries the focused flag, deliberately and with its own justification comment. If you go looking at that function expecting the name to be the specification, it will not be.

Lessons
#

A suspiciously round number in a noisy display means the display is not reading anything. Zero says “nothing arrived”, and a plausible number says “this works”. Round says “orphan”.
Silent-by-design is right for a statusline and it removes your only failure signal. A wrong field name in a script built never to break a prompt produces no error, no output, and no report, on every turn, indefinitely.
When a correct fix produces no visible change, consider that you fixed one of two bugs before concluding you fixed none. Two independent causes of one cosmetic symptom is the case where evidence points backwards.
Probe the live server instead of reading its schema. “Does this call emit an event at all” is a question a schema cannot answer and a five-minute experiment can.
Reject the obvious event on measurement, not taste, and write down the measurement. pane.updated carried the field I wanted and did not fire for the case I needed.
A periodic re-read must merge, never re-seed. A refresh that is older than the events you have already applied will happily undo them.
If a fallback exists, test the ordering, not just the fallback. Otherwise it is a second way to be quietly wrong.

References
#

Claude Code statusline docs, source of truth for the payload schema: https://code.claude.com/docs/en/statusline
The post that printed the correct field name three months before I got it wrong: The Claude Code statusline is a per-turn telemetry side channel
The rebuild this ring belongs to: I deleted six subsystems by swapping one dependency.
HerdDeck statusline delegate: scripts/herddeck-statusline.sh
HerdDeck state cache, including mergeTokensFromSnapshot: packages/daemon/src/stateCache.ts
HerdDeck target monitor, the refresh timer: packages/daemon/src/herdr/monitor.ts

My backoff logged errors=1 492 times. It was answering the wrong question.

nickboy@users.noreply.github.com (Nick Liu) — Mon, 31 Aug 2026 00:00:00 +0000

The daemon's log contained the line `plan poller cadence: errors=1` four hundred and ninety-two times, and `errors=4` five times. A counter that is supposed to climb during an outage had spent its entire life bouncing off one. A third of my requests were being rate-limited and the backoff built to handle that never engaged once, because it was answering a question nobody had asked.

Tested with herdr 0.8.0 · macOS

The Plan Usage key on the Stream Deck renders my Claude plan’s 5-hour and 7-day windows with a countdown to the next reset. HerdDeck polls Anthropic’s OAuth usage endpoint to fill it. That endpoint is undocumented, which is a story I have already told on this blog and will be correcting later in this post.

The log showed this, live, on my machine:

successes: 1136
HTTP 429: 543
recent ticks: update error update update error update update error update error update update

Two facts in that block, and the second one is the whole post.

A third of requests were rate-limited. And the failures arrived interleaved, not in runs.

Consecutive-error backoff answers “is the service down”
#

The mechanism I had was textbook exponential backoff on a consecutive-error counter. Every failure increments it and lengthens the interval. Any success resets it to zero.

That shape encodes an assumption: failures cluster. It is designed for an outage, where the service goes away, you back off further and further, and when it returns you snap back to normal cadence. Under those conditions the counter climbs, the interval grows, and the mechanism does its job.

Now feed it update error update update error update. With a success rate around two in three, the counter never survives long enough to reach two. The cadence oscillates between the 60-second base and a single doubling, forever, permanently pinned at the limit.

Logged cadence line	Occurrences
`errors=1`	492
`errors=4`	5

492 to 5. The counter was not counting an outage, because there was no outage. Every one of those 543 rejections was the server saying “you are asking too often”, which is a completely different question, and no amount of tuning the first answer addresses the second.

Three fixes, in descending order of how much they mattered
#

One: the interval was absurd. A 60-second poll for a key rendering 5-hour and 7-day windows. Those numbers move far slower than a minute. The poll is now five minutes, and the comment in the source carries the measurement that justified it:

// 5 minutes, not 60s. The 5-hour and 7-day windows this renders move
// far too slowly to justify a minute-by-minute poll, and 60s put the
// daemon permanently at Anthropic's rate limit: 1136 successes against
// 543 HTTP 429s on this machine, arriving interleaved. With two daemons
// on one account it was double that.
const PLAN_POLL_INTERVAL_MS = 5 * 60_000;

Roughly 80% of the request volume disappeared into that one constant. Everything below is smaller.

Two: obey the server. Anthropic states the correct wait in Retry-After, and the fetcher had been capturing that header all along, formatting it into a log string, and throwing it away. It now gets parsed and clamped, never faster than the base interval and never slower than the cap:

this.currentIntervalMs = Math.min(Math.max(retryAfterMs, this.intervalMs), this.maxBackoffMs);

Three: do not poll when nobody is looking. A daemon with no Stream Deck attached was polling anyway. In a two-machine setup that is the herdr host spending half the account’s request budget rendering a key that is not on screen. The gate is read per tick rather than latched at startup, so plugging a deck in does not require a daemon restart, and a skipped tick deliberately never reaches the cadence logic at all. A skipped tick is evidence of neither success nor throttling, and counting it as clean would let a headless daemon walk its way back down to an aggressive cadence without issuing a single request.

What a review found that twelve tests did not
#

I shipped an adaptive floor alongside those fixes. Every failure raised it by 1.5x, five consecutive clean ticks earned one step back down. Back off fast, recover slowly. It had twelve tests and they all passed.

Then I asked for an adversarial review of the arithmetic, and got three findings, none of which a test could have caught, because in every case the tests agreed with the code.

The tests ran against a configuration the same commit had changed. The floor was tuned and verified at a 60-second base interval. The same commit moved production to 300 seconds. The cap was 10 minutes flat at the time. At 60 seconds that gives you a ladder with real rungs. At 300 seconds, the consecutive-error term is base * 2^errors, so the first failure lands on 600 seconds, which is the cap exactly, and every subsequent failure lands there too.

Five distinct intervals become two. The blue ladder is what twelve tests exercised. The red one is what ran on my machine. Same code, same commit, and the consecutive-error term never affected an outcome again.

The tuning knob was mathematically inert. Up-steps and down-steps were the same multiplicative size, so the constant that looked like the tuning parameter cancelled out of the stability condition entirely. Only the streak length could affect whether the mechanism converged. A knob that cannot turn anything is worse than no knob, because sooner or later somebody turns it and reasons from the result.

And there was a reason to delete it that had nothing to do with rate limiting. The floor rose on any failure, including failures that say nothing about request rate. An expired OAuth token pinned the cadence at the ceiling and kept it there for tens of minutes after I had re-authenticated.

So the mechanism was deleted rather than tuned, and what replaced it is less code than what it removed.

Two things about the review itself are worth more than the findings.

It was asked to attack a specific claim with the arithmetic demanded rather than the verdict: work through the failure rate, does this converge or pin at the cap? It came back with a Markov chain, a break-even threshold of 12.9%, and the observation that my convergence worry was unfounded while a different problem was fatal. A reviewer told to find problems will find some. A reviewer told to check a specific number will sometimes tell you the number is fine and the question was wrong.

And the reviewer corrected itself. Its first pass closed by suggesting that wiring one constructor argument would have delivered more than the whole mechanism. Asked to confirm before that shaped the fix, it checked, found that the channel it depended on does not exist anywhere in the repo, and led its second response by retracting the claim. That retraction was the most valuable paragraph in the review. A review that cannot be wrong is not a review.

The part I have to say about my own cleanup
#

Given that the finding above was “you claimed a guarantee your test never made”, I am not going to claim a clean deletion.

The floor’s logic is gone. Its residue is not. The class docstring still describes the adaptive floor as a live mechanism, in direct contradiction of the method docstring a hundred lines below it. The cap constant is still named MAX_BACKOFF_FLOOR_MS. A passing test is still titled “a sustained clean streak earns the floor back”, testing something that no longer exists under a name that says it does.

None of that changes behaviour. All of it is exactly the kind of thing that convinces the next reader, including the next me, that a mechanism is present when it is not.

The correction I owe an earlier post
#

In May I wrote I polled an undocumented endpoint for 18 hours. The data was on stdin. The argument was that /api/oauth/usage was the wrong primitive and Claude Code’s statusline already pushes rate_limits.five_hour and rate_limits.seven_day every turn, for free.

The narrow claim still holds. Those two fields are documented and they are there.

The conclusion I drew from it overreached. I wrote that the endpoint had become “the fallback path now, not the primary one”, and HerdDeck found the inverse. The account this runs against returns seven buckets:

five_hour, seven_day, seven_day_opus, seven_day_sonnet,
seven_day_cowork, seven_day_oauth_apps, seven_day_omelette

The per-model weekly windows have no documented statusline equivalent. The statusline is a subset of that endpoint, not a replacement for it, and if you want to know how much Opus specifically you have left this week, the undocumented endpoint is the only place that answers.

HerdDeck was dropping five of those seven for weeks, because the code that picked weekly buckets out of the response matched on the substring weekly and every per-model key spells it seven_day_. The filter now matches both halves:

if (!/weekly/i.test(key) && !/^seven[_-]?day[_-]./i.test(key)) continue;

There is a second, smaller correction. That May post called its statusline freshness gate “the load-bearing change”. HerdDeck carried the same-shaped gate forward, and it has fired zero times. Not rarely. Zero. Nothing populates the timestamp it reads, because the statusline auto-patcher that used to populate it was one of the subsystems the rebuild deleted.

I want to be precise about what that does and does not mean. It is not evidence that the gate was wrong in ClaudeDeck, where it was wired to a feeder that existed. It is that I carried the seam across a rewrite and left the feeder behind, then spent weeks suffering the exact problem the seam was built to prevent while looking straight at machinery that was inert the entire time. The gate’s docstring now says so in capital letters instead of implying a defence it does not provide.

Lessons
#

Consecutive-error backoff answers “is the service down”. If your failures arrive interleaved with successes, you are being told “you are asking too often”, and no amount of tuning the first answer addresses the second.
Look at the distribution of your error counter, not just its maximum. 492 occurrences of errors=1 against five of errors=4 says the mechanism never engaged, and it says it in one grep.
The server usually knows the right answer. Retry-After beats any heuristic that guesses at it, and it is often already in a variable you are formatting into a log line.
A test suite that runs against a different constant than production is measuring a system nobody has. Check what the same commit changed before trusting what its tests proved.
If a tuning constant cancels out of the maths, delete it. A knob that cannot turn anything is worse than no knob, because someone will turn it and believe the result.
Deleting a mechanism means deleting the docstrings, constant names and test titles that advertise it. Residue outlives behaviour and it is what the next reader believes.
When you port a design across a rewrite, port the thing that feeds it or delete the seam. A defence with no input is indistinguishable from a defence, right up until you need it.

References
#

Claude Code statusline docs, the documented rate_limits contract: https://code.claude.com/docs/en/statusline
RFC 9110 section 10.2.3, Retry-After semantics: https://httpwg.org/specs/rfc9110.html#field.retry-after
The post this one corrects: I polled an undocumented endpoint for 18 hours. The data was on stdin.
The rebuild that deleted the statusline auto-patcher: I deleted six subsystems by swapping one dependency.
HerdDeck poller and cadence logic: packages/daemon/src/planUsagePoller.ts
HerdDeck usage fetcher, Retry-After parsing and the weekly-bucket filter: packages/daemon/src/claudeAiFetcher.ts

I deleted six subsystems by swapping one dependency. The protocol billed me.

nickboy@users.noreply.github.com (Nick Liu) — Sun, 30 Aug 2026 00:00:00 +0000

Six of the ten posts in my "Building ClaudeDeck" series document code that no longer exists. Over four days in August I rebuilt the plugin on herdr's socket API, and the hook dispatcher, the PTY runner, the statusline auto-patcher, the AppleScript focus path, the Claude project watcher and the shell-PID resolver all went in the bin, taking the `.app` bundle, the codesigning step and every TCC prompt with them. Then the substrate sent its invoice.

Tested with herdr 0.8.0 · macOS

ClaudeDeck was complicated for exactly one reason. Claude Code has no control API, so every fact the plugin needed had to be stolen from somewhere it was not offered.

To know an agent was blocked, it installed hooks and dispatched them. To know how full the context window was, it patched the statusline. To read what a pane was showing, it ran a PTY and kept a ring buffer. To jump to the right terminal tab it drove AppleScript, which meant Accessibility, which meant TCC, which meant codesigning. To know which project a shell belonged to, it resolved shell PIDs and watched the projects directory.

herdr is a terminal multiplexer built for coding agents. It already tracks all of that, and it exposes it on a Unix socket speaking NDJSON. Agent lifecycle, idle and working and blocked and done, is a first-class concept in the protocol rather than something you infer.

So the interesting artifact of this rebuild is not what I wrote. It is what came out.

What all that code was for
#

ClaudeDeck subsystem	It existed because	HerdDeck instead
Hook dispatch (post)	nothing tells you an agent is blocked	`agent_status` is a field in the protocol
Permission round-trip (post)	approval meant parking an HTTP response on a Promise	herdr already knows a pane is waiting
Statusline auto-patcher (post)	context fullness had to be smuggled out per turn	a statusline delegate you install yourself, never patched in behind your back
PTY runner and ring buffer (post)	reading a pane meant owning the terminal	herdr owns the terminal
AppleScript, codesigning, TCC (post)	focusing a tab needed Accessibility	one socket call
Shell-PID resolver, project watcher	mapping a shell to a project	herdr tracks it

Two things fell out of that beyond the line count, and only one of them was planned.

It works for every agent herdr recognises. Claude Code, Codex, OpenCode. The old design was Claude-shaped because hooks are Claude-shaped. The new one asks herdr what is running and gets an answer that was never Claude-specific in the first place.

Remote came close to free. herdr splits client from server, so the server holds the state and a remote server speaks the identical protocol. Forward the socket over SSH and the same daemon code drives agents on another machine.

I want to be careful about the word “free”, because there is a caveat and the obvious guess about it is wrong. herdr --remote makes the human terminal experience a thin client, but it does not expose a local API socket proxying the remote server. The local herdr-client.sock is a TUI attach endpoint and nothing more. The daemon needs its own forward. And the auto-sync that keeps herdr versions matched only fires on a human --remote attach, never on the daemon’s forward, so a box you rarely attach to can quietly drift to an older protocol. Every target therefore gets pinged and version-checked on connect and drops to a warning state on mismatch, rather than being assumed compatible.

The bet, and it was a bet
#

I would rather leave this part out.

I have a post on this blog about trialling herdr, with exit conditions written down before the trial started and a verdict due on August 16.

HerdDeck was built between August 6 and August 9.

So I deleted a working codebase and rebuilt my hardware controller on a substrate that was still on probation, a week before the trial I had written exit conditions for was due to conclude. If the verdict had gone the other way, the sunk cost would have been the whole rebuild plus the ClaudeDeck code I had already thrown away.

The verdict has since landed and it went my way. herdr graduated, which is the least interesting thing about it. It graduated on two of its three conditions, because the third turned out to be unanswerable from inside the window: a month of deliberately using one tool makes that tool look load-bearing whichever way the comparison would actually have gone. The trial is the data.

That is the same problem I had already created, one layer down and worse. Building HerdDeck did not merely make herdr look useful. It made herdr useful, to me, on hardware I reach for every day. A trial gets harder to fail once you have built something on the thing being trialled, and I built four days of work on it before the verdict was in.

A favourable answer does not make the sequence defensible and I am not going to dress it up as one. What makes it survivable rather than reckless is narrow: the deletion is reversible in the only sense that matters, because ClaudeDeck is still a repository and still works. What it cost is a real option, the ability to evaluate herdr without also evaluating four days of my own work sitting on top of it.

What the protocol charged
#

These are the things you cannot learn by reading a schema, and they are the actual price of the substrate.

One request per connection. herdr answers the first NDJSON line on a connection and closes it. events.subscribe is the exception: it converts its connection into a long-lived stream with a fixed subscription set. A client that wants to change what it is subscribed to has to open a new stream, which turns every subscription change into a make-before-break problem rather than a mutation.

Event names are inconsistent. Lifecycle pushes use underscores, like pane_created, with data.type repeating the name. Status pushes use dots, like pane.agent_status_changed. The cache accepts both spellings so no caller has to normalise first, which is a workaround rather than a fix.

Container closes do not cascade into pane events. Closing a workspace or a tab emits workspace_closed or tab_closed and nothing else. No pane_closed for the panes inside. A cache that only listens for pane events keeps zombie entries forever, which is exactly what mine did until I noticed.

workspace.close is asynchronous. The ok response returns immediately. The pane processes take one to two seconds to wind down before workspace_closed fires.

New subscribers get synthetic replay. A fresh events.subscribe stream receives pane_created for panes that already existed. This is harmless under the ordering below, and it looks exactly like corruption if you are not expecting it.

Per-pane subscriptions are all-or-nothing. pane.agent_status_changed requires a pane_id and there is no wildcard. One stale id fails the entire batch. That one produced the most instructive bug in the project, and it is the rest of this post.

None of the above is a criticism of herdr, which is a good substrate and the reason the rebuild was worth attempting. It is the answer to the question “what did it cost”, which is the question a post like this usually skips.

The ordering that took three tries
#

The naive connect sequence is: snapshot the state, then subscribe to changes. That loses every transition landing in the gap between the two. The reverse, subscribe then snapshot, double-counts.

What actually works has five steps, and step four is the load-bearing one.

Buffered events are either already reflected in the snapshot or strictly newer than it, and state_change_seq tells you which. Replayed events carrying no sequence number get dropped whenever the pane is already cached, and applied only when they describe something the snapshot missed, such as a pane created after it was taken.

When the recovery mechanism prevents recovery
#

On a busy session the daemon reconnected 24 times in 12 seconds.

The cause is the all-or-nothing subscription rule meeting reality. Short-lived panes, popups and plugin panes, routinely vanish between their pane_created event and the resubscribe that event triggers. herdr fails the entire subscribe batch when one pane_id in it is stale. Tearing down the connection on that failure and reconnecting rebuilds the identical doomed batch, which fails identically, which tears down the connection.

An endless online to connecting flap, in which the recovery mechanism was the only thing preventing recovery.

The fix prunes the vanished pane out of the cache and retries, bounded:

/** Bound on per-open prune retries, so a pathological server can't spin
 * this loop forever. */
const MAX_STALE_PANE_PRUNES = 8;

function stalePaneId(err: unknown): string | null {
 if (!(err instanceof HerdrApiError) || err.code !== "pane_not_found") return null;
 return /pane (\S+) not found/.exec(err.message)?.[1] ?? null;
}

Reconnects went from 24 in 12 seconds to one.

The bound matters more than the prune. Retry-until-it-works against a server that will never agree is the same flap with extra steps, so the loop gives up after eight prunes and throws with a message naming the count. A recovery path that cannot fail is not a recovery path.

What it came to
#

Four days, 36 commits on main, 35 of them merged through pull requests behind seven required checks. Four packages, 504 tests across 32 files, and close to one line of test for every line of source, which was not a target so much as a description of where the difficulty lived.

The difficulty did not live in the Stream Deck. It lived in the seam.

Lessons
#

Changing the substrate is a deletion strategy. If a dependency already tracks the thing you are inferring, the win is measured in subsystems removed, not features added.
Ask what a protocol costs before you claim it saved you something. Event naming, connection lifetime and subscription granularity are the parts no schema documents and the parts you will actually pay for.
Subscribe first and buffer, then snapshot, then replay against the sequence numbers. Snapshot-then-subscribe drops transitions and subscribe-then-snapshot double counts.
If one bad id fails a whole batch, reconnecting rebuilds the same bad batch. Prune the offending item and retry, bounded, or the recovery path becomes the outage.
Building on a tool you are still evaluating makes the evaluation harder to fail. Write down that you did it, because sunk cost will not remind you later.

References
#

herdr: https://herdr.dev (source: https://github.com/herdrdev/herdr)
HerdDeck: https://github.com/nickboy/herddeck. Engineering notes, including the protocol behaviour above, in docs/engineering-notes.md
ClaudeDeck, the predecessor: https://github.com/nickboy/claudedeck
The herdr trial this rebuild jumped ahead of: Running six agents made tab patrol my biggest time sink. So: a herdr trial.
The hook layer HerdDeck deleted: The Claude Code hooks docs are wrong. Here’s what’s actually on the wire.
The PTY runner HerdDeck deleted: I split my daemon in two so a Node subprocess could own the PTY
The codesigning and TCC path HerdDeck deleted: TCC pins your Accessibility grant to a cdhash. Every rebuild breaks it.

Herddeck on Nick Liu - Software Engineer

The context percentage is a division. Nothing tells you the denominator.

Five places the window size is not #

Why I rejected a model-to-window lookup table #

What the script does instead #

Two routes, and why both exist #

Running both against four live sessions #

Lessons #

References #

launchctl bootout returned 0. The label was still there. Bootstrap failed 5.

The idempotency fix that caused it #

What bootout actually returns #

Why the failure is silent #

The fix: poll, then retry, both bounded #

The pattern, and its sibling #

Lessons #

References #

The tunnel was up. The socket existed. Nothing was on the other end.

ssh -L binds before it connects #

The error was there the whole time #

ControlMaster pollution, in both directions #

Not every failure deserves a retry #

localhost is a valid far side #

One caveat about --remote, because the obvious guess is wrong #

When not to guess #

Lessons #

References #

The ring was 1.00:1 against its background. The key read 35% at 65%.

It started as a text bug #

The review said I had fixed the wrong surface #

Three collisions, and only two were the same colour #

Invisible would have been the good outcome #

The fix deleted a signal #

The near-miss underneath #

Lessons #

References #

Every context ring read 10%. Two bugs, and fixing one hid the other.

Symptom

day 1

Bug one found

day 1

Fixed, and wrong

day 2

Three live probes

day 2

Root cause

day 2

Bug one: a field name that does not exist #

The fix worked and the ring did not move #

Three probes against a live server #

pane.updated looked like the answer #

Re-read, merge, do not re-seed #

Lessons #

References #

My backoff logged errors=1 492 times. It was answering the wrong question.

Consecutive-error backoff answers “is the service down” #

Three fixes, in descending order of how much they mattered #

What a review found that twelve tests did not #

The part I have to say about my own cleanup #

The correction I owe an earlier post #

Lessons #

References #

I deleted six subsystems by swapping one dependency. The protocol billed me.

What all that code was for #

The bet, and it was a bet #

What the protocol charged #

The ordering that took three tries #

When the recovery mechanism prevents recovery #

What it came to #

Lessons #

References #

Five places the window size is not
#

Why I rejected a model-to-window lookup table
#

What the script does instead
#

Two routes, and why both exist
#

Running both against four live sessions
#

Lessons
#

References
#

The idempotency fix that caused it
#

What `bootout` actually returns
#

Why the failure is silent
#

The fix: poll, then retry, both bounded
#

The pattern, and its sibling
#

Lessons
#

References
#

`ssh -L` binds before it connects
#

The error was there the whole time
#

ControlMaster pollution, in both directions
#

Not every failure deserves a retry
#

localhost is a valid far side
#

One caveat about `--remote`, because the obvious guess is wrong
#

When not to guess
#

Lessons
#

References
#

It started as a text bug
#

The review said I had fixed the wrong surface
#

Three collisions, and only two were the same colour
#

Invisible would have been the good outcome
#

The fix deleted a signal
#

The near-miss underneath
#

Lessons
#

References
#

Bug one: a field name that does not exist
#

The fix worked and the ring did not move
#

Three probes against a live server
#

`pane.updated` looked like the answer
#

Re-read, merge, do not re-seed
#

Lessons
#

References
#

Consecutive-error backoff answers “is the service down”
#

Three fixes, in descending order of how much they mattered
#

What a review found that twelve tests did not
#

The part I have to say about my own cleanup
#

The correction I owe an earlier post
#

Lessons
#

References
#

What all that code was for
#

The bet, and it was a bet
#

What the protocol charged
#

The ordering that took three tries
#

When the recovery mechanism prevents recovery
#

What it came to
#

Lessons
#

References
#