clide/fable-ous.md

# fable-ous.md

*A fable about clide, as told by Fable.*

*Produced by 13 parallel subsystem reviewers reading ~58k LOC of Dart, ~100 raw
findings put through 70 adversarial verification passes (exactly one finding was
refuted — it had missed D-14), 5 feature-ideation lenses, and a full read of the
pql planning vault: 94 confirmed decisions, 24 open questions, 11 rejected
alternatives, 358 tickets. Everything below cites real file:line evidence that a
skeptical second agent re-read and failed to knock down.*

---

## TL;DR scoreboard

| Dimension | Verdict |
|---|---|
| Build health | **Green.** `make analyze` 0 issues, 1383 tests pass, format clean, coverage 95.30% over the 95 floor |
| Documentation discipline | **Best-in-class.** Near-every file cites its D-NNN/T-NNN; zero TODO/FIXME debt in 58k LOC |
| Honesty | **High.** CHANGELOG claims verified against code; stubs self-describe as stubs |
| Real bugs found | ~14 distinct high-severity, ~35 medium — mostly in process lifecycle, a11y, and terminal conformance |
| Systemic risks | Broadcast-streams-without-replay, silent `catch (_)`, kernel lookup in `dispose()`, copy-paste drift |
| Release process | **Stalled.** No git tag since v2.1.0 despite five CHANGELOG releases; `ci/release.sh` is a stub |
| Killer-feature headroom | Enormous — the moats (owned agent loop, owned renderer, pql vault) are real and barely exploited |

The fable in one sentence: **a castle with exceptional masonry, a few unlocked
side doors, and a dragon hoard of features in the basement nobody has spent yet.**

---

## Part I — The state of the realm (what's genuinely excellent)

Credit where due, because this codebase does several things better than most
production repos:

- **Governance traceability is real, not ceremonial.** Nearly every non-trivial
  declaration carries its ticket/decision id. Multiple reviewers independently
  called it "the best I've seen at this scale." Code-to-decision drift is
  *auditable from the code itself* — and indeed most drift findings below were
  found exactly that way.
- **Schema-validated IPC dispatch (D-74)** is beautifully executed: schemas
  co-registered with handlers, the MCP tool surface and `clide capabilities`
  both generated from the same registry (`lib/src/daemon/dispatcher.dart:90-137`)
  so three surfaces cannot drift apart.
- **The keymap subsystem (D-82)** — layered precedence, headless
  `SequenceMatcher`, clock-injected `ModifierTapTracker` — is exemplary,
  near-fully test-mirrored design.
- **`ClideTappable`, the anchored-overlay/menu family (D-88), reduced-motion
  honoring in every animated primitive** — the owned widget layer is coherent
  and disciplined.
- **Battle scars are encoded where they happened.** `pumpAsync` documents why
  `pumpAndSettle` wedges; `KernelFixture` encodes the T-280 teardown-hang fix;
  flake postmortems live as comments in the test that almost shipped them.
- **Security instincts**: 0600 socket + live-listener probe before unlink, git
  argv hardening with `--` terminators, `path_safety.dart` documenting its
  threat models inline, workspace-relative binary resolution forbidden (T-98).
- **Zero TODO/FIXME/HACK** across the tree. The clean-board policy is lived.

Patterns worth *extending* (the reviewers kept wishing other code did this):
the coalesced-notify `Timer(Duration.zero)` trick in `ConversationController`,
the pure-Dart-core/thin-Flutter-shell split, and `RecordingEventSink`-style
event-driven test waits.

---

## Part II — The bestiary (bugs I would fix, in order)

### 🐉 Dragons (high severity, verified, fix this week)

1. **Every naturally-exited PTY leaks its master fd — forever.**
   `lib/src/pty/native_pty.dart:444-450` — on child EOF, `_reap()` sets
   `_dead = true` but never closes `_fd`; a later `close()` short-circuits at
   `if (_dead) return;` (line 460) so `_nativeClose(_fd)` (line 477) never runs.
   Two reviewers found this independently. Every terminal/Claude pane whose
   child exits on its own leaks an fd and a pty device for the life of the app.

2. **The Claude child process is observed only via stdout.** Three reviewers
   converged here. `lib/builtin/claude/src/stream_json_session.dart:43-78` —
   stderr is *never drained* (≥64KB of `--verbose` spew = pipe fills = child
   blocks mid-turn = the flagship pane wedges with zero diagnostics), and
   nothing watches `exitCode` or `onDone` (line 303), so a crashed/dead
   session just looks… thoughtful. Drain stderr into a ring buffer, surface a
   terminal `SessionEnded` state. This also intersects T-283 (no resume
   timeout/fallback).

3. **The MCP HTTP server exposes the entire dispatcher with zero auth.**
   `lib/src/ipc/mcp_server.dart:138-195`, started unconditionally at boot
   (`lib/main.dart:174-180`). D-71's threat model ("another user on the same
   host should not drive my IDE") is enforced with 0600 on the unix socket —
   and then bypassed wholesale by an unauthenticated localhost HTTP port that,
   since D-86, serves *every* clide verb as a tool. Generate a token in the
   lock file (Claude Code's own `/ide` lock format has a slot for it), require
   the header.

4. **`editor.open`/`editor.save` skip path confinement entirely.**
   `lib/src/editor/registry.dart:215-219` returns absolute paths verbatim, no
   `..` normalization, no `path_safety` call — an unconfined read *and write*
   primitive over IPC while `files.read` is carefully guarded. Same family:
   **`search.replace` silently ignores its include/exclude globs**
   (`lib/src/search/replace_engine.dart:124-143`) and will happily rewrite
   files outside the filter the user typed; and **`listDir`'s symlink
   detection is dead code** (`lib/src/files/listing.dart:46-54` — `stat()`
   follows links, so `isSymlink` is always false) which means `walkFiles`
   descends symlinked dirs the docs claim it skips.

5. **Closing a terminal pane never closes the shell.**
   `lib/builtin/terminal/src/terminal_pane.dart:131-137` calls
   `ClideKernel.of(context)` from `dispose()` — illegal ancestor lookup,
   swallowed by `catch (_)` — so `pane.close` is never sent and the backend
   PTY + daemon pane leak. The same idiom leaks the settings listener in every
   disposed `ClaudePane` (`claude_pane.dart:460-466`). Combined with dragon #1
   this is a two-stage leak pipeline. Cache the kernel ref in
   `didChangeDependencies`, delete the catch-all.

6. **Project switch leaks the entire previous workspace.**
   `lib/main.dart:335-344` — a new dispatcher gets fresh `PaneRegistry`,
   `FilesService`, `EditorRegistry`, etc., but nothing calls the old set's
   `shutdown()` methods (which exist and have zero callers). Old watchers keep
   emitting into the new workspace's bus.

7. **T-274's root cause, found and verified:** the status bar is empty because
   `statusStream` is a plain broadcast controller — the `system/init` event
   fires while `spawn()` is still awaiting a 256KB transcript-tail read, before
   the pane ever subscribes (`claude_pane.dart:322`,
   `session_orchestrator.dart:222-225`). Seed from `session.status` on bind, or
   make it replay-latest. (The broadcast-without-replay shape is a recurring
   bug factory — see Part III.)

8. **Auto-scroll yanks a scrolled-up reader to the bottom on every streamed
   token.** `conversation_view.dart:268-277` — the `_atBottom` pin exists but
   is only consulted on viewport *resize*, not on new items. Anyone reading
   earlier output during a long streaming reply is dragged to the bottom
   continuously. One-line gate + the missing twin test.

9. **The terminal can crash on garbled output.** SGR 38/48 extended-color
   parsing does unguarded `params[i + 1]` lookahead
   (`lib/src/terminal/src/core/escape/parser.dart:501-516`) — `printf '\e[38m'`
   throws RangeError inside `Terminal.write`. An emulator must never throw on
   hostile bytes. While in there: colon-form SGR sub-parameters are mangled
   into bogus params.

10. **A11y has drifted despite being a Tier-0 contract.** Two independent
    verified findings: `ClideCollapserCard`'s `excludeSemantics: true` wipes
    *every expanded child* from the a11y tree
    (`lib/widgets/src/clide_collapser_card.dart:92-101`) — a screen-reader user
    can expand a run and hear nothing; and the three a11y gate tests
    hand-enumerate their subjects and have measurably fallen behind `lib/`
    (contrast checks fewer themes than `main.dart:443-454` loads; i18n checks 4
    of 8 namespaces). The gates stay green while covering less. Make `lib/`
    export the canonical lists and iterate them in the gates.

### 🦂 Scorpions (medium — real, will sting eventually)

- **D-72's "serial dispatch" isn't.** `lib/src/ipc/server.dart:151-180` uses an
  `async` onData without pausing the subscription — pipelined requests
  interleave, and the shared `StringBuffer` framing can drop/double lines.
  `client.cast<List<int>>().transform(utf8.decoder).transform(LineSplitter())`
  + `await for` fixes framing, UTF-8 split chunks, and serialization at once.
- **Split-chunk UTF-8 corruption is endemic at byte→String seams**: the
  terminal's only ingestion API is `write(String)` (`terminal.dart:218`) so
  both consumers decode per-chunk; `FileTailFollower` starts mid-character by
  construction. Add `writeBytes()` with a persistent chunked decoder.
- **`Orchestrator.spawn()` races itself** — check-then-act across two awaits;
  concurrent spawns for one id leak a live `claude` process
  (`session_orchestrator.dart:191-249`). Hold a `Map<String, Future<ManagedSession>>`.
- **Fork panes misbehave on `/clear`, `/resume`, `/fork`** —
  `widget.forkSourceId` wins forever, so `/clear` *re-forks the original
  conversation* instead of clearing (`claude_pane.dart:266-281`).
- **Settings persistence corrupts maps-inside-lists on write**
  (`settings.dart:199-219` emits `toString()`), breaking the documented keymap
  overlay across restarts; writes are non-atomic and a parse failure silently
  resets all settings.
- **Extension activation isn't transactional** — a throw mid-contribution
  leaves contributions mounted while the extension records as failed; retry
  double-applies (`extensions_manager.dart:133-192`). Plus: disabling an
  extension ignores dependents, and registries clobber silently on id
  collision — fine among curated builtins, hazardous the day Tier-6 Lua lands.
- **Terminal conformance debt** (the fork fixes what it trips over but has no
  vttest-style suite): HTS is a no-op (`isSetAt` instead of `setAt`,
  `terminal.dart:423`), DECCKM is tracked but never consumed, legacy mouse rows
  are off-by-one *and the test enshrines the bug*, CPR replies 0-based where
  every real terminal is 1-based, scrollback is maintained but structurally
  unreachable (`ViewportOffset.zero()` pinned every build,
  `terminal_view.dart:224`).
- **Markdown renderer**: hard breaks and images render as empty text (words
  glue together; `clide_markdown.dart:408-410`), and the whole document
  re-parses with sync `existsSync()` calls *inside build* on every streaming
  delta — multiplied by the conversation view re-deriving everything O(n) per
  notification and token streaming re-encoding the full reply per delta
  (O(n²) churn, `stream_json_session.dart:410-431`).
- **Terminal panes spawn in `Directory.current`**, not the open project root
  (`terminal_pane.dart:69`) — desktop launches get `$HOME` shells.
- **The Notifications service renders nowhere** — `notify.dart` has zero widget
  consumers; cli_install's dogfood warnings vanish into an unrendered list
  while `ToastService` sits right there.
- **Welcome screen no-ops**: "Clone from git…" and "Start a Claude session"
  advertise shortcuts that don't exist and do nothing on tap
  (`welcome_view.dart:173-174`).
- **`make test-e2e`/`ui-dev`/`ui-smoke` are dead** — `tools/ui/*.sh` still `cd`
  into the removed `app/` directory; the staged Gitea CI workflow would fail in
  three independent ways on activation, while D-32 calls it "ready."

### 🐀 Rats (low, but they breed)

Dead code worth a one-day extermination sweep: the entire legacy free-function
git API (~250 LOC duplicating `GitClient`, kept alive only by tests, *with its
own latent pipe-deadlock bug*), `ToolCheck`, ~60% of `ffi/libc.dart` (fd-passing
era), `GraphView` (unreachable placeholder), `ColumnHat` (duplicated
line-for-line in app.dart, kept alive by a zero-coverage test), the tmux-era
team pipeline (`TranscriptPublisher`, `TeamMemberJoined` — *nothing emits these
events*, yet the team roster UI still listens to them exclusively, meaning team
tiles are populated by ghosts), the dead `ptyc` binary still committed in
`native/linux-x64/` against D-62/D-63, and `mocktail` — pinned, documented in
D-25 as the IO-mocking strategy, and imported by exactly zero files.

---

## Part III — Patterns I would change (the systemic stuff)

1. **Broadcast streams that carry state need replay-latest.** This one shape
   caused T-274, the meta sidebar's manual compensation, and the
   prompt-stream's `initialData` workaround. Write a tiny `ValueStream` wrapper
   once; retrofit `statusStream`, `busyStream`, `pendingPromptStream`.

2. **Ban `catch (_) {}` on I/O and lifecycle paths.** The silent-swallow idiom
   turned an illegal-lookup-in-dispose into two resource leaks and turned
   process-spawn failures into blank panes. Cleanup paths may swallow; spawn,
   read, and dispose paths must log through the kernel Logger they already have.

3. **Sync I/O in async handlers on the single isolate.** `files.read` does a
   sync 10MB read; the replace engine reads and rewrites the workspace
   synchronously *while grep right next to it fans out to isolates per D-79*.
   Decide the rule (offload above N KB), write it into a D-record, apply it.

4. **Path confinement belongs at the dispatch layer, not per-verb.** files.read
   remembered, search.replace half-remembered, editor.* forgot. A confinement
   check keyed off the co-registered schema (the registry already knows which
   params are paths) ends the per-verb lottery.

5. **Copy-paste is the repo's main duplication tax.** The welcome screen clones
   FileActions' entire open-folder flow verbatim; palette and quick-open are
   ~230-line near-twins; three private "tail a growing file" implementations in
   the claude builtin alone; five hand-rolled `_userErr` helpers; five
   copy-pasted git test sandboxes (none isolating host git config); two
   parallel ANSI flag enums that already drifted (strikethrough is stored but
   never painted). Each is small; together they're how a solo-dev repo rots.

6. **Hand-enumerated lists drift; export the truth.** Bundled themes (already
   drifted between `main.dart` and the testmode harness — catppuccin is
   silently unvalidated), a11y gate subjects, i18n namespaces. One exported
   const each, consumed by both sides.

7. **The claude builtin returns `ok` with an `error` payload in 16 handlers**,
   drifting from the D-6 exit-code contract every other subsystem honors. A
   scripted `clide claude.agent.set-permission-mode bogus` exits 0 today.

8. **God-files**: `app.dart` (1187 LOC, five concerns — split plan is in the
   findings), `claude_meta_sidebar.dart` (1192), `parser.dart` (1139, T-123
   already exists — and the split should also fix `_consumeCsi` discarding
   intermediate bytes, which permanently blocks DECSCUSR/DECSTR).

9. **Docs drift at the front door**: CLAUDE.md and README still say "tmux owns
   Claude session persistence (D-41)" — superseded by D-75/D-77 per
   `docs/architecture.md`; README says "Pre-v2.0 (2.0.0-dev)" at v2.3.3 and
   headlines "canvas and graph surfaces" that are a 17-line stub and a flat
   ListView respectively. clide's honesty is its brand; the README is the one
   place currently off-brand.

10. **Close the release loop.** Five CHANGELOG releases since the last git tag;
    `ci/release.sh` exits 64 and references the dissolved sidecar; the pre-push
    fast path's safety argument cites "release CI on tagged versions" that
    doesn't exist; and the fast path skips ALL tests for pushes touching
    `test/`, `ci/`, or the hook itself. Back-tag 2.2.0–2.3.3, add tagging to
    the git-commit skill ritual, widen the fast-path regex. (This is also the
    blocking prerequisite your own T-47 refinement identified for self-update.)

---

## Part IV — Killer features (the dragon hoard)

Five ideation lenses, 27 proposals, deduplicated and ranked. The convergence
test mattered: **two lenses independently invented the flight recorder, and two
independently invented the visual canvas round-trip** — when separate agents
with different briefs land on the same feature, that's the market talking.

Clide's structural moats, verified against code: it *spawns and owns* the agent
process (D-77/D-78) where competitors are sandboxed extension guests; it owns
every pixel (terminal, markdown, canvas); everything is local-and-committed
(transcripts, costs, decisions, tickets) where competitors' business models
require cloud custody; and the pql vault is structured planning data no
mainstream IDE has an analogue for.

### Tier 1 — do these (high leverage, mostly M-effort, plumbing exists)

1. **Agent Blame + Session Flight Recorder** `[L]` — gutter action on any line:
   *which session, which turn, which prompt, which permission grant, what it
   cost* — opening the native conversation at the exact `tool_use`. Timeline
   scrubber to replay a session. The transcript pipeline
   (`transcript_reader.dart`, `session_index.dart`) already parses everything
   needed. Cursor/Copilot cannot ship this: their logs live server-side by
   business design. *Two lenses converged here.*

2. **Context X-ray** `[M]` — per-card token attribution ("this 40KB Bash tail
   is 12% of your window") + a real compaction indicator. `stream_json_session.dart`
   already parses usage and contextWindow per event; the renderer owns the
   cards. Fixes T-244 (invisible compaction) as a side effect. Context is the
   scarcest resource in agent pairing and every tool renders it as one opaque
   percentage.

3. **Trust Ledger + decision-aware permission prompts** `[M]` — every
   permission rule with provenance (which prompt, which session, which ticket),
   ticket-scoped expiry; and when a `can_use_tool` request arrives, chip the
   relevant D-record onto the card (edit touching pubspec.yaml → D-31
   prefer-zero-deps, one keystroke to deny *with the decision cited*).
   Governance stops being documentation and becomes live agent policy. No
   competitor has a queryable in-repo decision system to even attempt this.

4. **Agent Activity HUD** `[M]` — four backlog tickets and one open question
   are secretly one feature: build T-59's `OperationsRegistry` once and feed it
   git/pql progress (T-59), sidebar badges (T-58), compaction state (T-244),
   the status strip (T-274), with Q-34's budget slot reserved. Fix the T-274
   plumbing bug first or the HUD inherits blank-slot syndrome.

5. **Active Ticket Context** `[S]` ← *cheapest win in the whole list* — picking
   up a ticket binds it to the session: a "working on T-244" chip, auto
   `in_progress` flip, `(T-NNN)` pre-suggested in commit messages, changelog
   reminder on done. Makes kanban ambient instead of homework, and makes every
   trail/ledger feature below reliable.

### Tier 2 — the differentiators (L/XL, each could headline a release)

6. **Twin-timeline rewind** `[L]` — snapshot the worktree as hidden git refs
   (`git write-tree` → `refs/clide/checkpoints`) at every turn boundary, keyed
   to turn uuid; every user-message card gains "restore files to before this."
   Claude's `/rewind` only restores what Claude itself edited; clide owns both
   timelines.

7. **Visual Dialog** `[L]` — one bidirectional scene schema: Claude draws
   (D-91 canvas cards), the user annotates in the interaction zone (T-260), and
   the annotations return as *structured geometry + flattened PNG*, not prose.
   Merge the T-317/T-318 and T-260 specs into one protocol before they become
   two dialects. *Two lenses converged here.*

8. **Immortal terminals** `[M]` — T-258 (terminal as editor-mode peer) fused
   with T-325 live-tails: any long process — user shell *or* agent-spawned
   build — promotes to a full tmux-backed surface that survives restart.
   "The build that never dies" is structural for clide, a plugin fantasy for
   Electron. Resolve Q-27 (swap vs split) as part of it, as T-258 already notes.

9. **Local cost ledger** `[M]` — per-turn cost/tokens persisted against the
   active pql ticket; the board shows what each feature actually cost.
   Flat-subscription opacity is the competitors' business model; turn-level
   local cost data is clide's birthright. (Tokens primary, dollars advisory —
   subscription auth reports notional costs.)

10. **Label-routed work queues / ticket dispatch** `[M→XL]` — T-277 labels +
    the shipped pick-up path turn the board into an agent control surface;
    the XL extension dispatches a ticket to a teammate session in an isolated
    git worktree (SpawnSpec.cwd already exists). Local, no-telemetry
    background agents with the work item, isolation, review surface, and audit
    trail all in-repo.

### Tier 3 — moonshots (XL, pick one per quarter, they compound)

11. **Semantic terminal** — OSC 133 markers (clide spawns the shell, injection
    is trivial) lift scrollback into foldable command regions with recognizers
    for test runners and stack traces; real widgets between rows is something
    xterm.js structurally cannot do. *Note: fix the scrollback-unreachable bug
    first — a semantic scrollback you can't scroll is a koan.*
12. **Living codebase map** — tree-sitter imports + pql links + git churn on
    the owned canvas, with live agent heat from `tool_use` events: watch Claude
    *move through your codebase* in real time.
13. **Live mixed documents** — fenced blocks in the owned markdown renderer
    become live embeds (canvas scenes, pql query results, decision cards,
    confirm-gated command buttons). Notebook-grade, zero webview. The
    `ClideMarkdownHooks` seam already exists.
14. **Remote Claude over SSH** — T-329 is fully ticketed and undersold: agent
    on the buildbox, permission prompts rendering natively local. VS Code
    Remote moves the editor; nobody remotes the *agent control channel*.
15. **Sealed-workspace mode** — an egress-audit proxy around the whole agent
    stack, operationalizing D-60/D-64 into a provable property. The one
    feature in this list competitors *cannot* copy without breaking their own
    products.

### Honorable mentions

Plan-to-Board bridge (ExitPlanMode approval files the plan as a ticket tree),
Release Cockpit (renders `[Unreleased]` with word-count badges + one-action
release cut — would also unstall Part III #10), Daily Helm ("since you were
last here" pulse on the welcome screen, computed from data the repo already
commits), Total-recall conversation search (D-79 grep over the transcript
corpus + fork-from-here), Shared Gaze (attach editor selection/scroll context
to each outgoing turn), Speakable Layouts (`clide layout apply review.yaml` —
the agent stages your workspace), Agent fleet tray (enumerate per-workspace
sockets, show every repo's agent state — *requires fixing T-247's stale-socket
litter first*), Governance Graph (the D/Q/R/T web as a navigable map — gives
the placeholder graph view a flagship dataset).

---

## Part V — If I were you, Monday morning

1. **One leak-fix commit**: PTY fd on natural exit + kernel-lookup-in-dispose
   (terminal & claude panes) + project-switch service disposal. Three findings,
   one theme, one afternoon.
2. **One Claude-resilience commit**: drain stderr, watch exitCode, seed status
   on bind, gate auto-scroll on `_atBottom`. The flagship pane stops having
   silent failure modes.
3. **One security commit**: MCP auth token + editor.* path confinement +
   search.replace glob filter + symlink-walk fix.
4. **One rat-extermination day**: dead git API, ToolCheck, libc bindings,
   ColumnHat, GraphView, tmux-era team pipeline, ptyc binary, mocktail. The
   diff is gloriously red and the coverage denominator thanks you.
5. **Tag your releases.** Five releases of honest changelog work are currently
   unaddressable commits.
6. Then go build the **Active Ticket chip** (S!) and the **Context X-ray**, and
   let clide start showing people things no other IDE can.

---

*Findings methodology: every medium/high claim above survived an independent
adversarial re-read of the cited lines (one claim did not — the proposed
"can't-disable core extensions" guard, which D-14 deliberately rejects, so it
stays out of this report). The full per-finding evidence, severities, and
suggested fixes live in the review transcripts; ~34 additional low-severity
findings were verified by citation only.*

*— Fable, 2026-06-11*