the workspace daemon & its CLI · alpha
Padi: the memory
under kolu.
padi is the per-host daemon that holds what a kolu workspace is: terminals, sessions, restore state, repo context, the code tree, git status, diffs and agent awareness. It sits above kaval, which owns the live shells. padi-tui reads it from the shell.
Where it sits
The browser talks to kolu-server, the server binds padi, and padi supervises its own kaval. Restart the web shell and padi still has the workspace. Restart padi and kaval still has the PTYs. The layers recover on different clocks because they own different state.
When kaval stops answering
padi supervises its kaval continuously, not only at boot. Every ten seconds it asks three read-only questions over the socket, and a kaval that cannot answer them within five seconds counts as stuck.
| What padi sees | What it does |
|---|---|
| three stuck answers in a row, about half a minute | runs what the Restart kaval button runs: saves the session, stops the daemon, starts a fresh one, and offers your terminals back for restore |
| three restarts that still produce no answering daemon | stops restarting, and leaves the card and the button for you |
| the connection drops while the daemon still answers | re-makes the line about a second later, backing off to once every half-minute, for as long as it takes |
A re-made connection is the ordinary outcome, and it takes the daemon back over. Your terminals and the agents in them keep running, there is nothing to restore, and kolu says so once before the card clears itself.
Two narrower cases end differently, and kolu says which you got. If the daemon exits between the check and the re-connect, the re-connect starts a fresh one. If a re-connected daemon holds terminals kolu cannot account for, kolu replaces it. Both show the restart message, “kaval was unresponsive — kolu restarted it; your session is ready to restore”, and your session comes back through the restore card.
kaval also watches itself from the other side of the wire. It asks its own address a trivial question on the same cadence, and three unanswered self-checks in a row make it exit non-zero rather than accept connections it cannot serve.
While a host’s kaval is down, that host’s dot is amber, not green.
What padi knows
kaval only knows terminals. padi is where terminal observations become a workspace: repo-aware, agent-aware, resumable, and readable from more than one face.
A padi that has just started says it is still settling until it has adopted kaval’s terminals. Only then does it publish an established roster, which names the terminals it holds in the same message. A kaval restart closes the roster to settling again until its terminals are restored.
So a restart or a redeploy is never read a layer up as every terminal dying. Nothing above padi calls a terminal gone until the roster that would have held it is real, and “the roster is real” always arrives with its list of terminals.
padi also keeps account of its own cost: the commands it ran in the last minute, its stalls, its file watchers and its call times. Troubleshooting → kolu feels slow shows where to read them.
terminal registry
which terminals exist, where they belong, and how to re-open them after the web layer moves.
workspace memory
the session record, activity feed, restore target, and durable state-root for one host.
repo context
repo, branch, pull request, checks, cwd, foreground command, file browsing, git status, and diffs.
agent state
whether a terminal’s agent is working, waiting, or asking for you, folded into one live surface.
one host, nothing more
padi knows this machine’s terminals and nothing about any other. The fleet view, and the Conductor’s one conversation, are assembled a layer up, by the kolu-server that binds every host’s padi.
Read the workspace from the shell
padi-tui reads the same workspace surface kolu uses. Where kaval-tui shows what is running in each PTY, padi-tui shows what each terminal is in: repo, pull request, checks, foreground command, live byte activity and agent state. That is the state behind the multi-agent dock.
padi-tui status
padi-tui watch
padi-tui wait a3f10000 --until awaiting,waiting
padi-tui create --toplevel -- claude
ID REPO·BRANCH PR AGENT FOREGROUND IDLE
a3f10000 kolu·feat/dial-ssh #1412 ✓ claude · working node 2s
b7c20000 kolu·master — codex · waiting codex 1m
c9d40000 kolu·fix/fold #1408 ✗ — nvim 5m
REPO·BRANCH shows — for a terminal outside any repo, and ? while padi has not checked its git yet. With --json, the repo sits under .git.info, and .git.kind says which case it is: repo, none or unresolved.
| Command | What it does |
|---|---|
padi-tui status · --json | Print a one-shot workspace snapshot: terminals, repos, agent state, foreground process, and recency. |
padi-tui watch · --json | Follow the workspace live, including state changes and activity indicators. |
padi-tui wait <id> --until awaiting,waiting · --timeout <ms> · --json | Block until an agent turn ends using padi’s real agent-state fold, not a guess from terminal silence. |
padi-tui create (--toplevel | --parent <id>) -- claude · --worktree <branch> · --repo <path> · --json | Create a kolu terminal from the shell, live on the canvas. Placement is required: --toplevel, or --parent <id> to split under an existing terminal. Add --worktree for a worktree’d agent. |
Which daemon it talks to
- Inside a kolu terminal,
$PADI_SOCKETmakespadi-tuiflag-less, so an agent driving its siblings never guesses a path. padi keys its socket by a digest of its state-root. - padi also puts
padi-tui,kaval-tuiand thekoluwhosemcpface agents connect to on that terminal’s$PATH, taken from padi’s own build. On a remote host they arrive in the closure kolu provisions, so a tool can never come from a different build than the daemon it talks to. - Elsewhere it finds the running padi by itself. With several running (your everyday padi plus a dev or test one), it picks the one keyed to the state root your environment names.
--socket <path>and--state-root <dir>point it at a different local daemon.--host <ssh>reaches a padi on another machine, the twin ofkaval-tui --host. It provisions the daemon with Nix, runspadi --stdioover ssh, and runs every verb unchanged (padi-tui status --host nix@prod).- Read verbs are safe over
--host, andcreatelands a real terminal on the host, which survives the link. A tui only dials, so it never drains or converges the remote padi.--hostis mutually exclusive with--socketand--state-root.
To point kolu’s browser at a remote padi instead, see Add another machine.
Wait for an agent turn
wait <id> --until awaiting,waiting blocks until a terminal’s agent finishes its turn, read from real padi state rather than guessed from terminal silence.
- For a robust driver, wait in two phases:
--until workingfor pickup, then--until awaiting,waitingfor turn-end, so a stale previous-turn state cannot satisfy the wait early. --until freshwaits for an agent you have just launched to be up, with its screen settled and nothing said to it yet, which padi knows from the process.--timeout <ms>fails loud (exit 2). A terminal that exits first exits 3.--jsonprints{ id, agent }.
Why it is not inside kolu-server
The web server is a face: HTTP, assets, websocket transport. The workspace is a daemon: durable folder, terminal registry, session restore, agent awareness. Keeping them apart means a deploy can replace the web shell without making the workspace disappear.