Rebuild the terminal interface around nodes and increase UX - #117

Both front ends need to browse the models an engine can download, and only one
of them could: the desktop app carried its own Electron-side model hub, so the
terminal interface had no way to offer the same thing. Putting the catalog
behind engine:catalog gives both clients one implementation, next to the engine
manager that performs the pull.

One curated source per engine, because there is no generic GGUF registry worth
browsing. Ollama has no public catalog API, so the list is scraped by a
developer, reviewed as a diff, committed, and compiled in with go:embed --
serving it touches no network. LM Studio's catalog is the lmstudio-community
Hugging Face org, whose repo ids are exactly what lms get accepts, so it is
fetched live, cached for six hours, coalesced across concurrent callers, and
backed off after a failure so a dead upstream is not re-dialled per call.

The catalog is filtered for the platform the models will install on, not the
one serving it: MLX quantizations only install on Apple Silicon, so those rows
are marked appleOnly and dropped for a non-darwin target, and the reply echoes
the platform it filtered for.

Signed-off-by: Terve <[email protected]>

The Add Model browse was assembled in the main process: a committed Ollama list
bundled into the Electron bundle, plus a live Hugging Face fetch. The terminal
interface could not reach any of it, so the two front ends would have had to
maintain separate catalogs of the same models.

Replace the module with a thin relay over engine:catalog. What remains here is
the boundary work the renderer needs and the backend should not care about:
mapping EngineType to the manifest's engine name, translating the platform to
GOOS -- Node says win32 where Go says windows -- and normalizing rows, dropping
any without a pull-ready id rather than offering a model that cannot be
downloaded.

A catalog failure returns an empty hub rather than an error. The modal then
shows its empty state, which is the honest reading for a user who can do
nothing about a dead upstream.

The scraper stays in desktop/scripts: it is a TypeScript development tool and
only its output crosses into the services tree.

Signed-off-by: Terve <[email protected]>

The Inference Demo's HTTP client was built by its own script into its own
tools/ resource directory, which only the desktop app knew about. The terminal
interface runs the same demo and resolves everything beside its own executable,
so a second location meant it could not find the client at all.

Build it into cli-bin with the binaries it sits beside. It is still not a
service -- no entry in versions.json, no supervision -- so it carries the
services version rather than a component version, and it is named explicitly in
the expected-file set so cli-bin stays an exact inventory rather than merely
gaining an exemption.

Fingerprint what actually goes into a binary while here. Only .go files were
hashed, so regenerating an embedded asset -- the engine manager's Ollama
catalogue, now -- left the build believing cli-bin was current, and it shipped
the previous binary with nothing to indicate the list was stale. The
dispatcher's own sources sit outside the services tree and get walked for the
same reason.

Signed-off-by: Terve <[email protected]>

A bufio.Scanner is finished after a read error, including an over-long line,
which it cannot skip past. Treating that like a frame the client merely failed
to parse meant calling Scan again forever: the read loop spun at full speed
while the interface went on claiming the service was ready.

Name the unrecoverable case so the loop can tell the difference and report the
disconnect, and let the supervisor wait for the broker's own teardown before
force-killing it -- the workers it is shutting down are the ones holding the
files a reset is about to delete.

Signed-off-by: Terve <[email protected]>

Three things every view needs and none of them owned: a table that lays its
columns out against the width it was actually given, a status line that
expires on its own, and helpers that force a block of content to an exact
number of rows.

Each exists because the alternative kept going wrong. Columns summed to more
than the terminal and the last one was cut; a status line set during a
thirty-five second operation vanished six seconds in, leaving a screen
indistinguishable from a dropped keypress; and content that rendered one row
too many pushed the footer off the bottom.

Signed-off-by: Terve <[email protected]>

A node is the unit an operator reasons about, so the tabs become Nodes, Jobs,
Service, Errors, and Logs, and everything specific to one machine hangs off its
row rather than living in a tab of its own. The ten tabs this replaces spread
one machine's facts across four of them: its engines in one, its models in
another, its ports in a third, its cluster standing in a fourth.

The five views only exist together -- the shell sizes them, they share its
status line and frame budget, and the tab set is the change -- so this lands as
one commit. Read in the order the pull request gives, which follows the data
rather than the alphabet.

Much of it is about claiming no more than the backend guarantees. A proxy port
change reports the port actually bound rather than the one requested, because a
running engine holding that port wins and the broker resolves it elsewhere.
Clearing an error is only offered where clearing sticks -- delete-by-id on the
reporting node -- so a peer's entry names the node to clear it from instead of
silently reverting on the next sync. The cluster name is labelled as this
machine's own. Node presence follows the broker's snapshot rather than a
timestamp that never advanced.

Every table gets its columns at construction. The broker replays a baseline
snapshot as soon as a view subscribes, which can arrive before the first
WindowSizeMsg, and bubbles indexes its column slice per row cell -- so rows
against a zero-column table panicked rather than rendering empty.

Against the unified proxy the two identities are kept apart deliberately. The
Service tab's worker row keys on the process, engines.ProxyComponent, because
one nvpair-proxy hosts every facade and the broker reports one crash for it;
the facade views key on each engine's ComponentName, which is what addressing
"ollama-proxy:nodes/list" means. Getting that backwards is silent in both
directions, so the invariant is asserted rather than described.

Signed-off-by: Terve <[email protected]>

PAIR carries three numbers and the update check can only use one of them. The
published tags are named for the release version in desktop/package.json; the
services suite version and this component's own version describe parts of the
build. The suite version is currently the larger number, so comparing it
against the feed would not merely be wrong but silently wrong -- every check
concluding this build is ahead and saying nothing, forever.

Rename the symbol to ui.ReleaseVersion to match the vocabulary the release
tooling now uses, and stamp it from desktop/package.json in both build paths:
services/build.sh and .bat for a tarball install, and the desktop's
build-modular-binaries for the copy inside cli-bin. A -X against a symbol path
that does not exist fails silently, so both were verified by reading the value
back out of the built binary rather than by reading the flag.

Signed-off-by: Terve <[email protected]>

The engine manager gained editable launch settings: the arguments and
environment an engine starts with, alongside its server port and the
client-facing proxy port. The desktop app can edit all three; the terminal
interface could edit neither the arguments nor, on a peer, the ports.

"a" on an engine opens its arguments in the notation LAUNCH_TEXT.md defines.
Nothing is saved directly. The draft goes to engine:preview-settings, which
normalizes the text and reports per-field errors, a port conflict, and whether
applying restarts the engine; the commit then carries the settings the preview
returned rather than the text that was typed, so what lands is what was checked.
A restart is armed and confirmed with y, like the other interruptions.

The two port fields move onto the same path. They were writing through
engine:set-port and the proxy's own set-port, which meant two writers with no
shared revision: the last to finish won and neither could tell it had lost.
All three fields are now one revision-checked write, which is also what makes
them editable on a peer -- the backend relays it, and whether a particular
engine will accept the write is the snapshot's Editable answer rather than a
rule kept here that would drift from it.

Ports stay honest across the move. A port is a request, not a promise: a
running engine outranks the proxy, so the backend binds elsewhere and reports
the difference as the effective port. The outcome is read from the snapshot
that follows the write rather than from the write's own reply, which only says
the request was accepted -- and it is reported once, for a change made here,
because those snapshots also arrive when anyone else saves.

Signed-off-by: Terve <[email protected]>

The terminal interface guide still described the screen it replaced, and three
claims elsewhere had become false: that the model hub lives in Electron, that
the demo is the desktop app's alone, and that per-engine arguments are outside
the contract. All three are now the opposite of true.

The guide gains the startup-arguments editor and loses its own contradiction --
it documented the Jobs tab's test traffic in one section and denied having any
in another. Ports are no longer described as local-only, because they are not,
and the note about a port being a request rather than a promise moves into the
guide where an operator will meet it.

The architecture rule gains the rule worth keeping: the three settings fields
are one revision-checked write, and editability is the snapshot's answer rather
than something a front end decides for itself. Both halves are there because
both were got wrong here first.

Signed-off-by: Terve <[email protected]>

services/build.sh now stages inference-dispatcher beside the components, and
the check compares that directory against versions.json exactly -- so it fails
on a binary that is deliberately not a component.

Name the exception rather than loosening the comparison. The check exists to
fail when the build script and the manifest disagree about a component, and a
pattern that skipped anything unexpected would stop doing that. One extra
declared name keeps a second undeclared binary failing.

Signed-off-by: Terve <[email protected]>

Every colour adapts to the terminal's background, but the text drawn on top of
the accent did not: it was a fixed black, which suits the pale blue chosen for
a dark terminal and is unreadable on the dark blue chosen for a light one. It
applied to the active tab and the selected table row -- the row the operator is
looking at, on every tab -- so a light theme made the interface hard to use
rather than merely off-colour.

Pair the foreground with the background so both flip together, and assert the
pairing: a fixed foreground over an adaptive background is legible in exactly
one of the two terminals, and which one is decided by a detection this program
does not control.

Add --appearance for when that detection is wrong. It works by asking the
terminal for its background and waiting for an answer; a terminal that does not
reply -- common over SSH and inside tmux -- leaves lipgloss assuming dark. auto
still detects, light and dark state it outright, and anything else is refused
rather than quietly meaning auto, which would strand the one operator who
reached for the flag.

Signed-off-by: Terve <[email protected]>

Saving an engine's settings failed with "a request identifier is required"
after the check had already passed, which read as the interface calling its own
validated change invalid.

The identifier is the backend's idempotency key. It records a receipt against
it, replays return the original outcome, and a replay carrying different
settings is refused -- so a commit without one is rejected outright. Only the
commit needs it, which is why the preview succeeded first and the failure
arrived at the point of saving.

It is minted when the change is judged rather than when it is sent, so a change
held for a restart confirmation keeps the identifier it was judged with and
confirming is a replay rather than a second write.

The test asserts the marshalled request, not the Go field. `requestId` is
omitempty: unset, it does not travel as an empty string, it vanishes from the
object -- which is exactly how this shipped with a struct field that looked
correct and a payload that was missing it.

Signed-off-by: Terve <[email protected]>

Auto-detection did not work, so the colours had to be declared by hand on any
terminal that is not dark.

lipgloss resolves the background once, lazily, the first time an adaptive
colour is needed -- which is during the first render. By then Bubble Tea owns
the terminal and is reading stdin, so the terminal's reply to the query goes to
its reader, the query times out having learned nothing, and lipgloss falls back
to assuming dark.

Force it at startup instead, while stdin is still ours, and let the sync.Once
keep the answer for every later frame. Measured in a pty against a terminal
that answers with a light background: it is now detected as light, and the
first frame arrives in 0.19s.

The query runs alongside broker startup rather than in front of it, because a
terminal that never answers costs five seconds -- termenv's timeout is a
constant, and the query cannot be abandoned early since it owns the terminal
until it returns. That wait is not new: clean develop pauses the same five
seconds on the same terminal, and it is unrelated to --appearance.

Also correct what the documentation claims about when detection fails. SSH is
fine, because the query and its reply travel the connection like anything else.
It is screen and tmux that cannot answer, by their own design, along with
terminals that do not implement the query at all.

Signed-off-by: Terve <[email protected]>

The first settings change on a machine succeeded and every one after it failed
with "settings changed on this device; reload before applying", until the
screen was closed and reopened.

The broker stamps each snapshot with the node's UUID. This screen matched that
against the node argument the local RPCs take, which is empty precisely
because they are local -- so every push for this machine was discarded. The
cached revision stayed at whatever the first read returned while the real one
moved on with each save, and a write carries the revision it was based on.
Match on the row's key, which is the UUID discovery reports and the one the
broker sends.

Verified against a running broker: the snapshot's nodeId and discovery's
hostUuid are the same value, and the engine whose port had just been changed
was sitting at revision 2 against a cache still holding 1.

Make the failure recoverable while here. A revision the backend will not
accept cannot be repaired by repeating the write, so a rejected save now drops
the stale snapshot and re-reads it, and says what happened in terms of what to
do next rather than repeating the backend's instruction to reload -- which the
screen has by then already carried out.

Signed-off-by: Terve <[email protected]>

A node's detail screen replaces the whole tab, and it stayed open when the
operator switched away. Coming back to Nodes put them inside whichever machine
they had last opened rather than on the list they asked for, with the list a
keypress further away and nothing on screen saying why.

Leaving a tab now returns it to its own top-level screen. Expressed as an
optional interface, like the two a view already opts into, because this is not
something every tab should do: a selection or a filter is where the operator
left off and worth keeping. It is for a view that replaces itself with
something else entirely.

Unconditional on the way out, which is safe because a view holding a text
field or an armed confirmation captures the keyboard -- the tab cannot be
changed out from under one, so there is no half-finished state to discard.

Signed-off-by: Terve <[email protected]>

A successful engine port change was reported as a failure: "engine stayed on
:1237 - :1238 is taken", while the engine was in fact listening on 1238 and
nothing at all was on 1237.

The verdict was inferred by comparing the saved ports against the effective
ones. The effective engine port is observed at the moment the apply replies,
and an engine that restarts onto its new port finishes after that -- LM
Studio's server re-launches under launchd, detached, so the manager loses
sight of it and the reading lags a change behind. Reading failure into that
lag invented both the failure and a cause for it.

The snapshot already carries the backend's own verdict as a phase, with a
reason when it failed. Use those. The proxy port is still compared, because
that one is read live from the proxy process rather than observed in passing,
so a proxy that could not take the port it was given is a real difference
worth reporting -- stated as where it landed, without asserting why.

Signed-off-by: Terve <[email protected]>

A machine PAIR is not paired with reported "spark-182c is not answering - no
engine list available", directly above a hardware readout for that same
machine updating every two seconds.

Both were true at once because they travel different paths. Telemetry comes
from an endpoint that needs no pairing; engines come over pin-based mTLS,
which only succeeds against a peer we hold a pin for. The call was made
anyway, and its failure is indistinguishable from silence once it has failed
-- so the one cause the screen could not observe was the one it reported.

Decide before asking instead. A node outside the cluster is not asked, and the
pane says which relationship it has and what would change it: pair from the
Nodes tab, leave the other cluster first, or wait for the handshake. The
models pane stops blaming a stopped engine for the same gap -- models come
from what the node advertises over discovery, and whether an engine is running
is exactly what cannot be seen from outside the cluster.

Signed-off-by: Terve <[email protected]>

The initial read's reply and the errors:update pushes arrive by
different paths, so a reply landing after a push replaced the newer
snapshot with an older one. Keep the push once one has arrived.

Before this machine's identity arrived, every error was clearable, so a
peer's error could be cleared here and restored by the next sync. Hold
the clear until the identity is known and say why.

The column minimums summed past the forty-column floor, and what was
clipped off the right was the message. Let the node name and the message
share the width, weighted towards the message, with minimums that fit.

Also name the "re-render what is held" call instead of writing it as
setErrors(v.errs) in three places.

Signed-off-by: Terve <[email protected]>

Every rejected invite ended "remove the existing relationship first", including rejections that gave no reason or a reason unrelated to membership. Give the already-clustered reason its own remedy and report the rest plainly. The reason codes and their wording move to nodes.go, the only place that uses them.

Signed-off-by: Terve <[email protected]>

The key is t for tail; the label now says both words, so neither vocabulary has to be guessed.

Signed-off-by: Terve <[email protected]>

It lived in errors.go, which does not use it. It now sits beside clampWidth in table.go, and its test is table-driven, covering the cut, multi-byte boundaries, and degenerate widths.

Signed-off-by: Terve <[email protected]>

Drop the account of the old age-based presence rule from the comments; git records it. Point the manual-node shape at where ManualNodeStatus is defined, and put the any-service-answered check in one method so another probed service is one line there.

Signed-off-by: Terve <[email protected]>

Each tab's view type now starts with what it shows and the usual path through it, pointing at docs/terminal-interface.mdx for the user guide. The accounts of which older tabs each one replaced are gone; git records those.

Signed-off-by: Terve <[email protected]>

Near 40 columns the tab bar numbers the tabs it cannot name, the footer keeps quit and help, and full help spreads across columns to fit.

Signed-off-by: Terve <[email protected]>

Every broker reply and push was decoded with its error discarded, so a
shape the broker and this client disagreed about showed up only as a
screen of zero values. Decode through a helper that logs the failure
with what was being read, and skip the two workload pushes that would
otherwise fold in a job with no identity.

The terminal's own log went to stderr, which the full-screen program
hides. While it runs, route it to the Logs tab beside the broker's,
without ever blocking, since the update loop that drains that channel
also logs. The channel is no longer closed when the broker's stderr
ends, because this program still writes to it afterwards.

Signed-off-by: Terve <[email protected]>

Every worker read "ok" from the first frame, before the service had
answered, before any errors snapshot had arrived, and before this
machine's UUID was known to tell its crashes from a peer's. Show "?"
until all three are in, and classify no crash before the UUID.

Also on this tab: the log levels and their names come from applog, the
level is held as a slog.Level starting from NVPAIR_LOG_LEVEL as the
broker's does, a level change no longer claims to have reached every
service (the broker forwards it best effort), and the settings rows
carry whole method names instead of a suffix glued to "settings/get-".

Signed-off-by: Terve <[email protected]>

The Nodes tab read the cluster name once at startup, and the settings worker sends no push when it changes, so a rename made on the Service tab looked unsaved there. The save now carries its method and value to every tab, and the Nodes tab takes the name from it.

Signed-off-by: Terve <[email protected]>

A failed status read was dropped, so the strip kept its last good answer while reads failed; it now marks the facade down. The broker's {ready:false, port:0} for a facade it is not running blanked the port that the error push deliberately kept; both now keep it. A failed subscription is logged instead of discarded.

Signed-off-by: Terve <[email protected]>

The table listed jobs in arrival order, so a backlog of older queued work
pushed new jobs below the fold; it now lists newest first. Jobs for the
same model from the same node, started together, read as duplicates, so
a short ID column shows the tail of each job's ID, which is where the
per-process counters differ.

A failed subscription or baseline read left the table empty for the
session, and a failed identity read left this machine's jobs named by
UUID, with nothing said. Both are retried on the existing five-second
poll until they succeed.

Signed-off-by: Terve <[email protected]>

Answering an inbound request cleared it before the answer went out. The
cluster manager refuses a malformed PIN with an error and leaves the
session open, so a typo lost a request that could still be answered.
The request now stays on screen until the answer settles, and a second
answer cannot be sent while one is in flight.

A second inbound request replaced the first, which stayed live with no
way back to it. Requests now queue, one on screen, with the count of
those waiting. While a node's detail screen is open, a line above it
keeps a waiting request or a live outbound PIN in view.

A cancel that failed left a live invite untracked, with its PIN gone and
nothing to press. It is now put back and can be cancelled again.

The invite helpers move into nodes.go, their only user, and the invite
states are named after the cluster manager's.

Signed-off-by: Terve <[email protected]>

A manual entry whose probe had read one machine's UUID still fell back
to matching by address, so it folded into a different machine that now
answered at the same IP, showing one machine's membership and models
under the other's name. Once an entry has a UUID, it no longer joins a
row with a different UUID of its own.

Roster reads and nodes:changed pushes each replaced the roster, but a
reply and a push reach the view by different paths, so a reply landing
after a newer push put the older roster back. A read now counts only if
no push has arrived since it was sent; pushes carry every change.

Signed-off-by: Terve <[email protected]>

Each kind of reply carried its own node field and its own check, so a
new command could skip the check and report one machine's outcome on
another's screen. Every broker call the screen makes now goes out
through one wrapper that tags the reply with the screen's node, and the
screen drops replies for another node before handling any of them.

Signed-off-by: Terve <[email protected]>

- A second settings change while the first is still applying is refused.
  The screen follows one outstanding write, so the second replaced it
  and the first's verdict was never reported.
- Engine and model keys are refused while the frame has no room for
  that list, rather than acting on a row the operator cannot see.
- engine:install-progress is ignored on a peer's screen: it carries no
  node, so it is always this machine's install.
- Progress frames show a percentage only when one is reported. The
  engine manager omits it while indeterminate and sends -1 on failure,
  which rendered as (0%) and (-1%); a failed install now reads as a
  failure with the engine manager's reason.

Signed-off-by: Terve <[email protected]>

…wered

- The address that answered the last poll is tried first. Walking the
  node's list from the top spent a full timeout on every unreachable
  address ahead of it, every two seconds.
- A reading whose hostUuid names another machine is refused, so an
  address that has passed to a different host does not show that
  host's hardware under this one's name. Rows keyed by a stand-in, and
  this machine over loopback, have nothing to check against.
- Drop the unused msSince field from the telemetry and manual-node
  shapes.

Signed-off-by: Terve <[email protected]>

The only way past a failed load was to close the browser and open it
again, and once the error expired from the status line the list read as
the engine having no models. The failure now stays in the body, and r
asks for the catalog again.

Signed-off-by: Terve <[email protected]>

The progress note counted every request the schedule reached, including
ones whose dispatcher failed to spawn. It now counts on a successful
start, for the run still going, as the desktop app does.

Signed-off-by: Terve <[email protected]>

The architecture page still described pinning a node from the terminal
interface's Proxies tab. The terminal interface no longer has that tab
or any way to pin, so automatic routing is the only case PAIR produces.

Signed-off-by: Terve <[email protected]>

cluster:invite-node answers failed, with no PIN, when the first
exchange does not complete, and with whatever a cancel or teardown
recorded when one got there first. Only rejected was checked, so either
reply read as "invite sent" and left the invite pending. Only pending
now counts as sent.

Signed-off-by: Terve <[email protected]>

A machine can only be in one cluster, and the cluster manager refuses an
accept on a machine that already is. Requests still waiting after a
successful accept came up one by one looking answerable, and each
sender went on showing its PIN until the invite expired. They are now
declined as soon as the pairing succeeds, which tells each sender, and
the outcome says how many were declined.

Signed-off-by: Terve <[email protected]>