Shahin Kiassat — Blog

A live TUI in the AI era

Thu, 16 Jul 2026 00:00:00 GMT

Somewhere around 2025, the most advanced software interface on your machine quietly became… a terminal app. Claude Code, opencode, gemini-cli, codex — the AI tools everyone actually uses all ship as TUIs: live panes, streaming transcripts, spinners, modals, keyboard everything. Not a web dashboard in sight. The web spent fifteen years teaching us that serious UI means a browser; the agent era spent about six months un-teaching it.

The reasons are practical, not aesthetic — though the aesthetic isn't hurting. A TUI runs where the work is: inside the SSH session, the container, the repo. It has no port to forward, no build pipeline for its front end, no login page. It starts in milliseconds, streams by nature, and puts your hands where a developer's hands already are.

So: you're sold, and you want one for your own tool — live, interactive, the works. I've now built this twice — once in C#, once in Go, for the same system, my agent orchestrator — which qualifies me to give you the tour with receipts. It ends with the combination I actually ship, and a running example you can attach to.

What .NET gives you: Spectre.Console, honestly

If you live in .NET, the answer to "how do I make my console output not look like 1997" is Spectre.Console, and it deserves its reputation. Tables, trees, panels, progress bars, prompts, markup like [green]pass[/] — output that looks designed with almost no effort. And for live dashboards it has Live rendering and a Layout system:

var layout = new Layout("root").SplitRows(
    new Layout("header").Size(5),
    new Layout("body"),
    new Layout("footer").Size(3));

await AnsiConsole.Live(layout).StartAsync(async ctx =>
{
    while (running)
    {
        layout["body"].Update(RenderTranscript());
        ctx.Refresh();
        await Task.Delay(100);
    }
});

Conductor's built-in dashboard is exactly this, and it's genuinely good: a full-screen live view with a stage sidebar, a streaming transcript, gate timers, pop-out modals for thinking/output/git. Spectre rendered all of it without complaint. If your TUI is a dashboard with occasional keys, stop reading, use Spectre, be happy.

Now the audit. Because the moment your TUI becomes an application — focus, modals, scrolling, editing — you discover what Spectre is not. Spectre is a rendering library, not an application framework:

No component model. A panel doesn't own state or handle input; it's a thing you draw. Composition means functions that return renderables, and every piece of interactivity lives somewhere else, by hand.
No input system. There's no event loop, no focus, no "the modal has the keyboard now". Conductor's dashboard hand-rolls it: a ConcurrentQueue<ControlAction> fed by a raw key-reader thread, a Modal enum, manual scroll offsets, and a lock around the buffers so the UI thread is the only reader. It works — but I wrote a tiny, bespoke, undocumented UI framework and buried it in a dashboard class, which is exactly the code smell it sounds like.
No reactivity. You poll and redraw on a timer, or you build your own invalidation. Ten-line demos redraw everything at 10 Hz and shrug; fuller screens start to shear and flicker if you're careless.

There is a retained-mode alternative — Terminal.Gui, an honest widget toolkit with focus and events. But its native aesthetic is dialogs, menus and text fields: a Turbo Vision descendant, forms-first, while the thing the AI era wants is a live streaming dashboard with vim keys. You can bend it there; you'll be bending.

So .NET's real position: superb drawing, bring-your-own-architecture. Which raises the question — what are the tools that nailed the live TUI using?

How the AI tools actually do it

Two answers dominate, and neither is a coincidence.

Ink — React for the terminal, and the machinery under Claude Code. Components, props, hooks, and a flexbox layout engine (Yoga) targeting character cells. If you know React you already know Ink; useState + useEffect on a streaming API and the transcript renders itself. The snapshot-testing story (ink-testing-library) is the best in the field. The tax is the one you'd guess: a Node runtime shipping inside your CLI, and React's reconciliation overhead between you and the screen.

Bubble Tea — Go, and the engine of an entire generation of terminal tools (opencode among them, plus lazygit-adjacent everything from the charm ecosystem). It implements the Elm architecture, which is three types and a promise:

type Model struct{ /* ALL the state, in one place */ }

func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd)  // fold a message into the next state
func (m Model) View() tea.View                            // render the WHOLE screen from state

Every keypress, resize, tick and network event is a Msg. Update is the only place state changes. View is a pure function from model to screen — no invalidation, no dirty flags, no "who redraws this panel": the screen is a function of the state, recomputed each pass, diffed by the runtime. Side effects (HTTP calls, timers) are Cmds that run off-loop and come back as messages. It's the same discipline as the reducer in my trading engine — one queue, one fold, effects at the edges — which might explain why I took to it: it's the deterministic kernel, wearing eyeliner.

And Go itself keeps winning this niche for reasons that have nothing to do with language aesthetics: go build emits one static binary — your TUI is a 6 MB file that runs on a bare server with no runtime conversation whatsoever; cross-compiling for the platform matrix is GOOS=linux go build; goroutines plus channels make "pump three streams into the event loop" the boring case; and Lip Gloss gives Bubble Tea a styling layer Spectre users would recognise and envy slightly.

The actual question: your backend is .NET

Here's the situation this post exists for. The system worth watching — the orchestrator, the engine, the pipeline — is C#. It's staying C#. Nobody is rewriting a working backend because a UI library is nicer somewhere else. Meanwhile the best live-TUI toolchain is in Go. Choose one language and you compromise a layer; the answer is to stop treating it as one program.

Split it. The .NET process owns all state and does all work. The TUI owns nothing: it renders events and sends commands. And the wire between them is the most boring thing available:

Server-Sent Events for backend → TUI. One direction of truth, auto-reconnect semantics that amount to "GET it again", and — this is the killer feature over WebSockets for this job — curl -N is a valid client. When something looks wrong you read the stream with your eyes. No handshake upgrade, no framing, no client library.
Plain HTTP POST for TUI → backend. Commands are small, rare and request/response shaped. They were never streaming's problem to solve.

This is Conductor's production shape: the C# orchestrator exposes a small control plane; a Go companion app attaches to it over SSE — from another terminal, another machine, or a phone over Tailscale.

The .NET half is now embarrassingly small

.NET 10 made SSE a first-class result type, which deletes what used to be a page of hand-rolled text/event-stream plumbing:

app.MapGet("/run/events", (CancellationToken ct) =>
    TypedResults.ServerSentEvents(sim.Subscribe(ct)));

app.MapPost("/run/command", (Command cmd) =>
    sim.Apply(cmd.Action) ? Results.Ok() : Results.BadRequest());

An IAsyncEnumerable<SseItem<T>> in, a correct event stream out. Behind Subscribe there's a broadcast hub of maybe thirty lines: a Channel<RunEvent> per subscriber, TryWrite fan-out, and a ring buffer of recent events replayed to every new subscriber so a freshly attached TUI paints a full screen instantly instead of starting from a blank stare. Late joiners, reconnects after Wi-Fi blips, three TUIs at once — all the same code path.

The Go half is a fold

The TUI's entire architecture is: one goroutine reads the SSE stream and turns lines into messages; the Elm loop folds them.

case eventMsg:
    m = m.apply(msg.ev)        // fold: stage board, feed, status
    return m, m.wait()         // re-arm: "give me the next message"

case tea.KeyPressMsg:
    switch msg.String() {
    case "p": return m, sendCommand(m.url, "pause")
    case "r": return m, sendCommand(m.url, "resume")
    case "q": return m, tea.Quit
    }

apply updates a stage board (· pending, ▶ running, ✗ failed, ✓ delivered) and appends to the feed; View re-renders everything from the model; Lip Gloss joins the panels. There is no synchronisation anywhere in the UI — the network goroutine and the render loop touch nothing shared, because everything crosses as a message. Connection drops? The reader reconnects with backoff and sends a connMsg{false}; the header shows ● offline; state keeps folding when the stream returns. The TUI is, deliberately, the dumbest process I own — and therefore the one that never breaks.

Try it

The companion sample is the whole pattern in two small standalone halves — a .NET 10 backend simulating a gated delivery run (agent chatter, a lying agent caught by its gate battery, a fix session) and the Go TUI:

cd backend && dotnet run      # terminal 1 — the control plane
cd tui && go run .            # terminal 2 — the face

That's it running — the red FAIL line is the scripted lying agent being caught by its gate battery, and everything below it is the fix session cleaning up. Now be cruel to it, because the cruelty demonstrates the architecture: kill the TUI mid-run — the backend doesn't notice, and reattaching repaints the full board from the replay ring. Press p and watch the backend pause while the stream stays live — pausing is backend state, not UI state; a second attached TUI shows it too. And when you want to see the truth without any UI at all: curl -N http://127.0.0.1:5058/run/events. The face is optional. The system is not.

What it costs, honestly

Two toolchains in one repo, with the idiom tax that implies — a .NET engineer touching the face needs a day of Elm-architecture acclimatisation (it's the good kind of weird). The wire contract needs the discipline any API needs: version it, tolerate unknown fields, never rename in place — the TUI treating unknown events as "something to display verbatim" has quietly absorbed several backend changes. TUI testing is thinner than web testing — Update-function unit tests are easy and good, "does it look right at 83×41" is still eyeballs. And SSE buys its simplicity by being one-way; if your UI's commands are chatty and latency-sensitive, that's the actual argument for WebSockets, so use them with a clear conscience.

None of these has made me miss the alternative — a browser dashboard for a system whose entire audience lives in a terminal, or a C# TUI framework I'd have to invent first. The AI tools made the terminal the serious UI surface again. Meet it with the stack that's serious about it: your backend where it is, in .NET — and a face that's a single binary, a pure fold, and one curl-able stream away.

Runnable, attachable version: go-tui-dotnet-backend in blog-code — the .NET 10 SSE backend and the Bubble Tea face, each half standalone. The real thing: Conductor.

Designing a deterministic kernel

Thu, 16 Jul 2026 00:00:00 GMT

At 14:32 on a Tuesday, the engine sold. Nobody told it to. The strategy looked right, the risk numbers looked right, and yet: sold. So you do what everyone does — you re-run the day to watch it happen.

It doesn't happen.

Same code, same data, different behaviour. Congratulations: your system has interleavings, and one of them fired on Tuesday and a different one fired just now. There is no bug to find because there is no execution to inspect. The behaviour lives in the gaps between callbacks, and the gaps shuffle themselves every run.

This post is about the shape that kills that entire class of mystery. I built it for a trading engine — an environment where "we can't reproduce Tuesday" costs actual money — but nothing in it is about trading. It's about any system that reacts to events and must be able to answer for itself afterwards.

The problem, laid out properly

An event-driven system accretes naturally into this:

market data arrives in a broker callback, which updates some fields and maybe fires an order,
a timer wakes up every second to check drawdown,
order fills land on another callback, on another thread,
and an async continuation from the last HTTP call resolves whenever it feels like it.

Each piece is individually reasonable. Collectively they have no defined order. The fill from bar 41 can arrive while the timer is halfway through reading state that bar 42 is halfway through writing. Two runs over identical data interleave differently, so testing proves little and replaying proves nothing.

The usual patch is a mutex and an apology. The actual fix is structural: build the system so there is only one place where anything happens.

The shape

tape event ─► queue ─► Kernel.Decide (PURE) ─► (state', effects[])
                           │                          │
                           ▼                          ▼
                      StepRecord ─► journal      effect executor (the ONLY I/O)
                                                 venue feedback (fills, account) ──┐
                                                     re-enqueued via the queue ◄───┘

Four parts, four jobs, no overlaps:

The tape is wherever events come from — recorded bars on disk, or a live socket feed. The kernel cannot tell the difference, and that indifference is the whole point: the backtest and the live path run through the same driver. There is no replay-only fork of the logic to drift out of sync.

The reducer is one pure function:

EngineDecision Decide(EngineState state, EngineEvent evt);
// EngineDecision = (EngineState State, IReadOnlyList<Effect> Effects)

Every decision the system will ever make goes through this signature. It does no I/O, reads no clock, mints no ids. It takes the world as a value and returns the next world as a value, plus a list of intentions — SubmitOrder, ClosePosition, RecordDecision — as data.

The executor is the only component allowed to touch reality. It walks the effect list and does the dirty work: talks to the venue, writes to the event bus, updates the progress sink. Crucially, when reality answers back — a fill, an account update — the executor doesn't handle it. It wraps the answer in an event and puts it on the queue, where it goes through the same front door as everything else.

The journal gets one record per processed event: sequence number, sim-time, the event itself as JSON, the effects it produced, and a snapshot of the risk state. It is not logging. It's the single source of truth that the report, the export, and the live monitor are all projections of.

The loop

The driver that pumps it all is small enough to hold in your head:

foreach (var tapeEvent in tape)
{
    queue.Enqueue(tapeEvent);

    // Drain this event AND every feedback event it triggers
    // before pulling the next one from the tape.
    while (queue.TryDequeue(out var evt))
    {
        var decision = kernel.Decide(state, evt);   // pure
        state = decision.State;

        journal.Append(BuildStepRecord(++seq, evt, decision, state));

        foreach (var effect in decision.Effects)    // the only I/O
            await effects.ExecuteAsync(effect, ct);
    }
}

The line that earns its keep is the inner while. Call it drain-before-advance: when a bar produces a SubmitOrder, and the venue answers with a fill, that fill goes back onto the same queue — and is fully processed before the next bar is pulled from the tape. Consequences never race their causes. However asynchronous the outside world is, inside the kernel there is exactly one total order of events, every run, forever.

Without that rule, bar N+1 races the fills of bar N and you're back to interleavings. With it, the system is single-file: one event, one decision, one journal record, next.

Determinism is a discipline, not a property

Here's the uncomfortable part. You don't get byte-identical replays by declaring the reducer pure. You get them by hunting down every leak, and the leaks are sneakier than you'd think. A tour of the ones that actually bit me:

The id mint. Deep inside position tracking, something called Guid.NewGuid() to label a new position. Perfectly innocent — and every replay now produces different journal bytes, because the ids differ. The fix was to stop minting: the position id is the order id, which arrived on the event, which came from the edge. Rule: if the kernel needs an id, the id travelled in on the event.

The clock. DateTime.UtcNow in decision code means replays disagree with history by definition. Time is data: every event carries the time it occurred, and that is the only "now" the kernel is allowed to know. This has a lovely side effect — a year-long backtest experiences a year of sim-time in minutes, and nothing inside can tell.

The culture. The journal serialises decimals. 12.5m.ToString() is "12.5" on my machine and "12,5" on a machine that thinks in commas — different bytes, broken diff. Everything the journal writes is formatted with the invariant culture, because the determinism contract extends all the way down to ToString.

The impure question. Some decisions genuinely need outside knowledge — is there a news embargo right now? Is it the weekend? You can't call a news service from a pure function. The move: the edge computes those verdicts at event time and attaches them to the event itself. The reducer applies verdicts; it never asks questions. Purity is preserved, and so is the audit trail — the journal shows exactly which verdicts the decision saw.

Each of these is enforced by tests now, because each of them will be reintroduced by someone (me) innocently improving something (anything). A purity test that replays a fixed tape twice and compares hashes is the cheapest insurance I own.

Config is not state

A subtler design decision: what doesn't go in EngineState. Risk limits, sizing policy, symbol metadata — constant for the whole run — live in a KernelConfig the kernel closes over:

public sealed record KernelConfig(
    ConstraintSet Constraints,
    RiskProfile Profile,
    SizingPolicyOptions Sizing,
    Func<Symbol, SymbolInfo> ResolveSymbol,
    int Seed);

Only time-varying data — positions, drawdown, equity, protection status — is state. The split keeps state small enough to snapshot and reason about, and it makes the most useful operation in the whole system embarrassingly cheap: same tape, different config. That one sentence is "re-run this backtest with a different risk profile". No new data plumbing, no export/import, one function call with a different second argument.

Risk gets a veto

Inside the reducer, in front of every order, sits a gate. A strategy doesn't submit orders; it proposes them, and the proposal passes through a pre-trade gate that owns sizing and the account's survival constraints — daily, weekly, monthly and total drawdown, checked in severity order.

Reject means reject: the journal records a decision event with the reason, and no effect reaches the venue. And when equity breaches a limit, the gate's big sibling takes over: the state enters protection mode, every open position gets a close effect, and nothing opens again until the boundary that clears it (next day, next week) rolls past — also an event, also journaled.

The gate produces one more thing while it's at it: a self-describing sizing record — equity at gate time, drawdown scaling, raw and clamped lot size — written into the journal. When a position is a quarter of the size you expected, the answer is in the record, not in a debugger at 2 a.m.

Risk-as-veto only works because of the funnel. When every order passes through one pure function, "nothing bypasses risk" is an architectural fact, not a code-review aspiration.

What it buys

Replay as a debugger. Any surprising decision can be re-run with the exact state that produced it. "Why did it sell at 14:32?" stopped being a mystery and became a query: pull the step record, load the state, step through the reducer. The answer takes minutes and is always there.

Diff as a regression test. Same tape + same config ⇒ bit-identical journal. So a refactor's safety check is: replay, hash, compare. If the hash moved, behaviour moved — and the journal diff shows exactly which step diverged first. The demo in the companion repo does this in three lines of output:

replay 1 sha256 : 89F7787232D7CE37
replay 2 sha256 : 89F7787232D7CE37
byte-identical  : True

A backtester that proves something. Because live and backtest share the driver, a backtest exercises the code that trades — not a parallel implementation with parallel bugs. The only swapped part is the tape.

CI without credentials. A simulated venue at the executor's edge plus recorded tapes means the full decision path runs in CI, deterministic and credential-free, on every push.

What it costs

The decision path is deliberately single-threaded: one event at a time, in order. For a swing-trading engine, that's nothing — the queue idles between bars. If you need microseconds, a funnel with a journal write per event is not your design, and I'd point you at the LMAX Disruptor literature instead — same religion (single writer, event log), different performance class.

The journal grows. One record per event, with event and effects as JSON, adds up; you'll want retention rules and compaction eventually. I consider the disk cheap and the answers priceless, but it's a real line item.

And the purity contract needs guarding. It is not self-enforcing. The type system won't stop a colleague — or you, in eleven months — from adding an innocent DateTime.UtcNow. The replay-hash test will. Write it the same day you write the reducer.

The pure function was the idea. The queue, the journal and the discipline around them are what made it an engine — I wrote about the underlying philosophy in a trading engine as a pure function, and this post is the machinery that philosophy actually runs on.

Runnable, distilled version: deterministic-kernel in blog-code — records a tape, replays it twice, proves the journals byte-identical, then reruns it under a different config for free.

Fast event-driven IPC in .NET, with ZeroMQ and NetMQ

Thu, 16 Jul 2026 00:00:00 GMT

Sooner or later two of your processes need to talk. Properly talk — not "poll a REST endpoint every second", but events, as they happen, at rate. Market ticks into a trading engine. Telemetry out of a game server. Frames between a capture process and an encoder.

The industry reflex is to reach for a broker: RabbitMQ, Kafka, Redis pub/sub. Now you have infrastructure — something to install, monitor, patch and explain to the on-call rota — standing between two processes that might be on the same machine. For durable, cross-team, audit-me messaging that's a fine trade. For "process A must feed process B, fast, now", it's a mainframe to deliver a pizza.

There's a forty-year-old idea sitting one abstraction lower: just sockets — but sockets that know messaging patterns. That's ZeroMQ. This post is about using it from .NET, where the story is unusually good, and about the sharp edges you'll want to know about before they eat your messages.

What ZeroMQ actually is

The name misleads in both halves: there's no queue server, and there's no broker of any kind. ZeroMQ is a library that gives you sockets with opinions. They look like BSD sockets, but:

they carry messages (discrete frames), never byte soup — no length-prefix parsing, no "did I get half a message?",
each socket runs its own background I/O and reconnects forever — you can start the client before the server, unplug things mid-run, and the socket quietly heals,
each connection has an internal queue with a cap (the high-water mark), and — this is the part to tattoo somewhere visible — what happens when that queue fills is decided by the socket type,
and each socket type implements a pattern: pipeline, broadcast, request-reply, async routing.

And NetMQ is the reason .NET people get to be smug about it: a complete, mature port of ZeroMQ in pure C#. Not a P/Invoke wrapper — a port. One PackageReference, no native binaries, no platform matrix. It speaks ZMTP on the wire, so a NetMQ process happily talks to a libzmq process written in C, Python or Go.

dotnet add package NetMQ

That's the entire infrastructure story. Nothing to install, nothing to monitor, nothing between your processes but TCP.

The vocabulary

Four patterns cover almost everything. The table you actually need is the last column — what each socket does under pressure:

Pattern	Shape	Delivery	When the queue is full
PUSH → PULL	pipeline	round-robin to workers, fair-queue in	sender blocks (backpressure)
PUB → SUB	broadcast	every subscriber gets a copy	drops, silently
REQ ↔ REP	rigid request/reply	strict alternation	blocks
DEALER ↔ ROUTER	async request/reply	explicit addressing, any cadence	configurable

Two of those cells run the show. PUSH blocks — a slow consumer slows the producer, nothing is lost, the pipeline breathes. PUB drops — the show must go on, so a slow subscriber loses messages and nobody tells you. Not an exception, not a return code, not a log line. We'll watch it happen below.

The rule that falls out, and the single most useful sentence in this post: broadcast telemetry with PUB/SUB; move entitlements over something that blocks. A missed price tick is Tuesday; a missed fill is a lawsuit.

A pipeline, measured

The classic ZeroMQ pipeline is fan-out/fan-in:

ventilator (PUSH, bind) ──► workers ×3 (PULL → PUSH) ──► sink (PULL, bind)

The companion sample wires this up over real TCP on localhost and pushes 200,000 messages through both hops. The ventilator is four lines:

using var push = new PushSocket();
push.Options.Linger = TimeSpan.FromSeconds(30);   // remember this line
push.Bind("tcp://127.0.0.1:15961");

for (var i = 0; i < 200_000; i++)
    push.SendFrame(payload);

On my laptop, one unscientific evening:

payload    16 B : 200,000 / 200,000 msgs through 2 hops in 0.77 s — 259,761 msg/s (4 MB/s)
payload 1,024 B : 200,000 / 200,000 msgs through 2 hops in 5.62 s — 35,566 msg/s (35 MB/s)

A quarter of a million small messages per second, through two hops and four sockets, with zero tuning, on a laptop that was also running Spotify. For same-box IPC you will run out of ideas before you run out of throughput.

But look at the two rows together, because they teach the real lesson. At 16 bytes we're message-rate bound — the cost is per-message bookkeeping, and the bytes are irrelevant. At 1 KB we're shovelling 64× the payload but only going 7× slower — the cost curve is bending towards bandwidth bound. Your bottleneck is almost never "the transport". It's what you put in the messages — which, in a typical system, means serialization. A JSON encode per event will dominate everything ZeroMQ does. (The trick that follows from this: don't make it a per-message cost. Batch small events into one frame and amortise.)

The foot-gun tour

Every one of these is a demo mode in the sample, because every one of them got me or someone I respect.

The slow joiner

A subscription is not a local filter — it's a message, sent from SUB to PUB after connecting, and until it lands the publisher filters everything out at the sending side. So a publisher that starts blasting immediately loses its opening messages to every subscriber. How badly? On localhost, with the subscriber connecting as fast as it possibly can:

naive start    : received    0 of 1,000 events — the head of the stream is simply gone
handshake first: received 1,000 of 1,000 events

Zero. Out of a thousand. This is the most-reported "bug" in ZeroMQ's history and it is by design: PUB/SUB is a radio broadcast, not a mailbox. The fix is a start-of-day handshake — the subscriber says ready over a separate REQ/REP pair, and the publisher holds fire until it hears it. Fifteen lines, and part of the fifteen is a comment saying why.

The high-water mark

Each side of a connection buffers up to the HWM — 1,000 messages by default. PUSH responds to a full queue by blocking. PUB responds by dropping, and here's what that looks like when a publisher blasts 50,000 frames at a subscriber that dawdles just slightly:

published      : 50,000 frames of 128 B
received       : 2,000
dropped        : 48,000 — silently, at the high-water mark

Ninety-six percent of the stream, gone, no error anywhere. If you take one number away from this post, take that one. Raise Options.SendHighWatermark when bursts are expected, drain your subscribers fast — and never, ever put must-deliver data on PUB/SUB.

The vanishing tail

NetMQ's default linger is zero: disposing a socket discards whatever is still queued, instantly. Your process sends its last 2,000 messages, hits the end of using, and those messages evaporate — the demo lost exactly its tail until I set Linger before dispose. Symptoms: "the last batch never arrives", but only on fast runs. Set linger, or drain before dispose.

The threading rule

ZeroMQ sockets are not thread-safe, full stop. The blessed shape for a long-lived transport is to give the sockets a single home: a NetMQPoller owns them all and runs the loop, receive handlers fire on the poller thread, and any other thread that wants to send goes through a NetMQQueue<T> — a thread-safe funnel that the poller drains on its own thread.

In the trading engine this pattern came from, the transport then hands messages to the async world through two bounded System.Threading.Channels, and the bounds encode the semantics:

// market data: losing the oldest tick to a stall is fine — it's telemetry
Channel.CreateBounded<(string Topic, string Json)>(
    new BoundedChannelOptions(10_000) { FullMode = BoundedChannelFullMode.DropOldest });

// commands/executions: these are entitlements — block, never drop
Channel.CreateBounded<(byte[] Identity, string Json)>(
    new BoundedChannelOptions(2_000) { FullMode = BoundedChannelFullMode.Wait });

Two channels, two full-modes, and the PUB-drops/PUSH-blocks distinction from the socket table shows up again inside the process. The semantics of "what may be lost" isn't a transport detail. It's the design.

Buying determinism over a socket

Speed is the advertised feature. The feature I actually came for is stranger: you can build determinism on top of this, and most transports won't let you.

The setup: a trading engine in one process, its venue adapter in another (inside a broker platform I don't control). Bars flow one way, orders flow back. If both flows are free-running, bar N+1 can arrive before the venue has executed the orders that bar N produced — and every run of the same day interleaves data and commands differently. For an engine whose whole design rests on replaying any day byte-for-byte, that's fatal.

The fix is a protocol, not a transport feature — the lock-step loop:

the venue sends bar N with a sequence number,
then blocks until the engine replies bar_done echoing seq N, carrying every command that bar produced,
the venue executes those, echoes the executions, and only then sends bar N+1.

One total order of data and commands, enforced by the conversation itself. Same bars in, same interleaving, every run — across a process boundary.

The sample implements it with DEALER/ROUTER rather than REQ/REP, and the choice is instructive: REQ/REP hard-codes exactly one reply per request, but an engine might answer a bar with nothing, or with three commands and a status update. DEALER/ROUTER is the polite version of the same conversation — ROUTER prefixes each message with the sender's identity, so replies are addressed and several venues could share one engine:

// engine side: ROUTER frames arrive as [identity][payload]
var identity = router.ReceiveFrameBytes();
var json     = router.ReceiveFrameString();
// ... decide ...
router.SendMoreFrame(identity)                      // reply to *that* venue
      .SendFrame(Wire("bar_done", new { seq, commands }));

Yes, lock-step caps throughput at one bar per round-trip. For bars — even M1 bars across every major pair — that budget is laughable. Determinism costs latency you weren't using.

What I'd use it for, and what not

Reach for it when: processes on one box or one rack need events at rate; pipelines with natural backpressure; broadcast telemetry with many readers; a protocol of your own design (like the lock-step above) that a broker's opinions would fight.

Don't reach for it when: you need durability — ZeroMQ holds messages in memory; a crashed process's queue is gone. No replay, no consumer offsets, no audit log: that's Kafka's job, and the honest response to needing it is to use Kafka. Similarly the open internet edge (you'll want TLS, auth, and someone else's hardened listener) and org-wide integration fabric (the broker's governance is the feature, not the overhead).

One more honest cost: no broker means nobody is watching. There's no management console showing queue depths; observability is yours to build. The engine's transport counts bars in, commands out, executions back, and timestamps the last message — four counters and a clock, exposed on a status endpoint. Build them on day one; they're your only witnesses (the HWM certainly won't testify).

Runnable, measurable version: netmq-event-pipeline in blog-code — the pipeline benchmark, the slow joiner, the silent HWM drops, and the lock-step protocol, each as a one-command demo.

Gated delivery for a team of agents

Thu, 16 Jul 2026 00:00:00 GMT

Here is how a multi-stage delivery actually goes with a coding agent. You write a beautiful plan. You feed stage one to the agent. It works; you check it; fine. You feed it stage two. You wait. You alt-tab to something else. You come back to find it finished twenty minutes ago — or stuck, forty minutes ago. You check the work, you spawn the next session, you glance at the clock: 23:40. You are a highly trained engineer performing the duties of a while loop.

I built Conductor to be that while loop. It runs agent sessions unattended, one at a time, for hours — overnight is the normal case, not the war story. And every design decision in it flows from one axiom, which I'll state now and spend the rest of the post cashing out:

An agent's report of its own work is not evidence.

Not because agents lie maliciously. Because they are optimistic, occasionally confused, and rewarded — in some deep gradient-descent sense — for sounding finished. "All tests passing, the feature is complete" is a claim. The orchestrator's job is to be the auditor that never signs a claim without receipts. I've written before about the trust model in principle; this post is the machinery, end to end.

The automation surface nobody advertises

First, the enabling fact: you don't need an SDK, a browser harness, or PTY scraping to drive a coding agent. The CLIs ship a first-class headless mode:

claude -p "<prompt>" --output-format stream-json
opencode run "<prompt>" --format json

Prompt in, newline-delimited JSON out: every assistant message, every tool call, and a final result envelope carrying cost, token counts and an error flag. Which means an agent session is something Unix has known how to supervise for forty years — a child process with structured output.

The spawning code is boring, and every boring line is load-bearing:

var psi = new ProcessStartInfo(cfg.Command)
{
    WorkingDirectory = repoPath,
    UseShellExecute = false,
    RedirectStandardOutput = true,
    RedirectStandardError = true,
    RedirectStandardInput = true,
    StandardOutputEncoding = Encoding.UTF8,
};
foreach (var a in args) psi.ArgumentList.Add(a);   // never a concatenated string

ArgumentList, not an argument string — prompts contain quotes, newlines and JSON, and hand-quoting them for a shell is a bug factory with a night shift. Close stdin — headless agents shouldn't wait for input; some will anyway. Tee the raw stream to a file before parsing a single line — session-042.jsonl is the forensic record for when something goes weird, and parsers are lossy by design. And keep the parser tolerant: unknown event types become raw, never an exception, because the stream format is versioned by vibes.

Templates finish the job: the config holds ["-p", "{prompt}", "--output-format", "stream-json"], and the driver substitutes {prompt} and {sessionId}. Swapping Claude Code for opencode is a config edit. The orchestrator has one session class and two parsers, and genuinely does not care who's inside the process.

Kill means kill

One hard-won subclause. Agent sessions spawn children — build tools, test runners, dev servers — and some of them detach and escape the process tree. On Windows, even Process.Kill(entireProcessTree: true) misses those. Conductor puts every session in a Job Object with KILL_ON_JOB_CLOSE: close one handle and everything the session ever started dies with it.

The tuition for this lesson: a stray dotnet watch from session 12 held a file lock that failed the build gate in session 13, which spawned a fix session that could not possibly fix anything, which burned the stage's attempt budget, which stopped the run — all while the actual code was fine. An orchestrator that can't guarantee a clean battlefield between sessions will gaslight itself. Kill means kill.

Sessions don't pass or fail — they end ten ways

The next thing unattended operation forces on you: an exit code is nowhere near enough vocabulary. Conductor reduces every session to one of ten explicit outcomes, and the enum is worth reading like a poem about everything that can go wrong:

public enum SessionOutcome
{
    Advanced,      // gates green, new commits, ≥1 checkpoint newly DONE
    Progress,      // gates green, new commits, no new DONE — multi-session stage, fine
    NoProgress,    // gates green but nothing committed
    GatesRed,      // gates failed after the session
    Stalled,       // no output for stallMinutes — killed
    TimedOut,      // exceeded sessionTimeoutMinutes — killed
    AgentError,    // agent process exited with an error result
    LimitBackoff,  // usage/rate limit detected — waiting it out
    KilledByUser,
    Interrupted,   // conductor itself died mid-session (recovered on restart)
}

The point of the vocabulary isn't taxonomy for its own sake — it's that different outcomes get different next moves, and the difference is fault attribution:

Stalled / TimedOut — the agent's fault. Kill it, resume the same session with a bounded resume budget, and burn an attempt from the stage's allowance.
LimitBackoff — the world's fault. The backend said "usage limit reached"; punishing the agent for that is nonsense. Wait it out, resume, burn nothing. (Detecting this one is a regex over the output tail, because the refusal hides in free text rather than any structured field. I'm not proud of it, but it's load-bearing: misclassify a rate limit as an agent failure and your overnight run dies at the exact moment it's most useful — when you're asleep and the API is busy.)
GatesRed — actionable, and the evidence is already in hand. Spawn a fix session; more below.
NoProgress — the strangest one. Everything's green, the agent chatted amiably, and nothing changed in the repo. Counted against the stage, because three of those in a row means the plan and the agent have agreed to disagree, and a human should look.

A watchdog produces the first two: every output line stamps LastActivityUtc, and a supervision loop checks it against a stall limit and a wall-clock timeout. The cost envelope feeds a second budget — the result event's total_cost_usd accumulates per session, stage and run, so the loop stops when the money's gone rather than when the credit card notices.

The verdict: three witnesses, no testimony

Now the core of the trust model. When a session ends "successfully" — clean exit, no error flag — Conductor determines what actually happened using only things it can independently observe:

The gate battery — re-run the builds, tests, linters. Real commands, real exit codes, no summaries accepted.
Git — CommitsSince(startHead). Did the repo change? An agent that "completed the feature" without committing anything has completed nothing.
The tracker diff — the plan's checkpoints live in a tracker file; parse it before and after, and see which checkpoints newly flipped to DONE.

One line from the real log, because it summarises the whole philosophy:

verdict inputs: gates green · commits 3 · newly DONE [4.2] · dirty no

Gates green and commits exist and a checkpoint flipped ⇒ Advanced. Gates green and commits but no checkpoint ⇒ Progress. The agent's parting essay about its own excellence is not among the inputs. It's stored — it makes good reading later — but it decides nothing.

Note what this makes the agent's claim of "done": a hypothesis the orchestrator then tries to falsify, cheaply. Session says done → gates say otherwise → session was wrong, and the loop knows it before the human ever would. The wrongness gets caught in minutes, not discovered in review two days later.

Gates are a battery, not a script

The gates themselves deserve engineering care, because per-session gating means they run constantly. Conductor's GateRunner walks the configured gates in listed order with one scheduling rule: a gate marked non-parallel is a barrier; consecutive parallel gates run as one concurrent batch. So build runs alone, everyone waits — then tests, formatting and the docs check fan out together. There are two tiers: a fast tier after every session (seconds — the pulse check), and the full battery at phase boundaries (the physical). Optional gates can fail as warnings; per-stage filters keep irrelevant gates out of the loop.

That's four sentences of feature list with one purpose: keep the verify-everything loop cheap enough that nobody is ever tempted to skip it. A trust model you bypass under schedule pressure isn't a trust model. It's decoration.

Failure is an input: fix sessions

When gates come back red, the orchestrator doesn't retry with a hopeful "try again, but better". It records a debt — literally a PendingFix in the run state:

public sealed class PendingFix
{
    public int FromSession { get; set; }
    public string GateFailures { get; set; } = "";   // the ACTUAL failing output
    public string ProgressSummary { get; set; } = "";
}

— and the next session is a fix session whose prompt embeds the real failing gate output, the commits so far and what the last session claimed. The difference in outcome quality between "tests failed, please fix" and here are the four failing test names and their assertion messages is the difference between a coin flip and a mechanic. Evidence in, fix out.

Fix isn't the only specialist. Sessions come in kinds — Deliver for new work, Fix armed with failures, Resume (via claude --resume <session-id>) to continue an interrupted session with its context intact, and Audit at phase boundaries to review a whole stage's diff. Same process machinery, different briefs. A team of agents, in the only sense that currently works reliably: not five agents arguing in a group chat, but specialists across time, each handed exactly the context its job needs, each distrusted equally.

When the loop truly corners itself — resume budget exhausted, attempts gone — it consults a cheap second-model advisor with a compact dossier: outcome history, tracker state, the reason it's stuck. Continue, retry differently, or stop and ask the human. A second opinion at dead ends only; the loop's core stays deliberately dumb and auditable. Autonomy that knows when to stop being autonomous — the run status even has a NeedsHuman state, which is the system formally admitting you exist.

Built to be killed

Anything that runs for hours will be interrupted — Ctrl+C, reboot, power cut, or its own bug. Conductor treats that as a feature request: the entire run state is one JSON document, snapshotted atomically on every transition (write to temp file, rename over the old — the filesystem's one free transaction). Owed work is recorded as data: PendingFix, PendingResume, PendingPhaseGate, PendingAudit. Kill the process anywhere; conductor run reads the state and does whatever is owed. There's even an outcome for it — Interrupted — because dying mid-session is just another way a session ends, and the resume machinery treats it accordingly.

The companion sample compresses this whole post into a ninety-second demo: a three-stage delivery where the backend rate-limits stage one (backoff, no attempt burned), the agent lies about stage two (gates catch it, the fix session gets the evidence), a power cut lands between runs (atomic state resumes it), and the agent stalls on stage three (watchdog kills, retry succeeds). Its final self-report — which, unlike an agent's, you may believe, because it's a grep over verified output:

delivered 3/3 stages · sessions: 6 · lies caught by gates: 1 · stalls caught by watchdog: 1
resumed after crash: True

What this costs, honestly

You're coupled to stream formats that change without notice. The raw log plus the tolerant parser is the survival kit, not a nicety.

Your gates are your actual spec. The loop delivers whatever the battery accepts — it cannot want what you meant, only what you check. A weak battery plus a diligent agent yields confidently delivered garbage at impressive speed. Budget real time for gate quality; it's where the engineering went.

Sequential sessions are slower than a human juggling three terminals — on a good day, when the human is fresh. The orchestrator's day has no concept of fresh. It does the loop at 03:00 exactly as it does it at 09:00, watched from a phone if you're curious, and it never once believes the agent because believing was never in the loop.

That last property compounds. Each session ends as a SessionRecord — outcome, commits, checkpoints, cost, tokens, duration — so every run produces its own audit trail. After a few weeks you know things about your agents no anecdote could tell you: which stages burn attempts, where stalls cluster, what a stage costs. The loop doesn't just deliver unattended. It keeps the books.

Runnable, distilled version: gated-agent-delivery in blog-code — the full loop with a bundled fake agent, so it runs with nothing installed. The real thing: Conductor.

A trading engine as a pure function

Wed, 15 Jul 2026 00:00:00 GMT

There's a dirty secret in most algorithmic trading setups: the backtester and the live engine are two different programs. The backtest loops over candles in a for loop; the live engine reacts to broker callbacks, timers, and network weather. The strategy logic gets reimplemented — or "shared" through a leaky abstraction — and the result is a backtest that validates code which never runs, and live code that has never been validated.

I'm building a trading engine (Shamshir) where that split can't exist, because the core of the engine is a pure function:

public static (EngineState Next, IReadOnlyList<Intent> Intents)
    Reduce(EngineState state, MarketEvent evt);

State in, event in. New state out, plus a list of intents — open this position, move this stop, close everything. That's the whole kernel. No clock, no broker client, no database, no DateTime.UtcNow, no randomness. If it needs to know the time, the time is on the event.

Side effects live at the edges

Everything impure sits in thin adapters around the kernel:

A feed adapter turns broker callbacks (ticks, bar closes, order fills) into MarketEvent records and pushes them through the reducer.
An execution adapter takes the intents the reducer emits and turns them into real broker API calls — then feeds the results (fills, rejections) back in as new events.
A persistence adapter appends every event to a log (SQLite is plenty) before the reducer sees it.

The adapters are deliberately boring. All the decisions — every indicator update, every signal, every position-size calculation — happen inside the pure part, where they can be tested with nothing but values.

The backtest is not a second program

Once the engine is a reducer over events, backtesting stops being a separate implementation and becomes replay:

var state = EngineState.Initial(config);
foreach (var evt in recordedEvents)
    (state, _) = Kernel.Reduce(state, evt);

Feed it a year of recorded events and you have a backtest. Feed it this morning's events and you have a reconstruction of this morning. The code path is identical to live — same reducer, same indicators, same sizing, same risk checks — so a green backtest actually says something about the software that will trade.

The corollary is my favourite property of the whole design: any trading day can be replayed, byte for byte. When the engine does something surprising at 14:32 — and it will — I don't stare at logs guessing. I replay the event log up to 14:31, attach a debugger, and step through the exact decision with the exact state. "Why did it sell?" becomes a reproducible question.

Strategies propose. The governor disposes.

Shamshir targets prop-firm accounts, which come with unforgiving rules — FTMO-style daily drawdown and total drawdown limits. Breach them once and the account is gone. Rules like that are too important to live inside strategy code, which is exactly the code you rewrite most often.

So the kernel is split in two layers. Strategies emit proposals. A separate risk governor sits between proposals and intents, and its only power is veto and reduction:

// The governor can shrink or kill a proposal — never enlarge it.
var verdict = governor.Evaluate(state.Risk, proposal);
// verdict: Approved(sized) | Reduced(sized, reason) | Rejected(reason)

Daily drawdown, max total drawdown, exposure caps, and position sizing are first-class domain objects in the governor, not if statements scattered through strategies. A strategy can be wrong, greedy, or half-finished; the blast radius is capped by a small component that never changes and is tested to death. It's the same shape as a supervisor in an actor system — or, for that matter, an orchestrator that doesn't trust its agents: the thing that enforces the rules must be separate from the thing that does the work.

What testing looks like when the core is pure

The unit tests read like arithmetic. Build a state, apply an event, assert on the output — no mocks, no broker sandbox, no async ceremony:

[Fact]
public void Breaching_daily_drawdown_flattens_and_locks()
{
    var state = StateWith(equity: 98_950m, dailyStart: 100_000m); // -1.05%
    var (next, intents) = Kernel.Reduce(state, BarClose(...));

    intents.Should().ContainSingle(i => i is CloseAll);
    next.Risk.TradingLocked.Should().BeTrue();
}

Above that sits a simulation tier: full engine, synthetic or recorded feeds, no credentials required — so CI exercises realistic multi-day scenarios without a broker account anywhere in sight.

The costs, honestly

Purity isn't free. All engine state has to be explicit and serialisable — including indicator state, which is where third-party indicator libraries fight you. Multi-symbol, multi-timeframe indicator windows make EngineState a genuinely large object, and you have to be disciplined about it evolving. And this design optimises for correctness and replayability, not latency; if you're chasing microseconds, a pure functional core with an event log is not your architecture.

For a swing engine whose failure mode is "one bad day ends the account", the trade is obvious. The reducer gives you a backtest you can believe, a debugger that time-travels, and a risk layer that can't be bypassed — all from one decision about where the side effects live.

An agent session is not pass/fail

Wed, 15 Jul 2026 00:00:00 GMT

The first version of Conductor — my orchestrator for running coding agents unattended across multi-stage plans — judged every session the obvious way: did it succeed or fail?

That model survived contact with reality for about two days. What do you call a session that ran for forty minutes, kept the build green, and committed nothing? A session that made real commits but didn't finish the checkpoint? A session that died because the API rate-limited it? "Failure" lumps together things that demand completely different responses — and an unattended loop is its responses. Get the reaction wrong and the loop either gives up on plans it could have finished, or burns money re-running work that was never broken.

The taxonomy

Conductor now resolves every session to one of eight outcomes. None of them come from the agent's own report — they're computed from three independent signals after the session exits: the gate battery (build/tests/lint, re-run by the orchestrator, real exit codes), the git log (did commits appear?), and the plan tracker (did a checkpoint genuinely flip to DONE?).

Observation	Outcome	Response
Gates green, new commits, checkpoint flipped	`Advanced`	Next checkpoint, attempts reset
Gates green, new commits, nothing flipped	`Progress`	Another delivery session
Gates green, no commits	`NoProgress`	Fix session; attempt burned
Any required gate red	`GatesRed`	Fix session with the failing output embedded
No output for N minutes	`Stalled`	Kill, resume the same session
Hard time limit hit	`TimedOut`	Same as stalled
Backend says rate/usage limit	`LimitBackoff`	Wait, resume — no attempt burned
Session token budget exceeded	`RolledOver`	Fresh session with handoff — no attempt burned

Plus one park state that outranks them all: NeedsHuman. If the agent writes HUMAN: in its handoff, or a checkpoint flips to BLOCKED, or the loop detects two consecutive zero-output stalls, the run parks, publishes a report, and notifies me. More on why that's a success in a moment.

Whose fault was it?

The load-bearing distinction in that table isn't green versus red — it's agent-caused versus environment-caused.

Every stage has an attempt budget (expected sessions × a slack factor). Burn through it and the stage escalates. Early on, everything decremented that budget, and I watched a plan die overnight because the provider rate-limited for an hour and the orchestrator dutifully recorded strike after strike against a stage that had done nothing wrong.

So the taxonomy encodes blame. NoProgress and GatesRed are on the agent — they burn an attempt. LimitBackoff and RolledOver are weather — the loop backs off or rolls over with a handoff, and the budget is untouched. A rate limit is not evidence about the difficulty of the work.

RolledOver deserves a note, because naive token exhaustion is nasty: the session dies mid-edit with no summary and the next session inherits a half-finished mystery. Conductor watches spend, and at 80% of the budget it injects a cooperative nudge: stop opening new work, commit what's coherent, write the handoff. Exhaustion becomes a planned landing instead of a crash.

The outcome picks the next prompt

The second thing the taxonomy buys: the outcome determines what kind of session runs next, not just whether one runs.

GatesRed spawns a fix session whose prompt embeds the actual failing gate output — the agent starts from the compiler error, not from "something is wrong, please investigate".
Stalled doesn't start over; it resumes the same session (bounded per session), because mid-task context is expensive to rebuild.
Budget exhausted → an advisor — a second, cheap model — reads the history and picks from a closed vocabulary: retry, resume, skip, or human. It's consulted only at genuine dead ends, and its answer is validated against that vocabulary. Deterministic first, model second.

Parking is not failing

The early instinct is to treat "the loop stopped and asked for me" as defeat — the whole point was autonomy. That's wrong. For an unattended system the real failure modes are silent: retrying a doomed stage at 3am, or skipping past a wrong assumption baked into the plan. NeedsHuman is the loop recognising the limit of its evidence and saying so loudly, with a report of everything it knows. I'll take that over confident thrashing every time.

Autonomy for coding agents doesn't come from a better model or a cleverer prompt. It comes from the boring machinery around the model knowing exactly what just happened — and having a specific, evidence-based reaction to each way a session can end. Pass/fail was never going to carry that weight. A taxonomy does.

Call graphs lie about modern .NET

Wed, 15 Jul 2026 00:00:00 GMT

Ask the obvious question about any .NET service — what actually happens when POST /orders is hit? — and try to answer it with a call graph. You'll get exactly one hop:

[HttpPost]
public Task<IActionResult> Create(CreateOrderRequest req)
    => _mediator.Send(new CreateOrderCommand(req));   // ...and the trail goes cold

The call graph dutifully reports that the controller calls IMediator.Send. It cannot tell you that the real successor is CreateOrderCommandHandler, because nothing in the entire solution ever calls the handler. MediatR finds it by reflection at runtime. Statically, it's dead code with a day job.

And it's not just MediatR. Modern .NET has systematically replaced calls with conventions: DI containers construct your implementations, so nothing news them; MassTransit invokes your consumers when a message arrives, so nothing calls them; domain events dispatch to handlers the same way; pipeline behaviours wrap everything invisibly. The better your architecture — the more decoupled — the more your call graph degenerates into disconnected islands with Send and Publish at the shores.

This is precisely where humans onboarding to a repo get lost, and where coding agents hallucinate wiring that doesn't exist. The model sees Send(new CreateOrderCommand(...)), can't see the handler, and invents one.

Join, don't follow

DevContext — my tool for turning a .NET solution into a queryable code graph — deals with this by refusing to treat calls as the primary source of truth. Instead, the analyser runs separate Roslyn detections across the solution: endpoints, MediatR handlers, message consumers, EF Core entities, DI registrations, background workers, domain-event raises.

Then it builds edges by joining detections, the way you'd join tables:

_mediator.Send(new CreateOrderCommand(...)) is detected as a send of CreateOrderCommand.
class CreateOrderCommandHandler : IRequestHandler<CreateOrderCommand, OrderId> is detected as a handler of CreateOrderCommand.
Same message type on both sides → a Sends/Handles edge connects them.

No call exists between those two classes, and no call is needed. The message type is the foreign key. The same join works for events and their consumers, for AddScoped<IOrderRepository, OrderRepository>() connecting an interface to what the container will actually construct, and for entities reached through a DbContext.

An edge you can't cite is a guess

Joins are inference, and inference can be wrong — a message type with two handlers, an interface with three registrations. So every edge in the graph carries three pieces of honesty metadata:

Provenance — the file:line of the evidence on both sides.
Resolution — how the edge was derived: a Join, a raw Syntactic match, or full Semantic resolution.
Confidence — because "the only implementor of this interface" is a stronger claim than "one of three implementors".

This turns out to matter more for LLMs than for humans. A trace whose every hop cites its source is something an agent (or its orchestrator) can verify — open the file, check the line. A trace without citations is just more plausible-sounding text, and plausible-sounding text is the one thing models never run short of.

Not all edges are equally interesting

When the tracer walks outward from an entry point, it expands edges in a strict priority order — the semantic, intent-revealing edges first:

Priority	Edge	Meaning
0	`Sends`	command/event dispatch
1	`Handles`	mediator handler join
2	`Raises`	domain event raised
3	`Consumes`	bus consumer join
4	`ReadsWrites`	EF entity touched
5	`Resolves`	DI interface → implementation
6	`WrappedBy`	pipeline behaviour
7	`Calls`	plain method call

Raw Calls edges — the only thing a classic call graph has — come dead last. They're the noise floor: real, but rarely what you're asking about. The priority ladder is what makes a trace read like an explanation ("the endpoint sends a command, the handler raises an event, a consumer writes the entity") instead of a stack dump.

A few guards keep traces finite and honest: a depth limit, a fan-out cap per node, framework-boundary detection so the walk stops at ASP.NET internals instead of descending into them, and a revisit guard for cycles. A trace that tried to be complete would be as unreadable as the codebase; the job is to be truthful within a budget.

The point

I wrote before about giving agents a map instead of letting them re-explore the repo every session. The map is half the answer. The other half is the trace — and a trace is only worth feeding to a model if it survives the question "how do you know?". Build the edges from joins, make them cite file and line, and rank meaning above mechanics: that's the difference between a code graph and a very confident lie.

Point, don't re-explore: giving an LLM a map of your .NET repo

Tue, 14 Jul 2026 00:00:00 GMT

Every coding agent I've used has the same expensive habit: it re-explores the repository from cold at the start of every session. It greps, it opens files, it follows references, it rebuilds a mental model — and then the session ends and all of that context evaporates. Next session, it does it again.

For a small project that's fine. For a real .NET solution — dozens of projects, layers of dependency injection, MediatR handlers wired up by convention — it's slow, costs a fortune in tokens, and the model still gets the wiring wrong.

The idea

What if the first thing an agent read wasn't the raw source, but a map? A compact, honest description of the architecture: the projects, how they depend on each other, where the entry points are, and how a request actually flows through the indirection.

That's what DevContext does. It's a CLI that analyses a .sln and emits structured context — Markdown or JSON — designed to be dropped straight into an LLM's context window.

Why Roslyn

You can't build an honest map with regex. The whole point is to resolve indirection: to say "this controller action ends up calling that handler" even when nothing in the text links them. That needs real semantic analysis, which in .NET means Roslyn.

using var workspace = MSBuildWorkspace.Create();
var solution = await workspace.OpenSolutionAsync(solutionPath);

foreach (var project in solution.Projects)
{
    var compilation = await project.GetCompilationAsync();
    foreach (var tree in compilation.SyntaxTrees)
    {
        var model = compilation.GetSemanticModel(tree);
        var root = await tree.GetRootAsync();

        foreach (var invocation in root.DescendantNodes().OfType<InvocationExpressionSyntax>())
        {
            var symbol = model.GetSymbolInfo(invocation).Symbol;
            // symbol.ContainingType tells you where this call *actually* lands —
            // even across an interface or a DI registration.
        }
    }
}

The semantic model is the difference between "these two files mention the same name" and "this call is dispatched to this concrete type."

The rule that keeps it useful

There's one discipline that matters more than any feature: never show what the tool can't honestly answer. A map that invents an edge — a confident but wrong "this calls that" — is worse than no map at all, because the agent will trust it and build on the lie.

So DevContext is explicit about scope and confidence. It says what it analysed (the whole solution, or one project's closure) and how sure it is about each edge. A tool you reach for blindly has to be self-aware about its blind spots.

Where this goes

DevContext started as a one-shot context generator. The direction it's heading — a queryable graph you can browse, trace, and expose over MCP — is the more interesting version: one kernel, many faces. But the core bet is the same. Don't make the model re-explore. Hand it the map.

Vertical slices, not onions: structuring a .NET service for change

Tue, 07 Jul 2026 00:00:00 GMT

Open a "clean architecture" .NET solution and you know the shape before you read a line: Domain, Application, Infrastructure, Api. To add one endpoint you touch a controller, a service interface, its implementation, a repository interface, its implementation, a DTO, and a mapper — seven files across four projects for one behaviour.

That layout optimises for swapping a whole horizontal layer. In fifteen years I have almost never done that. What I do every day is change one feature. So I organise around features.

Slices, not layers

A vertical slice keeps everything one feature needs in one place — the endpoint, its validation, its handler, its data access — and lets unrelated features stay unrelated.

Features/
  Orders/
    CreateOrder.cs        // endpoint + request + validator + handler
    GetOrder.cs
    Orders.Endpoints.cs   // maps the group
  Catalog/
    SearchCatalog.cs

CreateOrder.cs holds the whole story:

public static class CreateOrder
{
    public record Request(string Sku, int Quantity);

    public class Validator : AbstractValidator<Request>
    {
        public Validator()
        {
            RuleFor(x => x.Sku).NotEmpty();
            RuleFor(x => x.Quantity).GreaterThan(0);
        }
    }

    public static async Task<Results<Created<OrderId>, ValidationProblem>> Handle(
        Request request, AppDbContext db, CancellationToken ct)
    {
        var order = Order.Create(request.Sku, request.Quantity);
        db.Orders.Add(order);
        await db.SaveChangesAsync(ct);
        return TypedResults.Created($"/orders/{order.Id}", order.Id);
    }
}

No IOrderService, no IOrderRepository, no AutoMapper profile. A minimal-API endpoint calls Handle directly. Cross-cutting concerns — auth, logging, validation — live in endpoint filters, not in a mediator pipeline.

"But you're not decoupled!"

Right — and that's the point. Decoupling has a cost, and you should pay it where coupling actually hurts, not everywhere by reflex. Two rules keep this honest:

Share the domain, duplicate the plumbing. Entities and invariants are shared. A read model that happens to look like another feature's read model is not shared — small duplication beats a wrong abstraction two features fight over.
Abstract at the real seam. The database, the clock, an external API — those are worth an interface because you genuinely swap them (tests, providers). A handler is not a seam. Don't wrap it in one.

When a slice grows complex, it gets a private helper inside the slice. It never graduates to a shared service that a dozen features quietly depend on.

What you get

Reading a feature is local. Everything is in one file. New joiners map a change to a place in seconds.
Deleting a feature is rm. No dangling interfaces or half-used services.
Tests target behaviour. I test the handler against a real database (Testcontainers) rather than mocking four layers to assert the mocks were called.

Onion architecture isn't wrong. It's a big up-front bet on flexibility you can usually buy later, at the exact seam, when you actually need it. Vertical slices bet on the thing you do constantly — changing one behaviour — and make that cheap.

Typed tools beat a raw shell: designing an MCP server for agents

Tue, 30 Jun 2026 00:00:00 GMT

The quickest way to make an LLM "agentic" is to give it a shell. It works in a demo and then betrays you: the model shells out with a subtly wrong flag, deletes the wrong path, or pipes half a gigabyte of log into its own context and forgets what it was doing. A raw shell is maximal capability with zero guardrails.

The reliable alternative is boring: give the agent a small set of typed tools, each of which does exactly one thing, validates its input, and refuses everything else. That's the whole idea behind the Model Context Protocol — and designing a good MCP server is an API design problem, not a prompt-engineering one.

A tool is a contract, not a suggestion

A tool has a name, a typed input schema, and a description the model reads to decide when to call it. The schema is the guardrail: the arguments are validated before your code runs, so the model physically cannot call get_order without a well-formed orderId.

[McpServerTool, Description("Fetch a single order by id. Read-only.")]
public static async Task<OrderDto> GetOrder(
    OrderService orders,
    [Description("The order's GUID, e.g. 3fa85f64-...")] Guid orderId,
    CancellationToken ct)
{
    var order = await orders.FindAsync(orderId, ct)
        ?? throw new McpException($"No order found for {orderId}.");
    return OrderDto.From(order);
}

Three things are doing quiet work here:

The type is the validation. Guid orderId means malformed ids never reach your logic — the protocol layer rejects them.
The description is the interface. "Read-only", the id format, the example — the model plans against that text. Vague descriptions cause misuse the same way vague docs cause bad API calls.
The error is structured. A clear McpException lets the agent recover on the next turn instead of hallucinating what went wrong.

Design principles that survive contact with a model

Least privilege, always. Prefer get_order and refund_order over one run_sql. Every tool you expose is attack surface the model can stumble into. If a tool can't be misused, you don't have to hope the prompt keeps it in line.
Return structured data, not a wall of text. Hand back a typed DTO, not dumped stdout. The model reasons far better over { "status": "shipped" } than over 400 lines it has to parse — and you keep its context lean.
Make writes obvious and idempotent. Name mutating tools like mutations, validate hard, and design them so a retried call is safe. Agents retry.
Bound every output. A tool that can return unbounded data is a context bomb. Page it, cap it, summarise it — decide the limit yourself.

Why this is the un-glamorous, correct path

Giving a model a shell feels powerful because it offloads the hard part — deciding what the system should actually let happen — onto the model's judgement, turn by turn. Typed tools put that decision back where it belongs: in an interface you designed, reviewed, and tested once.

It's the same instinct as everywhere else in engineering. You don't hand a caller raw database access and hope; you give them an API. An agent is just another caller — a fast, capable, occasionally overconfident one. Design for it like you'd design for any client you don't fully control.

Don't trust the agent — verify it

Sat, 20 Jun 2026 00:00:00 GMT

If you let a coding agent run unattended across a long plan, you eventually hit the core problem: an agent's report of its own work is not evidence. It will tell you a stage is done. Sometimes it is. Sometimes it edited the wrong file, sometimes the build is red, sometimes it wrote no code at all and narrated progress anyway.

You can't prompt your way out of this. The report and the work come from the same model in the same session — there's no independent witness. So I built one.

Evidence, or it didn't happen

The orchestrator I've been working on (Conductor) treats every session's claims as unverified until it checks them itself, out of process. After a session exits, it looks at three independent signals:

The gate battery — it re-runs build, tests, and lint itself and reads the real exit codes. Not the agent's summary of them.
Git — did new commits actually appear?
The tracker — did a checkpoint's status genuinely flip to DONE?

A checkpoint only counts when all three agree:

gates green  +  new commits exist  +  a checkpoint flipped to DONE
        →  Advanced (move on)

any required gate red
        →  GatesRed (next session is a *fix* session, with the
           failing output embedded in its prompt)

gates green, no commits
        →  NoProgress (the attempt is burned)

The asymmetry is deliberate. Advancing requires positive evidence from every source. Failing requires only one source to disagree.

"All done" is confirmed, not believed

The nicest bug this caught: an agent that marked the whole plan complete while the final integration test was quietly failing. Because "the plan is done" triggers one more full gate battery before declaring victory, the orchestrator caught the red test and kicked off a fix session instead of celebrating.

That's the whole philosophy in one line: deterministic first, model second. Use the cheap, boring, reliable checks — exit codes, git, a status table — as the source of truth. Only consult the model when you've genuinely hit a dead end, and even then, validate its answer against a fixed vocabulary of actions.

Why this generalises

You don't need an agent orchestrator to use this. Any time you're automating something with an LLM in the loop, ask: what's my independent witness? If the only thing telling you the work succeeded is the same thing that did the work, you don't have verification. You have a vibe.