Month: August 2026

The maintainer merged the argument, not just the patch

Gregory Golberg voitta , , , ,

Two weeks ago I wrote about a scanner that graded my orchestration a C. The complaint was construct validity: the score counted named tool invocations and called the result proficiency, so work done by any other mechanism registered as absence.

I’m now at 500/1000, B-Tier. That’s the least interesting thing in this post.

The interesting part is what happened between the two numbers, because it is the clearest example I’ve had recently of a disagreement that made both sides more correct.

What actually shipped

Four pull requests against aiqrank/plugin. Two merged the same day, one is open pending a review question, and one I closed myself — more on that below.

The merged ones are small and boring, which is the point:

  • command_diversity was in the shared rollup schema but only ever incremented by the Codex scanner. Every Claude Code user uploaded a hard 0. Not “this user runs one command over and over” — nobody was looking.
  • Plan artifacts were recognized only under docs/plans/ or .context/plans/. The same file, written for the same reason, counted or didn’t based on where a repo happened to keep it.

Both are the same defect wearing different clothes: in a schema shared across several collectors, a field that only one collector populates serializes as 0 for everyone else, and the wire format has no way to say not applicable here. Three completely different facts collapse into one byte — the user didn’t do it, this source never reports it, or the user did it by a means the collector doesn’t recognize.

That third one is the one that stings, and it’s the one no amount of adding fields will fix.

The part I got wrong

I asserted that a test fixture path was a bug: it resolved one directory above the repository root, so the fixtures could never be found. I wrote a patch, wrote a PR body explaining the error, and was quietly pleased with myself.

It wasn’t a bug. The path is correct for the layout the plugin actually ships from, where it sits inside a larger repository. I had only ever seen my own fork, where the root is one level shallower, and concluded from a single data point that the other layout was a mistake. The maintainer fixed it properly — resolve both roots, use whichever exists — and committed the missing fixtures besides.

I closed my PR. It was wrong in a way I couldn’t have seen from where I was standing, which is a different thing from being careless, and worth distinguishing.

That was the third correction of the exercise. I had already retracted a claim that MCP tool calls weren’t being counted (they were), and another about how session counters aggregate (I’d misread the rollup). Each retraction came from the same failure: I reasoned from a field’s name instead of finding the line that increments it.

The part he got right that I hadn’t thought of

On the plan-artifact PR, I argued the allowlist was arbitrary because repos organize themselves differently. He accepted it and added a better reason than mine: Claude Code’s own plan mode writes to ~/.claude/plans/, which the allowlist also missed. So the scanner wasn’t just failing to see third-party conventions. It was failing to see its own first-party output.

He then bumped the measurement version — the scanner stamps every row with a PLANNING_MEASUREMENT_VERSION so the server can tell old rows from new ones — from 1 to 2, because the definition of a plan artifact had genuinely changed. That is the discipline I had been asking for, applied without being asked, one PR after I asked for it.

The disagreement that stayed a disagreement

I also filed an issue arguing the deeper thing: that the choice of which tool names count as sophistication is a claim about the correct way to work, embedded in a number rather than stated. ORCHESTRATION_TOOLS = {"Agent"} is one string. Fan out across git worktrees and separate processes instead, and you’ve done strictly more work for zero credit.

His reply is the best thing to come out of this. Paraphrasing badly:

  • Version string: yes. Scores already carry an internal methodology version so users don’t see phantom drops when the math changes. It just isn’t surfaced. It will be, alongside plain-English descriptions of each dimension.
  • Most of the rubric is already published, and the rest will be. And the detail that saves everyone reverse-engineering: within a source, the base weights are equal. There’s no secret weight table.
  • The tuning coefficients stay private, and here’s the reasoning I have no rebuttal to: those numbers move as calibration data arrives, and publishing them turns every recalibration into a renegotiation. The transparency people actually want — what is this measuring, and why did my score change — is deliverable without them.
  • On not-observed versus zero: agreed in principle, but don’t write that PR yet. Once a source can say “I can’t report this,” the scorer has to decide whether a non-observation is excluded-and-renormalized or treated as zero, and those produce materially different rankings. He’d rather make that call deliberately than have it smuggled in through a schema change.

And on the framing itself: the tool sets encode a claim about what competent agent use looks like — conceded, with the refinement that the claim is taken partly on evidence and partly on what’s observable without heuristics, and that the current implementation doesn’t distinguish those two constraints. Which is a sharper statement of my own argument than I managed.

We still don’t agree on everything. I think outcome-based signals should displace proxies faster than he does. He thinks the wire-format change needs a scoring decision first, and he’s right that it does. Nobody folded.

The thing worth generalizing

He told me, before merging, that none of my PRs would move my score. reasoning_blocks feeds a dimension Claude Code doesn’t currently have. file_changes and effort_usage don’t feed any scored dimension. Merging them makes the data correct; it doesn’t make it count, and wiring it into scoring moves everyone’s numbers, so it isn’t a same-day follow-up.

He didn’t have to say that. I’d have found out eventually, in the least charitable possible way — by rescanning and seeing nothing move. Saying it up front costs something and buys nothing except that the next exchange starts from a true premise.

That’s the whole thing, really. Politeness is free, so it carries no information. Good faith is expensive, which is why it works. A sociopath can be unfailingly polite. What’s hard to fake is doing the work before making the claim: a patch with tests and before/after numbers attached, a stated kill condition for your own change (“if the allowlist was deliberate defense rather than oversight, this PR is wrong and I’d rather know”), and an admission when the change does nothing for you.

His version of paying that cost was a review question I’ve been thinking about since. I had counted subagent activity in one field with a stated reason, excluded it in another with a stated reason, and counted it in a third with no reason at all. His note: given the comparability argument you’re making, I’d rather it be a stated choice either way than an accident.

Intended but unstated is indistinguishable from accidental. That’s a code-review principle, and also a conversational one.

Which is just eventual consistency again

I argued recently that eventual consistency isn’t a metaphor for how distributed teams work, it’s a structural description. Independent nodes take local writes, diverge, and converge at the boundaries through explicit contracts.

This exchange is that, with two nodes and a pull request as the contract.

Neither of us had the whole picture. I could see my own transcripts and had no visibility into the scoring; he could see the distribution across all users and had no visibility into why one person’s worktree-based fan-out was invisible. Both local views were correct and neither was sufficient. The divergence wasn’t a failure state — it was replication lag, and the PRs were the anti-entropy protocol.

Convergence didn’t require either of us to have been right at the start. It required the writes to be legible enough to merge: small diffs, stated reasoning, verifiable numbers, and an explicit note when a change did nothing.

I said in that piece that integration is where all the residual difficulty concentrates, and that owning the merge is the remaining hard problem. I meant it about software fleets. It turns out to apply to arguments.

Thanks to @grahac for taking the patches, for the ones he improved on, and for telling me up front that they wouldn’t help my score.

Still a zero in Planning, incidentally. I don’t use plan mode and I don’t write plan files, so that one is measuring me accurately. Some zeros are just true.

cmux, eight weeks later: the two-hop PATH trap

Gregory Golberg voitta , , , ,

A June post covered getting cmux set up so agent panes survive a reboot. Since then the setup has been running continuously, and three things went wrong that were worth filing (#30, #31, #32). Here is what held up and what did not.

How teammate tabs actually work

cmux claude-teams gives each teammate its own watchable cmux tab by impersonating tmux. It drops a shim at ~/.cmuxterm/claude-teams-bin/tmux:

#!/usr/bin/env bash
exec "${CMUX_CLAUDE_TEAMS_CMUX_BIN:-cmux}" __tmux-compat "$@"

and sets $TMUX to a synthetic socket path. No tmux server exists anywhere. Claude Code thinks it is talking to tmux; cmux answers, and each new-window becomes a tab.

It works well. tmux -V returns tmux 3.4, and tmux list-windows enumerates your cmux workspaces:

0 m&a
1 voitta
2 agent-teams
3 debedb

The catch is that the whole thing rests on PATH resolution, in two places.

Hop one: which tmux wins

If the launching process resolves tmux to real Homebrew tmux instead of the shim, real tmux tries to connect to a socket that was never a socket, and teammate spawn breaks outright.

On this machine Homebrew sat at PATH position 11 and the shim at 26. Both sources pushing it there were self-inflicted: my own cmux.json command re-prepended /opt/homebrew/bin, and so did .bash_profile. The fix is to prepend the shim directory in the workspace command.

Worth noting for anyone copying the June post: on cmux 0.64.16 cmux claude-teams now puts the shim at position 1 itself. The cmux.json prepend is belt-and-braces today, not the load-bearing fix. Which matters, because it is not what was actually broken.

Hop two: the shim’s own cmux

Look at the shim again. It execs bare cmux. And the cmux binary lives at /Applications/cmux.app/Contents/Resources/bin/cmux, which is not on a normal login shell’s PATH:

$ env -i HOME=$HOME /bin/bash -lc 'command -v cmux'
$

So winning hop one buys you nothing if hop two loses:

$ env -i HOME=$HOME /bin/bash -lc \
    'export PATH="$HOME/.cmuxterm/claude-teams-bin:$PATH"; tmux -V'
/Users/gregory/.cmuxterm/claude-teams-bin/tmux: line 3: exec: cmux: not found

One symlink fixes it:

ln -s /Applications/cmux.app/Contents/Resources/bin/cmux ~/.local/bin/cmux
$ env -i HOME=$HOME /bin/bash -lc \
    'export PATH="$HOME/.cmuxterm/claude-teams-bin:$PATH"; tmux -V'
tmux 3.4

I had filed that symlink as an ergonomics nit — scripts otherwise need CMUX="${CMUX_BUNDLED_CLI_PATH:-/Applications/…/cmux}". It was not a nit. A shim on PATH whose own dependency is off PATH fails in a way that reads as a tmux problem.

The diagnostic that saved the most time

A queued teammate and a shadowed shim look identical from outside: the pane sits there, nothing tabs. They are distinguished by one check.

If ps shows no __tmux-compat process ever appeared, the spawn never reached tmux, so PATH is not your problem. In my case the launcher pane was in manual mode on and the teammate sat at ◯ indefinitely, having called nothing at all. I would have spent the evening on PATH.

The other habit worth keeping: read the live process environment, not the shell’s.

ps -Eww -o command= -p <pid> | tr ' ' '\n' | grep -E '^(TMUX|PATH)='

A pane’s shell will happily report a PATH the long-running agent inside it never saw.

What about reboot survival?

That part held. Across a real reboot on 0.64.16, all 7 panes came back on their exact resume commands, none silently dropped — including a teams-named pane, which now carries an agent-hook resume binding it did not have before.

One caveat the June post did not mention: identity is not preserved. Comparing session-com.cmuxterm.app-previous.json against the live session file, workspaceId and panel id share zero values across a restart. Restore recreates everything by replaying resume bindings. That is the mechanism behind rescued tabs landing on Claude Code’s “is this a project you trust?” prompt — folder trust was scoped to a workspace id that no longer exists.

If you go diffing those files yourself, the identity key is workspaceId, not id. Key on id and every workspace collapses to None, which reads as “ids are stable” — precisely backwards. I made that mistake on the first pass.

Net

Two config lines, both one-time:

ln -s /Applications/cmux.app/Contents/Resources/bin/cmux ~/.local/bin/cmux
# and in cmux.json's teams command:
export PATH="$HOME/.cmuxterm/claude-teams-bin:$PATH"

The setup from June is still the setup. What eroded was the environment around it — which is the recurring theme with long-lived agent sessions: nothing breaks, things merely get reordered underneath you.

Design Patterns Are Darmok

Gregory Golberg method-and-apparatus, projects/method and apparatus, voitta , , , ,

There’s a Star Trek episode — “Darmok” — where Picard is stranded with an alien captain whose language the universal translator can’t crack. It renders every word and none of the meaning, because the Tamarians speak entirely in allusion. “Darmok and Jalad at Tanagra” isn’t a sentence; it’s a pointer to a shared myth — two strangers who became allies by facing a common enemy. The words are just the address. The meaning lives in a story you either share or you don’t.

The usual read is that this is gloriously alien. It isn’t. It’s your last standup.

“Wrap it in a Singleton.” “Put a circuit breaker on that call.” “It’s a strangler-fig migration.” Each of those is Darmok — one token standing in for a paragraph of hard-won situation: one instance, global access, lazy init, and the testing pain you’ll come to regret; the downstream call keeps failing, so stop hammering it, fail fast, recover later. You didn’t describe the situation. You pointed at it. And it only worked because the engineer across the table had read the same paragraph.

That is what a design pattern is. The Gang of Four didn’t invent Singleton or Observer — those situations already existed, painfully, unnamed. What they did was name them, so engineers could stop describing and start invoking. The name is a compression codec. It only decompresses on the far end if the receiver holds the dictionary.

Umberto Eco spent a career making this precise: a sign carries no meaning on its own, only inside a shared code. Programmers rediscovered the idea, called it a “pattern catalog,” and skipped the semiotics reading list. Same insight, fewer footnotes.

Which is the part the episode actually cares about — and the part we forget every time we reach for jargon. Darmok’s whole tension is that metaphor-language fails on outsiders. Picard can’t parse the Tamarian captain, not until they’ve fought the same beast side by side — at El-Adrel — and built the shared referent between them. Only then does “Darmok and Jalad at Tanagra” finally mean something to him. A pattern name handed to someone who never learned the pattern isn’t communication — it’s noise in a confident voice. Every piece of jargon is a bet that the referent is shared. When the bet is wrong: Shaka, when the walls fell. (That’s the Tamarian for it all fell apart — and if you didn’t already know it, you just felt exactly the failure I’m describing.)

So here’s why I’m thinking about a 1991 Star Trek episode. We are minting a new pattern language right now, in real time, for a situation only a few years old: running work as a fleet of AI agents.

The last piece in this series handed you a fistful of these without flagging them. Own the merge. Team of rivals. Eventual consistency of the vision. Merge versus select. Each is a Singleton-in-the-making — a paragraph of situation we’ve all started hitting, crushed toward a token so we can stop re-describing it every time. “Own the merge” is three words for execution got cheap, integration didn’t, and the scarce human work is now the reconcile step. That’s a lot of paragraph for three words. It only lands because — if you read the last piece — you now share the referent.

And that is the obligation the pattern quietly hands you. A pattern language is worthless until the community holds the dictionary, which means the naming and the teaching are the same act. You can’t coin “own the merge” and walk off; you have to hand over the paragraph first. It’s why the Gang of Four wrote a book and not a glossary. It’s why a good entry in a shared skills library is three pages of when-and-why, not a one-line definition. The token is the payoff. The paragraph is the price.

We’re early. The territory of agent-fleet work is mostly unmapped; most of its patterns have no names yet, and some don’t even have paragraphs. This series is me trying to write a few of the paragraphs, so the tokens have somewhere to land.

Mirab, with sails unfurled.