274 lines
14 KiB
Markdown
274 lines
14 KiB
Markdown
# patterm: persistent daemon + thin networked client — implementation plan
|
||
|
||
Status: implemented — Phases 0–4 landed on this branch. Branch: `feat/daemon-client-split`.
|
||
|
||
> Implemented: pty workdir/process-group + protocol/Transport/loopback foundation;
|
||
> multi-project `ProjectRegistry`; out-of-process unix-socket daemon with auto-start,
|
||
> `daemon stop`/`ls`, detach (Ctrl-]) + reconnect; opt-in LAN TCP listener with a
|
||
> lightweight bearer token + `patterm connect`; per-pane display-owner sizing for
|
||
> multi-client viewing. Deferred (not built): TLS (transport kept pluggable),
|
||
> remote MCP, durable restore of live PTYs across daemon restart.
|
||
|
||
## Goal
|
||
|
||
Turn patterm from a single foreground process into a persistent background
|
||
**daemon** that owns all process/project state, plus a thin **client** that
|
||
renders and forwards input. A client on another LAN device can attach,
|
||
navigate projects via the command palette, detach, and reconnect — with child
|
||
processes surviving across client disconnects.
|
||
|
||
## Locked decisions
|
||
|
||
1. **Scope:** build all phases; land as one PR off this branch.
|
||
2. **Remote access:** human UI clients only. MCP for agents stays local
|
||
(per-daemon unix socket); no remote MCP transport in this work.
|
||
3. **Multi-client = per-client independent view.** The daemon holds pure
|
||
process/project state. Each client connection owns a `ClientView`
|
||
(selected project, focused pane/pad, scroll offset, palette state,
|
||
terminal size). Two clients may sit on different projects at once.
|
||
4. **Daemon lifecycle:** auto-start on demand (tmux/docker model). `patterm`
|
||
starts the daemon if absent and attaches; `patterm daemon stop|ls` manage it.
|
||
5. **Durability:** "persistent" = survive client disconnect while the daemon
|
||
process lives. Daemon restart only rehydrates today's persist model
|
||
(top-level commands, fresh IDs). No attempt to resurrect live PTYs/agents
|
||
after daemon death.
|
||
6. **Auth (trusted-network stance):** Harry runs this on a trusted LAN and is
|
||
fine with LAN exposure. Keep it lightweight: localhost default, opt-in LAN
|
||
bind (`--listen`), a simple pairing/bearer token to prevent accidental
|
||
drive-by access. TLS/cert-pinning is NOT required now but the transport must
|
||
stay pluggable so TLS can be layered in later.
|
||
7. **Detach gesture:** explicit detach via a palette command and/or a dedicated
|
||
host chord. Ctrl-D stays as PTY input (shell EOF), as today. Quit-project and
|
||
stop-daemon are explicit actions.
|
||
|
||
## Current architecture (baseline facts — verify before editing)
|
||
|
||
- `app.Run` (`internal/app/app.go:49`) wires the entire process: presets,
|
||
settings, scratchpad/trust/persist stores, in-process MCP server, ONE
|
||
`Session`, the `uiState` TUI, classifier, SIGWINCH, 60Hz chrome ticker,
|
||
blocking `stdinLoop`.
|
||
- **The seam:** `ChildEventListener` (`internal/app/session.go:83`) —
|
||
`OnChildSpawned`/`OnChildExited`/`OnPTYOut`/`OnChildStateChanged`/
|
||
`OnChildClosed`. Today `uiState` is the only real listener (subscribed at
|
||
`app.go:198`). A remote client = a serialized listener + reverse command
|
||
channel.
|
||
- One `Session` (`session.go:28`) holds a flat `children map[string]*Child` +
|
||
`order`. Tabs are derived: `KindAgent` children with `ParentID==""`
|
||
(`tree.go` `runningTopLevels`). The whole tree is reconstructed from
|
||
`Child.ParentID`.
|
||
- `Child` (`child.go:72`) owns `*pty.PTY`, `*vt.GhosttyEmulator`, raw ring,
|
||
status/owner atomics. Lifecycle: `Session.Spawn` (`session.go:222`) →
|
||
`startPTY` → `pumpChild` (`session.go:423`, PTY→emulator→ring→`emitPTYOut`)
|
||
+ `reapChild` (`session.go:488`, exit→`killDescendantsOf`).
|
||
- Stores already keyed by projectKey on `Open`
|
||
(`scratchpad`/`trust`/`persist`); `projectkey.Key(dir)` =
|
||
`sha256(realpath)[:16]`.
|
||
- `SerializeChild` (`session.go:687`) already yields a full VT snapshot for
|
||
stateless repaint.
|
||
- Rendering writes ANSI to `os.Stdout` under `outMu`; `viewportRenderer`
|
||
(`internal/app/viewport_renderer.go`) is a stateful ANSI rewriter confining
|
||
child output to the viewport. Input: raw `os.Stdin` via `stdinLoop`
|
||
(`app.go:1433`)/`processStdin`.
|
||
- MCP: in-process `Server` (`internal/mcp/mcp.go:26`), newline-JSON over a
|
||
per-PID unix socket `$XDG_RUNTIME_DIR/patterm/<pid>.sock`. Agents launch
|
||
`patterm mcp-stdio --socket S --identity T`. Identity → `callerID` via
|
||
`host.ResolveCallerIdentity` → `Session.FindChildByIdentity`.
|
||
- **No TCP/TLS anywhere today.** All `net.Listen`/`net.Dial` are unix sockets.
|
||
- **Must-fix:** `pty.Start` (`internal/pty/pty.go:26`) does not set `cmd.Dir`;
|
||
today the process `os.Chdir`s once. A daemon can't chdir globally, so
|
||
`SpawnSpec.WorkDir` must propagate to `exec.Cmd.Dir`.
|
||
|
||
## Target component model
|
||
|
||
| Component | Owns |
|
||
|---|---|
|
||
| `internal/daemon` (`pattermd`) | Project registry (N `Session`s), all PTYs, emulators, MCP server, per-project stores, classifier, timers. No TTY. |
|
||
| `internal/client` (`patterm`) | Real terminal: raw mode, alt-screen, SIGWINCH, stdin/stdout; `uiState`, `viewportRenderer`, chrome draws, palette, input. Holds `ClientView`. |
|
||
| `internal/transport` | `Transport` interface + framing; loopback, unix, TCP/TLS impls; auth handshake. |
|
||
| `internal/protocol` | Wire message types shared by daemon + client. |
|
||
|
||
### `Transport` interface (migration linchpin)
|
||
|
||
```go
|
||
type Transport interface {
|
||
Send(Frame) error // client→daemon command, or daemon→client push
|
||
Recv() (Frame, error)
|
||
Close() error
|
||
}
|
||
```
|
||
|
||
- **Loopback impl:** in-process channels, zero serialization. Default
|
||
`patterm` = client + loopback daemon in one process → today's UX preserved
|
||
exactly, single binary.
|
||
- **Net impl:** framed JSON-per-line over `net.Conn`, reusing the
|
||
`mcp.go:handleConn` pattern; unix socket first, then TCP/TLS.
|
||
|
||
### Per-client state vs daemon state
|
||
|
||
```go
|
||
// daemon-side, pure process/project state
|
||
type Registry struct { projects map[string]*Project } // key = projectKey
|
||
type Project struct {
|
||
Key, Dir, Name string
|
||
Session *Session
|
||
Pads *scratchpad.Store
|
||
Trust *trust.Store
|
||
Persist *persist.Store
|
||
Launcher *Launcher
|
||
Host *ToolHost
|
||
}
|
||
|
||
// per-connection, client-owned view state (lives client-side; daemon tracks
|
||
// only what it must to size emulators + route subscriptions)
|
||
type ClientView struct {
|
||
ID string
|
||
ProjectKey string // which project this client is looking at
|
||
FocusedID string // pane (Child) or pad
|
||
ScrollOff int
|
||
Cols, Rows uint16
|
||
// palette state is fully client-local
|
||
}
|
||
```
|
||
|
||
Project switch = re-point this client's subscription to another `Project`'s
|
||
Session + send `chrome` + `pane_snapshot`. No process teardown.
|
||
|
||
### Wire protocol (control + UI channel)
|
||
|
||
Bidirectional framed JSON-per-line.
|
||
|
||
Daemon → client:
|
||
- `hello` / `auth_challenge` / `auth_ok` — handshake.
|
||
- `project_list` — `[{key, path, name, last_active, tab_count}]` for the
|
||
palette switcher.
|
||
- `chrome` — semantic model for the client's current project+view: tab list
|
||
(`runningTopLevels`), sidebar tree (`sidebarNav`), status/owner, toasts,
|
||
scratchpad list + selected preview. Client draws chrome locally
|
||
(reuses `tabbar.go`/`sidebar.go`).
|
||
- `pane_snapshot{paneID, vtBytes}` — full repaint on focus/attach/switch via
|
||
`SerializeChild`.
|
||
- `pane_chunk{paneID, bytes}` — live focused-pane PTY output (serialized
|
||
`OnPTYOut`).
|
||
- `lifecycle{spawned|exited|closed|stateChanged,...}` — serialized listener.
|
||
- `attention` / `trust_prompt` — human-facing surfaces; render on the client
|
||
whose view owns the relevant project.
|
||
|
||
Client → daemon:
|
||
- `attach{token, term_size, project_key?}` / `detach`.
|
||
- `input{paneID, bytes}` (the `InjectAsUser` path).
|
||
- `focus{paneID|pad}`, `switch_project{key}`, `open_project{path}`.
|
||
- `palette_command{...}` (spawn/kill/rename/quit-project), `trust_response`,
|
||
`resize{cols,rows}`.
|
||
|
||
**Encoding decision:** ship raw focused-pane PTY bytes + periodic
|
||
`SerializeChild` snapshots; client runs its own `viewportRenderer`. No
|
||
daemon-side pre-render (keeps daemon size-agnostic), no grid diffs in v1.
|
||
Requires in-order delivery only (TCP gives it). Diffs are a later optimization.
|
||
|
||
### Emulator sizing with per-client views
|
||
|
||
Each `Child` emulator has one size. Rules:
|
||
- A pane is sized by the client(s) viewing it. If exactly one client focuses a
|
||
pane, that client's cols/rows drive `ResizeAll` for that pane.
|
||
- If two clients focus the **same** pane, one is the **display owner** (first
|
||
to focus, or explicit take-control); the owner's size drives the emulator;
|
||
the other letterboxes/clips. Surface a toast.
|
||
- Because clients are usually on different projects/panes, contention is rare.
|
||
|
||
### Security (human clients, LAN — trusted-network stance)
|
||
|
||
Harry runs this on a trusted LAN (decision #6). Keep it lightweight but not
|
||
wide open:
|
||
- localhost-only by default. LAN bind (`--listen 0.0.0.0:PORT`) is explicit
|
||
opt-in, never default.
|
||
- A simple pairing/bearer token gates network attach so a stray host on the LAN
|
||
can't drive-by-attach. Daemon prints the token on `--listen`; client presents
|
||
it in `attach`; store a per-client token after first pairing.
|
||
- Local unix-socket clients keep `0600` perms (sufficient for same-user).
|
||
- Keep the transport pluggable so TLS + cert pinning can be layered in later
|
||
without reworking the protocol. Not building TLS now.
|
||
- Trust prompts may now be approved from another device — deliberate; route to
|
||
the client whose view owns the project.
|
||
|
||
### Daemon lifecycle (auto-start)
|
||
|
||
- Well-known local socket `$XDG_RUNTIME_DIR/patterm/daemon.sock` +
|
||
pidfile/lockfile (single daemon per user).
|
||
- `patterm [dir]`: dial the socket; if absent, fork-exec the daemon, wait for
|
||
readiness, attach. `--project`/dir selects the initial project for the view.
|
||
- `patterm daemon` (foreground), `patterm daemon stop`, `patterm ls`.
|
||
- **Detach = explicit** palette command and/or a dedicated host chord; PTYs keep
|
||
running. Ctrl-D stays as PTY input (shell EOF). Quitting a project / killing
|
||
the daemon are explicit palette/CLI actions.
|
||
- Idle-shutdown policy: configurable; default keep alive until explicit stop.
|
||
|
||
## Package-by-package changes
|
||
|
||
- **`cmd/patterm`** (`main.go`): add `daemon` subcommand (headless core);
|
||
default invocation becomes client (auto-start/attach); `mcp-stdio` dials the
|
||
shared daemon socket (not per-PID); `debug-harness` drives a daemon (or
|
||
loopback).
|
||
- **`internal/app` split:**
|
||
- new **`internal/daemon`**: headless half — move `session.go`, `child.go`,
|
||
`host.go`, `tree.go`, `launch.go`, classifier, timers, `Shutdown`,
|
||
kill-cascade. Add `Registry`/`Project`.
|
||
- **`internal/client`**: TTY half — `uiState`, `viewport_renderer.go`,
|
||
`screen_renderer.go`, `tabbar.go`, `sidebar.go`, status, `palette.go`,
|
||
`stdinLoop`/`processStdin`, SIGWINCH/chrome ticker, markdown/marquee/toast.
|
||
Consumes events + chrome over `Transport` instead of `sess.Subscribe`.
|
||
- **new `internal/transport` + `internal/protocol`**: messages, framing,
|
||
loopback/unix/TCP-TLS impls, auth handshake.
|
||
- **`internal/mcp`**: `SocketPath` per-daemon (not per-PID);
|
||
`ResolveCallerIdentity` becomes daemon-wide across projects (token already
|
||
carries `PATTERM_PROJECT_KEY` via `ChildEnv`).
|
||
- **`internal/pty`**: set `cmd.Dir` from `SpawnSpec.WorkDir`; add process-group
|
||
handling for reliable tree teardown.
|
||
- **`internal/vt`**: unchanged grid source of truth; enforce per-child
|
||
serialization around emulator access (interface isn't concurrency-safe) since
|
||
clients + MCP + pump all snapshot.
|
||
- **`internal/{scratchpad,trust,persist}`**: per-`Project` instances in the
|
||
registry (already keyed by projectKey).
|
||
- **`internal/preset`**: project-agnostic; daemon loads once, shares.
|
||
- **`internal/projectkey`**: doc update (key is now load-bearing for routing).
|
||
- **`internal/harness`**: add daemon/loopback mode; assert child survives client
|
||
disconnect/reconnect, project-switch preserves each project's tree, two
|
||
clients on different projects, unauth TCP rejected.
|
||
|
||
## Backpressure
|
||
|
||
`pumpChild`'s listener calls are synchronous (`session.go:149`). A slow network
|
||
client must not block the PTY pump. Introduce a per-client event bus with a
|
||
bounded buffer that coalesces/ drops to a snapshot under pressure, decoupled
|
||
from `pumpChild`.
|
||
|
||
## Phased roadmap (all phases land on this branch)
|
||
|
||
0. **Extract headless core behind loopback transport.** `daemon.Core` +
|
||
`client` over in-process `Transport`. Zero behavior change; harness green.
|
||
1. **Multi-project registry + per-client view scaffolding.** Registry, per-
|
||
project stores, `ClientView`, palette "Switch/Open project…", project tier
|
||
in chrome. Still single local process.
|
||
2. **Out-of-process daemon over unix socket.** Auto-start/attach; PTYs survive
|
||
client exit; reconnect + snapshot-on-attach; Ctrl-D = detach; pidfile/lock.
|
||
3. **TCP + TLS + auth.** localhost TCP, then opt-in LAN bind; pairing token /
|
||
cert pinning; remote trust-prompt routing.
|
||
4. **Per-client view fully realized + emulator sizing/display-owner.**
|
||
Independent focus/scroll/palette per client; multi-client on same/different
|
||
projects; resize negotiation + letterbox.
|
||
5. **Hardening.** systemd/launchd autostart, `daemon stop|ls`, idle-shutdown,
|
||
backpressure, security review, CHANGELOG.
|
||
|
||
## Risks / open questions for review
|
||
|
||
- Heterogeneous client sizes vs one-PTY-one-size (display-owner + letterbox is
|
||
the v1 answer — is it sufficient?).
|
||
- Security escalation: a network client spawns processes / runs shell / injects
|
||
input. Auth/TLS scope adequate?
|
||
- Ctrl-D semantics flip — acceptable UX?
|
||
- Backpressure design — bounded bus + snapshot-on-pressure correct?
|
||
- MCP identity uniqueness across projects after per-PID socket removal.
|
||
- Is per-client view (decision #3) worth doing from Phase 1, or staged after a
|
||
shared-focus interim that's faster to ship?
|
||
- Splitting `uiState` (focus/palette/render caches/trust prompt/dims/outMu) out
|
||
of the daemon is the largest refactor — sequencing concerns?
|