pulam-tui — the thin CLI client for the pulam daemon

pulam-tui is the raw client of the pulam daemon — kaval-tui’s sibling, one layer up. Where kaval-tui is the thin shell client of the kaval PTY daemon (list / attach / kill over a socket, no browser), pulam-tui is the thin shell client of the pulam awareness daemon: status / watch over the same socket-or-ssh transport. The rich, leave-it-on-a-second-monitor fleet view is pulam-web’s job now — so pulam-tui sheds the Bun + OpenTUI machinery it grew for that view and reverts to what kaval-tui has always been: a scriptable, single-daemon CLI face.

User-facing description

Three verbs against one daemon — status (a one-shot snapshot), watch (a live follow), and wait (block until a terminal’s agent reaches a state, then exit) — each scriptable with --json, and watch optionally narrowed to a single terminal id. No alt-screen, no full-screen UI: pulam-tui prints to your terminal and exits, or streams line-by-line, exactly the way kaval-tui’s list / snapshot do. wait is the awareness analog of a blocking read: it’s the done-signal an agent uses to drive another agent — prompt a Claude Code / Codex / opencode in a kaval terminal, then wait --until awaiting,waiting for its turn to end before reading the reply.

wait matches the agent’s state the instant it connects (it replays the current value), so a robust driver waits in two phases — --until working to confirm the prompt was picked up, then --until awaiting,waiting for the turn to end — rather than a lone post-send wait that the previous turn’s stale waiting/awaiting would satisfy immediately. It fails loud on a --timeout <ms> (exit 2) and on the terminal exiting before the state lands (exit 3 — the agent you were driving died), so a stuck or dead agent can’t hang the loop.

The surface mapping — each command is a thin read over the terminalWorkspaceSurface the daemon serves:

Flags mirror kaval-tui exactly: --socket <path> points at a local daemon (default $XDG_RUNTIME_DIR/pulam/awareness.sock); --host <ssh> dials and Nix-provisions a single remote pulam over ssh. The two are mutually exclusive, and there is no multi-host mode — one invocation, one daemon. (Watching the whole fleet across hosts is what you open pulam-web for.)

Workflows

Glance — what is every terminal in, right now. status prints the snapshot and exits:

Follow the whole daemon live. watch (no id) streams every terminal’s changes as they land — leave it running in a spare pane. Each line is HH:MM:SS id repo·branch agent · state, with a trailing ● when that terminal is moving bytes right now:

Follow one terminal. Narrow to an id (the short id from status, or a unique prefix) when you only care about one agent:

Script it. --json turns either verb into a feed — pipe status --json through jq, or alert off a watch --json line (NDJSON, one object per line):

Reach a remote daemon. --host dials and Nix-provisions one pulam over ssh — same two verbs, no kolu-server:

Architecture-level changes

The whole point is the raw-vs-rich split, the same one kaval-tui draws against its daemon: the daemon is durable and serves the full typed surface; the -tui client is the bare, scriptable face, and the browser is the rich one. pulam-tui reading awareness is the exact analog of kaval-tui reading PTYs.

pulam-tui reverts to a leaf — and loses no electricity proof by doing so. The original note justified the OpenTUI fleet board as the awareness analog of drishti: a second consumer that proves pulam’s own surface is a receptacle other apps plug into. That proof now stands on pulam-web — a second consumer, and the better one, reading the same surface the same way kolu’s browser will. With the electricity carried elsewhere, the TUI no longer has to be rich to earn its keep; it can be the bare scriptable client and nothing is lost. The renderer that the old note called “electricity, but already OpenTUI” is simply not needed in the TUI anymore — the rich render lives in the browser, where it belongs.

What leaves the package, and why it was only ever there for the fleet board:

• The Bun runtime → back to Node (tsx). OpenTUI’s renderer is a native Zig core loaded via Bun.dlopen, so the dashboard needed Bun. With no dashboard, Node is enough — matching kaval-tui’s tsx src/main.ts and the pulam daemon’s own runtime.
• OpenTUI (@opentui/core, @opentui/solid) + the per-arch Zig lib. The whole SolidJS-into-terminal render layer (render.ts, the live clock, the breathing alert strip) goes; status prints a table and exits.
• bun2nix and its scaffolding. bun.lock / the autogenerated bun.nix / the per-arch Zig closure / the pnpm-workspace exclusion that kept the Bun manifest out of pnpm’s glob — all of it existed to package the Bun viewer. It is replaced by the same plain Node packaging kaval-tui uses.
• The multi-host fleet subcommand. The N-host fan-out, the (host, terminalId) aggregate, the FleetSink / startFleet / multi-host RepoWatchSet, the --by / --no-local / --ssh-config flags — the entire aggregation surface moves to pulam-web, which already owns it. pulam-tui dials one daemon.

What stays — the thin-client spine, shared with kaval-tui:

• The single-daemon dial. --socket for a local daemon and --host for one remote pulam over ssh, both through @kolu/surface-nix-host’s dialAgentOnce — the same one-shot primitive kaval-tui’s --host rides. pulam-tui and kaval-tui stay thin wrappers over one shared dial.
• The awareness read + --json. The one-shot awareness-collection dump (today’s --json) is already exactly what status needs; it keeps that path and grows the human table beside it.

Implementation details

A subtractive change, mostly: delete the viewer, keep the dial, rename the snapshot. The decisions, to be echoed as code comments at their sites (the kaval-tui convention):

The steps:

1. Strip the viewer. Remove @opentui/*, the render.ts OpenTUI tree, the live clock, and the fleet subcommand from packages/pulam-tui. Drop the Bun manifest (bun.lock / bun.nix / the Zig closure) and the pnpm-workspace exclusion; repoint package.json’s start to tsx src/bin.ts.
2. Keep the dial, rename the snapshot. The existing single-endpoint awareness consume (today rendered by the OpenTUI list, dumped by --json) becomes status / status --json over --socket | --host (dialAgentOnce). No surface change — status is a one-shot read of the awareness collection the daemon already serves.
3. Add watch. Subscribe to the awareness collection plus the activity stream and print each update — a line in default mode, one JSON object per line under --json — until Ctrl+C. Bare watch follows every terminal; an optional <id> filters to one. A pure consumer; no contract bump.
4. Repackage like kaval-tui. The Nix derivation drops bun2nix for the plain Node packaging packages/kaval-tui uses; nix run …#pulam-tui and the dev recipe follow kaval-tui’s wholesale.

History

• Shipped (2026-06-26, #1582) — with pulam-web shipped as the browser fleet dashboard (R-pulamweb-3, #1535), the OpenTUI/Bun fleet board in pulam-tui was redundant. This reverts pulam-tui to a kaval-tui-style raw client — status and watch (all terminals, or one by id) over one daemon, Node/tsx instead of Bun, no OpenTUI, no multi-host fleet. Split out of pulam’s R4.5 (the fleet board) and its “Why this stays a TUI” / “Why Bun” sections, which this supersedes; the daemon note keeps the daemon story and points here for the client.