retire Go sidecar; adopt Dart core (ADR 0005)

ADR 0005 supersedes ADR 0002. The "sidecar vs app" split was
load-bearing on Go-vs-Dart being a meaningful boundary. Going
all-Dart collapses that — the daemon becomes clide --daemon mode
of the same AOT binary the CLI lives in, both sharing lib/ with
the Flutter app. The one native gap (Dart's multi-threaded VM
can't safely fork+exec) is filled by a small C supporter tool —
ptyc, Project Terminal Controller, peer of pql — rather than
introducing a second core language.

ADR 0006 defines the CLI/event surface on top of that Dart core:
subsystem list (pane/tab/editor/panel/tree/git/pql/canvas/graph/
theme/settings/project), command shape, versioned JSON event
schema, pql-parity exit codes, and command-event duality as the
operational form of user/Claude parity.

Deleted: sidecar/cmd, sidecar/go.mod, every sidecar/internal
package. Rewritten: Makefile (dart compile exe, flutter
analyze/format/test, build-linux/build-macos, ptyc-build),
ci/*.sh, .githooks/pre-push (no more GOBIN PATH dance),
.gitignore (Flutter/Dart at repo root, ptyc section),
project.yaml (drop module: and go_version:), CLAUDE.md
(guardrails, dependencies, commands refreshed).

Co-Authored-By: Claude <noreply@anthropic.com>

docs/ADRs/0002-sidecar-language-go.md

@@ -1,7 +1,8 @@
 # ADR 0002 — Sidecar language: Go
 
-**Status:** accepted
+**Status:** superseded by [ADR 0005](0005-dart-core-ptyc-peer.md)
 **Date:** 2026-04-20 (ported from the claudian lineage)
+**Superseded:** 2026-04-20 — the "separate language" premise dissolved once we chose Dart for the core; see 0005 for the rationale.
 
 ## Context
 

docs/ADRs/0005-dart-core-ptyc-peer.md

@@ -0,0 +1,163 @@
+# ADR 0005 — Dart core; sidecar directory dissolved; `ptyc` as pql-peer
+
+**Status:** accepted
+**Date:** 2026-04-20
+**Supersedes:** [ADR 0002](0002-sidecar-language-go.md)
+
+## Context
+
+ADR 0002 picked Go for the sidecar/CLI on the reasoning that (a) the
+heavy work (PTYs, subprocesses, file watchers, git, IPC) belongs in
+a language separate from the UI layer, and (b) pql is Go so the
+muscle memory transfers. The Flutter app would talk to a Go binary
+over a unix socket.
+
+On reassessment, two facts broke that reasoning:
+
+1. **What the "heavy work" actually is.** Stripped of the PTY layer,
+   the sidecar is I/O-bound glue around shell-outs (`git`, `claude`,
+   `pql`), a unix-socket server, JSON-lines framing, and a process
+   table. `dart:io` covers all of this cleanly. The Go-versus-Rust
+   debate implicit in 0002 was the wrong axis — the real choice was
+   **separate process vs shared language**, and separate-process is
+   what matters (session persistence needs the daemon to outlive the
+   app), not language.
+
+2. **PTY is the one place Dart is genuinely weak** — and not because
+   of ecosystem, but because Dart's multi-threaded VM can't safely
+   `fork()`. That single constraint forces a native helper regardless
+   of what language wraps it. Once you accept a small native helper,
+   the question is whether *everything else* needs to be in that same
+   native language. It doesn't.
+
+So the "sidecar" directory stopped carrying weight. It existed to
+justify the Go/Dart split. With the split gone, the directory is
+ceremony.
+
+## Decision
+
+Three moves.
+
+### 1. Dart is the core language.
+
+Everything that used to live under `sidecar/` — IPC server, CLI
+dispatch, process management, file watching, git shell-outs, pql
+wrapper — is written in Dart. Two execution modes of one Dart AOT
+binary:
+
+- `clide <subcommand>` — one-shot, pql-style. Parses args, connects
+  to the running daemon socket, sends a request, prints JSON on
+  stdout, exits with the pql exit-code contract.
+- `clide --daemon` — long-running. Owns PTYs, subscriptions, file
+  watchers, subprocess lifecycles. Started by the app on load;
+  survives app restarts so Claude sessions persist.
+
+The Flutter app imports the Dart core as a library for in-process
+state (views, widgets, models) *and* connects to the daemon over the
+same IPC the CLI uses. One protocol, two clients.
+
+### 2. The sidecar directory dissolves.
+
+```
+app/                # Flutter UI (Linux / macOS primary)
+lib/                # Dart core shared by app + CLI + daemon:
+                    #   ipc/, pty/, proc/, git/, pql/, events/, panes/
+bin/clide.dart      # Dart AOT entry: subcommand dispatch + --daemon
+tool/                # Dart scripts used by the Makefile
+tests/              # integration tests that span app + daemon
+```
+
+No `sidecar/`. No Go module. `project.yaml` drops `module:`; the
+Dart package name replaces it.
+
+### 3. `ptyc` is a pql-peer supporter tool.
+
+The PTY helper — a small C binary that does `posix_openpt` + `fork`
++ `exec` + fd-passing via `SCM_RIGHTS` — graduates to the same
+status as pql: single-purpose, language-appropriate, standalone,
+reusable outside Clide. It lives in its own directory (eventually
+its own repo) and Clide wraps it the same way it wraps pql. Working
+name: **`ptyc`**.
+
+- Clide shells out to `ptyc` to spawn every PTY (terminal pane,
+  tmux session, claude, LSP server, debug adapter — all one code
+  path).
+- `ptyc` writes only what it needs to write (a PTY + forked child)
+  and does nothing else. No IPC protocol of its own, no long-running
+  state. One-shot per pane.
+- Consumers other than Clide (a Python script, another Dart app, a
+  Go tool) can use `ptyc` standalone with no Clide dependency.
+
+This mirrors ADR 0003's pql contract: **wrap, don't duplicate**;
+supporter tools stay independent and reusable.
+
+## Consequences
+
+- **ADR 0002 is superseded.** Go sidecar removed. Existing
+  `sidecar/` contents (Go skeleton — `cmd/clide/`, `internal/*`,
+  `go.mod`) are deleted; the ideas it encoded (exit-code contract,
+  ldflag-stamped version, JSON diagnostics) are reimplemented in
+  Dart. The supersession note stays in 0002 so the history reads
+  correctly.
+- **One toolchain for the IDE proper.** Flutter + Dart. The C
+  toolchain is needed only to build `ptyc` — a tiny, rarely-changing
+  artifact.
+- **`project.yaml` simplifies.** `module:` and `go_version:` go
+  away. A `ptyc_version:` pin joins the existing `dart_sdk:` and
+  `flutter_channel:` keys.
+- **Supply-chain gates stay, shape changes.** The Go gate
+  (`govulncheck`) is removed. The Dart gate stays (advisories review
+  + exact-pin `pubspec.yaml`). `ptyc` gets its own tiny gate: it has
+  no deps beyond libc, so the review is "read the 150 lines before
+  every bump." `make security` becomes `make security` = Dart
+  advisories + `ptyc` review checklist.
+- **IPC stays.** The daemon / app / CLI split is unchanged — unix
+  socket, token auth, JSON-lines. It was never about language.
+- **Session persistence stays.** PTY master fds live in the Dart
+  daemon process, not the app process. App restart does not kill
+  Claude.
+- **Pql continues as-is.** Wrapped via shell-out from
+  `lib/src/pql/` (the Dart equivalent of the deleted
+  `sidecar/internal/pql/`). No protocol change to pql.
+- **CLAUDE.md and the Makefile need updates.** Commands, directory
+  references, and the "sidecar language: Go" guardrail all shift.
+- **Rust remains an escape hatch, not a plan.** If a Dart limit
+  later forces a second native helper (file-watching at scale on
+  macOS, a tree-sitter host, etc.), the precedent set here is: new
+  native need → new supporter tool, peer of pql and `ptyc`. Never a
+  second "core language."
+
+## Notes
+
+- **Name: `ptyc`** (pronounced "p-tic"). Three honest readings, all
+  pointing at the same tool:
+  1. **Project Terminal Controller** — parallel to pql's **Project
+     Query Language**. Clide's supporter tools follow a `p*` pattern
+     where `p` = *project*: pql handles project queries, ptyc
+     handles project terminals. Future supporter tools that fit the
+     "small single-purpose peer of pql" slot should follow the same
+     pattern when the fit is natural.
+  2. **PTY + child** — domain vocabulary (PTY parent/child pair).
+     This is what a reader seeing the name on a command line will
+     decode it as, and it's exactly what the tool does: run a child
+     process under a PTY.
+  3. **PTY + C** — the implementation language. Accurate and
+     non-limiting; Unix has a long tradition of tools advertising
+     their implementation (`gcc`, `libc`, `musl`). If we ever
+     rewrote it in another language it would become a new tool with
+     a new name, same as pql would if rewritten.
+
+  Crucially, none of the readings tie the **caller** to any
+  ecosystem — `ptyc` is usable from Dart, Python, Go, shell,
+  anywhere a subprocess can be spawned and a fd can be received.
+  Alternatives considered and rejected: `clide-pty-spawn` (too
+  clide-specific for a peer tool), `dpty` (already taken on
+  crates.io), `ptyspawn` (verbose), `dartmx` (falsely signals
+  caller-ecosystem + implies multiplex), `ptyx` (arbitrary suffix,
+  no domain reading), `ptyc` as read-only "PTY C" (works but sells
+  the name short).
+- The helper's wire contract (stdin JSON → stdout JSON + SCM_RIGHTS
+  fd transfer) is intentionally small so wrapping it is trivial from
+  any language.
+- This ADR does not define the Clide CLI / event surface itself —
+  that is [ADR 0006](0006-cli-and-event-surface.md).

docs/ADRs/0006-cli-and-event-surface.md

@@ -0,0 +1,190 @@
+# ADR 0006 — CLI and event surface contract
+
+**Status:** accepted
+**Date:** 2026-04-20
+
+## Context
+
+[ADR 0001](0001-cli-first-not-mcp.md) established that Claude drives
+Clide via a Bash CLI, not MCP. That decided the *channel*. It did
+not define the *surface* — which subsystems exist, how commands
+relate to events, what the JSON looks like on the wire, how
+subscribers discover state changes.
+
+CLAUDE.md states the rule colloquially: "every CLI subcommand has a
+UI affordance in the app, and every UI action has a CLI. If you add
+one side without the other, the feature is incomplete." This ADR
+restates that as an implementable contract.
+
+The shape needs to satisfy three things at once:
+
+1. **User/Claude parity.** Anything the user can do with a mouse,
+   Claude can do with `clide <...>`. Anything the user can observe
+   in the UI, Claude can observe via events.
+2. **Daemon as authoritative state.** The app and the CLI are both
+   clients. State lives in the `clide --daemon` process; commands
+   mutate it; events broadcast changes to all subscribers.
+3. **pql-style ergonomics.** One tool-use pattern for Claude across
+   pql and clide — same exit codes, same JSON-on-stdout habit, same
+   stderr-for-diagnostics rule.
+
+## Decision
+
+The CLI is organised into **subsystems**. Each subsystem owns a
+noun, a set of verbs, and a set of events. The set is closed at any
+point in time (documented); growth is additive (new verbs, new
+events — never renaming existing ones without a version bump).
+
+### Subsystem list (initial, by tier)
+
+| Subsystem | Tier | Nouns | Representative verbs | Representative events |
+|---|---|---|---|---|
+| `pane`     | 1 | terminal pane | spawn, list, focus, close, write, resize, tail | `pane.spawned`, `pane.output`, `pane.exit`, `pane.resized` |
+| `tab`      | 2 | workspace tab | new, switch, close, list | `tab.opened`, `tab.switched`, `tab.closed` |
+| `open`     | 2 | editor shortcut | *(verb-only: `clide open <path>`)* | — (emits `editor.opened`) |
+| `editor`   | 2 | active editor buffer | goto, highlight, insert, replace-selection, save | `editor.opened`, `editor.selection_changed`, `editor.saved` |
+| `panel`    | 2 | sidebar/context panels | show, hide, toggle, list | `panel.visibility_changed` |
+| `tree`     | 2 | file tree | reveal, refresh | `tree.node_expanded`, `file.changed` |
+| `git`      | 3 | working tree | status, stage, unstage, stage-hunk, commit, stash, pull, push | `git.status_changed`, `git.branch_changed` |
+| `pql`      | 4 | queries | run, tags, backlinks | `pql.result` |
+| `canvas`   | 5 | canvas surface | open, node add/move/connect, save | `canvas.node_added`, `canvas.node_moved`, `canvas.connection_added` |
+| `graph`    | 5 | graph view | open, focus, filter | `graph.focused`, `graph.filter_changed` |
+| `theme`    | 6 | theme/palette | set, list, get | `theme.changed` |
+| `settings` | 6 | settings store | get, set, list | `settings.changed` |
+| `project`  | — | whole-workspace | status, reload, events | `project.ready`, `project.reloaded` |
+
+Two umbrella entry points sit outside any subsystem:
+
+- `clide tail --events [--filter <subsystem>[:<id>]]` — subscribe to
+  the event stream. Bare `tail --events` gets everything; filtered
+  forms narrow by subsystem or by subsystem+id (e.g.
+  `--filter pane:p_7`, `--filter git`).
+- `clide status` — one-shot daemon snapshot: connected clients,
+  live panes, open tabs, workspace root, daemon version, uptime.
+
+### Command shape
+
+```
+clide <subsystem> <verb> [<positional>...] [--flag ...] [-- argv...]
+```
+
+- Positionals are nouns/ids; flags are modifiers.
+- `--` separates Clide's args from an inner argv passed through
+  (e.g. `clide pane spawn --cwd X -- tmux new-session -A -s foo`).
+- Verbs are imperative (`spawn`, not `create-pane`).
+- Where it reads naturally, single-word shortcuts exist for the
+  hottest paths (`clide open <path>` → `clide editor open <path>`).
+  Shortcuts alias; they do not fork.
+
+### Exit-code contract (parity with pql)
+
+| Code | Meaning |
+|---|---|
+| `0` | Success |
+| `1` | User error (bad args, unknown id, precondition failed) |
+| `2` | Tool error (daemon unreachable, IPC failure, internal panic) |
+| `3` | Not-found (id or path doesn't resolve) |
+| `4` | Conflict (state busy, already-running, concurrent-modify) |
+| `64`–`78` | Reserved, per `sysexits.h`, for future specific cases |
+
+Diagnostic JSON on **stderr** (not stdout) on any non-zero exit:
+```json
+{"code":1,"kind":"user_error","subsystem":"pane","message":"pane id p_99 not found","hint":"clide pane list"}
+```
+
+Stdout stays machine-parseable on success. This matches pql.
+
+### Event schema
+
+Events are JSON objects, one per line, on the `--events` stream.
+Every event:
+
+```json
+{
+  "v": 1,
+  "ts": "2026-04-20T21:00:00.123Z",
+  "type": "pane.output",
+  "subsystem": "pane",
+  "id": "p_7",
+  "payload": { "bytes_b64": "…", "seq": 412 }
+}
+```
+
+- `v`: schema version. Bumped only for breaking changes. Old
+  subscribers pin `v`.
+- `ts`: ISO-8601 UTC with millisecond precision.
+- `type`: `<subsystem>.<verb_past|noun_changed>`. Past-tense for
+  things that happened; `_changed` suffix for state transitions.
+- `subsystem` + `id`: redundant with `type`, but makes
+  filtering cheap and future-flexible.
+- `payload`: subsystem-defined; documented per subsystem.
+
+Binary payloads (PTY output, file contents) are base64. The ergonomic
+cost is worth the "entire stream is line-delimited JSON" invariant.
+
+### Command ↔ event duality
+
+Every state-changing command emits at least one event. Subscribers
+see the same mutation whether they triggered it or not, and the
+issuing client gets the event back (so `clide pane spawn` followed
+by a `tail --events` subscription sees `pane.spawned` regardless of
+subscribe order, via a short replay buffer per subsystem).
+
+Read-only commands (`list`, `get`, `status`) emit nothing.
+
+### User/Claude parity as a check
+
+Every merge to `main` that adds a UI affordance must either:
+- add the matching CLI verb, or
+- include a linked follow-up task naming the verb to add next.
+
+Every merge that adds a CLI verb must either:
+- surface it in the UI, or
+- document why the verb is Claude-only (rare; mostly diagnostics
+  like `clide status`).
+
+Events have the symmetric rule: any UI surface that reacts to state
+must react to the corresponding event; any new event must be
+consumable both by the UI and by `clide tail --events`.
+
+## Consequences
+
+- **Surface is enumerable.** Adding a subsystem means adding a row
+  to the table above and specifying its verbs + events in a short
+  doc under `docs/cli/`. The daemon registers it; the CLI dispatcher
+  picks it up; `clide --help` and `clide <subsystem> --help` stay
+  accurate by construction.
+- **Wire schema is versioned.** `v: 1` is the starting point.
+  Compatibility breaks bump the major and land alongside a
+  `project.yaml` `schema_version:` bump.
+- **Replay buffer per subsystem.** Cheap (most subsystems emit
+  seldom); needed so a subscriber that connects after a command
+  still sees that command's effect. Buffer depth per subsystem is a
+  tuning parameter; defaults to 16 events.
+- **Events are the only UI→app state channel.** The Flutter app
+  does not poll; it subscribes. Panels render from the last event
+  for their subsystem + current snapshot from `project status`.
+- **pql events fit naturally.** Long-running `pql` queries stream
+  rows as `pql.result` events keyed by a query id, letting the
+  Query panel render incrementally.
+- **Testability.** Every subsystem can be integration-tested by:
+  start a daemon → open a `tail --events` subscriber → issue
+  commands over the CLI → assert events. No UI needed for
+  protocol-level coverage.
+- **Extension API (Tier 6) inherits this.** A Dart extension
+  publishes a subsystem; the same registration pipeline exposes
+  it to Claude via the CLI. Extensions don't get a second-class
+  channel.
+
+## Open questions
+
+- **Authorisation granularity.** The daemon's token auth is coarse
+  (allow all / deny all). Later, per-subsystem grants may matter
+  (e.g. restrict `git push`). Out of scope here.
+- **Back-pressure on event streams.** A subscriber that falls behind
+  on `pane.output` (a firehose) needs a policy: drop oldest, block
+  producer, coalesce, or kill subscriber. Defer until Tier 1 is in
+  real use.
+- **Event persistence.** Events are in-memory only in v1. If a
+  future need (audit log, undo) wants persistence, it becomes a
+  subsystem that subscribes and writes — not a property of the bus.