feat(cli): Phase 0 control plane, list/status/open, bundling

[MHohlios]

This PR is Phase 0 of the termic CLI (design: #125): a termic command that talks to the running app over a local Unix socket.

What it does now: three read-only commands (list, status, open) plus all the machinery underneath them (socket, token auth, connect-or-launch, the bundled binary, and PATH install). It cannot create or change anything.

What it does not do yet: create or drive tasks. Those verbs land in later PRs.

This is a self-contained phase that merges on its own, following the repo's "one phase, one PR into main" shape (#62, #84, #113). Later phases follow as separate PRs with no ordering constraint between them, and every phase leaves the app's build green and behaviorally unchanged for anyone who has not opted in. Opened as a draft for now; ready to flip once reviewed.

Commands

Verb	Phase	What it does
list / ls	0 (this PR)	List tasks: project, task, agent, work state, diff stat, branch. -q = ids only, --project filter
status <task>	0 (this PR)	One task in depth: state, branch, path, sandbox, session count, dirty files
open [<task>]	0 (this PR)	Raise the window and select a task (current-directory aware)
new <name> [-p …]	1	Create a task from the shell
wait <task>	1	Block until the agent is quiescent
archive <task>	1	Archive a task
project add / list / remove	1	Manage projects
send <task> -p …	2	Prompt a running agent
apply <task>	2	Send the task's diff to main
attach <task>	2	Attach a real TTY to the agent PTY
path / diff <task>	2	Print worktree path / show diff

Everything in Phase 0 is read-only or window-focus. Unimplemented verbs are simply absent (clap prints "unrecognized subcommand"), never stubbed or half-working. Global flags: --output-format text|json, --json, --no-launch.

Command name per build, and instances

The installed command name is build-aware, and the app permits one instance per data dir (the socket doubles as the lock). Because prod and beta share the release data dir, they are mutually exclusive by design: launching one while the other runs raises the running one and exits. Beta is long-term testing of prod, so you run one or the other, never both.

Build	Command	Data dir	Instances
prod (release)	termic	termic	one; shares the lock with beta
beta	termic-beta	termic (shared with prod)	one; mutually exclusive with prod
dev (make dev)	termic-dev	termic_dev	own lock; newest-wins on relaunch
e2e (test rig)	uses the dev binary	scratch TERMIC_DATA_DIR	isolated, parallel-safe

The on-disk sidecar is always termic-cli; only the symlink name varies, so all three coexist on PATH.

Under the hood

• Crates. A cargo workspace with termic-proto (wire types, NDJSON framing, protocol version, pinned exit codes) and termic-cli (the termic binary), which links only termic-proto, never the app's lib.rs.
• Socket server on its own thread, never the IPC/main thread. <data_dir>/termic.sock (0600, sun_path guard, always binds). Unauthenticated surface is hello/raise only; every verb needs the "Enable CLI" setting (default off) AND the per-boot token from <data_dir>/cli-token (0600, in memory only, never in the app env that pty_spawn copies to children). getpeereid same-uid check per connection.
• Webview RPC. Work state comes from the webview over a new typed correlation-id channel (cli-rpc://request + cli_rpc_result), not the debug /eval bridge, which is never armed or reused.
• Sandbox boundary. The control socket is a privilege boundary: a caged agent that reaches it can escape. Enforcing profiles now emit the socket deny as the final network rule and the data-dir deny as the final filesystem rule, in both Enforce and EnforceFs. Verified behaviorally with real sandbox-exec.
• Distribution. externalBin sidecar so the binary ships in the .app; enabling the CLI auto-installs it (no prompt) into ~/.local/bin, with a system-wide /usr/local/bin option (admin prompt on macOS). termic --version reports the app version, injected at build time, so the bundled CLI is always versioned with the app.

Off by default

There is a single Settings → General → "Enable CLI" toggle, off by default. While it is off, every command is refused and the app behaves exactly as it does today, so this is invisible to anyone who does not turn it on. (Exit codes and --json output are a stable, additive-only contract, so scripts can rely on them once shipped.)

Try it out

gh pr checkout 132     # or: git fetch <remote> && git checkout feature/cli-phase0
make dev               # launches the dev app on the termic_dev profile
                       # (first build after the Rust changes takes ~1-2 min)

In the running app: Settings → General → "Enable CLI" (toggle on). Enabling auto-installs the command as termic-dev into ~/.local/bin (no password). Then from any shell:

termic-dev list                    # project, task, agent, state, diff, branch
termic-dev status <project/task>   # one task in depth
termic-dev open <task>             # raises the window and selects that task
termic-dev --json list             # machine-readable

The -dev name is deliberate so it never clashes with a real termic install. If ~/.local/bin is not on your PATH, the Settings row says so, and make cli-dev is an alternative that builds and symlinks it for you. Toggling the setting off refuses every command immediately.

Testing

• 226 Rust unit tests across the three crates: protocol round-trips and version-mismatch, exit-code and text/JSON output goldens, name and cwd resolution (worktree-first, longest-prefix, ambiguity), auth and gating, single-instance handshake, and behavioral sandbox-exec containment tests (in-cage connect refused, token read refused with ~/Library allow-listed through each extension layer, caged env carries no token). Plus the existing frontend suite.
• CI runs cargo test --workspace --lib. A full release compile succeeds and stages the sidecar.
• Manual smoke over the socket: enable/disable, list / status / open, and every error path (disabled, bad/missing token, no-launch, in-cage refusal).

Known / deferred

• The prod/beta simultaneous-launch bind race is accepted and deferred to the tmux-style flock fix, per the design doc.
• The behavioral sandbox-exec tests self-skip on the Ubuntu CI (macOS-only). A gated macOS CI job to run them for real is a follow-up.
• macOS is the primary target. On Linux the install falls back to ~/.local/bin (no privilege prompt, since the /usr/local/bin elevation is macOS-only), and auto-launch is macOS-only; the sandbox boundary is macOS-only regardless (tasks are never caged on Linux).

[simion]

Approving. The security model is the standout: 244-bit per-boot token in a create_new 0600 file, never exported to the process env (asserted by an absence test), peer same-uid check before any read, and SBPL denies placed as the final fs/network rules so last-match-wins can't invert them. Really appreciate that the containment claim is proven behaviorally with real sandbox-exec runs rather than a textual profile check, including a positive control that the allow-listed ancestor is otherwise readable. Resolution logic (worktree-vs-main-checkout precedence, composition members, shared-checkout ambiguity) and the NDJSON framing edge cases are all well covered, and the build.rs nested-cargo lock/env handling plus the universal-bundle belt-and-braces are thoughtful. Only nits, none blocking: per-connection threads are uncapped (bounded by same-uid + timeouts), and every app cargo check now recompiles the CLI (mitigated by profile-matching). Ship it.

[simion]

Will be shipped in the next release, probably this weekend. I manually re-test the entire app, and each new feature. before releasing :D

Thanks for the effort!