Padi: the memory
under kolu.

padi is the per-host daemon that remembers the memory under kolu — 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 PTYs. The split is simple: kaval keeps shells alive; padi keeps the workspace legible. The whole layer stack is in Architecture; padi is a @kolu/surface daemon, with the drain-capable live recycle that keeps a client connected across an upgrade.

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.

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.

The thin shell face — padi-tui

padi-tui reads the same workspace surface kolu uses. Where kaval-tui shows what’s running in each PTY, padi-tui shows what each terminal is in: repo, PR, 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 -- 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

Usually no flag. padi keys its socket by a digest of its state-root, so inside a kolu terminal $PADI_SOCKET makes padi-tui flag-less — an agent driving its siblings never guesses a path. Elsewhere it autodiscovers the running padi; --socket <path> or --state-root <dir> point it at a different local daemon, and --host <ssh> reaches a padi on another machine — the twin of kaval-tui --host: it provisions the daemon with Nix, runs padi --stdio over ssh, and runs every verb unchanged against the remote (padi-tui status --host nix@prod). Read verbs are safe and create lands a real terminal on the host (which survives the link); a tui is a dial, so it never drains or converges the remote padi. --host is mutually exclusive with --socket / --state-root. Pointing kolu’s browser at a remote padi is a separate path that already ships — see Remote Hosts for adding a machine to the canvas.

wait <id> --until awaiting,waiting blocks until a terminal’s agent finishes its turn — a done-signal read from real padi state, not guessed from terminal silence. For a robust driver, wait in two phases: --until working for pickup, then --until awaiting,waiting for turn-end, so a stale previous-turn state cannot satisfy the wait early. --timeout <ms> fails loud (exit 2), a terminal that exits first exits 3, and --json prints { id, agent }. The deeper design notes live in the padi atlas note.

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 -- claude · --parent <id> · --worktree <branch> · --repo <path> · --json	Create a kolu terminal from the shell: a new tile, a split tile (--parent) that opens and selects just like a browser-made split, or a worktree’d agent — all appearing live on the canvas.

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 those apart means a deploy can replace the web shell without making the workspace disappear.