Merge main into windows-support
Brings windows-support up to date with main (T-404/405/406, T-413–416, T-421, the T-422 workspace-lifecycle epic, and the 2.4.0 release). Conflict resolutions: - terminal_pane.dart: keep the Windows PowerShell shell selection and main's workspace-cwd fix (T-381) together. - tool_check.dart: accept main's deletion (dead, unreferenced code). - CHANGELOG.md: keep both Unreleased sections. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.8
+23
-2
@@ -66,7 +66,7 @@ You might also want, project-permitting:
|
||||
- [D-22: WCAG-AA contrast gate on bundled themes](decisions/accessibility.md#d-22-wcag-aa-contrast-gate-on-bundled-themes) — _accessibility_
|
||||
- [D-23: Test pyramid — seven layers](decisions/testing.md#d-23-test-pyramid--seven-layers) — _testing_
|
||||
- [D-24: Golden tests — primitives only, Alchemist + Ahem](decisions/testing.md#d-24-golden-tests--primitives-only-alchemist--ahem) — _testing_
|
||||
- [D-25: Mocks — mocktail at IO, hand-rolled fakes for ChangeNotifiers](decisions/testing.md#d-25-mocks--mocktail-at-io-hand-rolled-fakes-for-changenotifiers) — _testing_
|
||||
- [D-25: Mocks — hand-rolled fakes throughout; mocktail dropped](decisions/testing.md#d-25-mocks--hand-rolled-fakes-throughout-mocktail-dropped) — _testing_
|
||||
- [D-26: Web driver — raw Playwright + Flutter semantics](decisions/testing.md#d-26-web-driver--raw-playwright--flutter-semantics) — _testing_
|
||||
- [D-27: Startup regression gate](decisions/testing.md#d-27-startup-regression-gate) — _testing_
|
||||
- [D-28: Test organisation — mirror `lib/` in `test/`](decisions/testing.md#d-28-test-organisation--mirror-lib-in-test) — _testing_
|
||||
@@ -137,6 +137,10 @@ You might also want, project-permitting:
|
||||
- [D-93: clide writes no directories of its own into the workspace](decisions/architecture.md#d-93-clide-writes-no-directories-of-its-own-into-the-workspace) — _architecture_
|
||||
- [D-94: Workspace mode is a first-class, extensible declared capability](decisions/architecture.md#d-94-workspace-mode-is-a-first-class-extensible-declared-capability) — _architecture_
|
||||
- [D-95: Workspace validity and onboarding flow](decisions/architecture.md#d-95-workspace-validity-and-onboarding-flow) — _architecture_
|
||||
- [D-96: Remote-execution footprint — no-install ssh-exec](decisions/architecture.md#d-96-remote-execution-footprint--no-install-ssh-exec) — _architecture_
|
||||
- [D-97: ssh:// workspace URI + system-ssh auth](decisions/architecture.md#d-97-ssh-workspace-uri--system-ssh-auth) — _architecture_
|
||||
- [D-98: Remote-tool contract + connect preflight](decisions/architecture.md#d-98-remote-tool-contract--connect-preflight) — _architecture_
|
||||
- [D-99: Remote session identity keyed on (host, workspace)](decisions/architecture.md#d-99-remote-session-identity-keyed-on-host-workspace) — _architecture_
|
||||
|
||||
## Open questions
|
||||
|
||||
@@ -156,7 +160,6 @@ You might also want, project-permitting:
|
||||
- [Q-17: Icon set growth](questions/process.md#q-17-icon-set-growth) — _process_
|
||||
- [Q-18: Theme hot-reload in release builds](questions/process.md#q-18-theme-hot-reload-in-release-builds) — _process_
|
||||
- [Q-20: Kernel DB service — namespaced SQL access?](questions/process.md#q-20-kernel-db-service--namespaced-sql-access) — _process_
|
||||
- [Q-23: SSH-remote development — run clide against a remote workspace](questions/architecture.md#q-23-ssh-remote-development--run-clide-against-a-remote-workspace) — _architecture_
|
||||
- [Q-25: Body text face — mono everywhere vs Josefin Sans UI + mono code](questions/architecture.md#q-25-body-text-face--mono-everywhere-vs-josefin-sans-ui--mono-code) — _architecture_
|
||||
- [Q-26: Small screen layout (< 1000px)](questions/architecture.md#q-26-small-screen-layout--1000px) — _architecture_
|
||||
- [Q-27: Two-editor split](questions/architecture.md#q-27-two-editor-split) — _architecture_
|
||||
@@ -164,6 +167,23 @@ You might also want, project-permitting:
|
||||
- [Q-30: Focus behavior when editor is dirty and viewer is peeked](questions/architecture.md#q-30-focus-behavior-when-editor-is-dirty-and-viewer-is-peeked) — _architecture_
|
||||
- [Q-31: XWayland fallback for frameless — proper Wayland protocol needed](questions/architecture.md#q-31-xwayland-fallback-for-frameless--proper-wayland-protocol-needed) — _architecture_
|
||||
- [Q-34: How + when to surface the account/team token budget given upstream doesn't expose it](questions/architecture.md#q-34-how--when-to-surface-the-accountteam-token-budget-given-upstream-doesnt-expose-it) — _architecture_
|
||||
- [Q-35: Agent Blame + Session Flight Recorder — implement?](questions/design.md#q-35-agent-blame--session-flight-recorder--implement) — _design_
|
||||
- [Q-36: Context X-ray — implement?](questions/design.md#q-36-context-x-ray--implement) — _design_
|
||||
- [Q-37: Trust Ledger + decision-aware permission prompts — implement?](questions/design.md#q-37-trust-ledger--decision-aware-permission-prompts--implement) — _design_
|
||||
- [Q-38: Agent Activity HUD — implement?](questions/design.md#q-38-agent-activity-hud--implement) — _design_
|
||||
- [Q-39: Active Ticket Context — implement?](questions/design.md#q-39-active-ticket-context--implement) — _design_
|
||||
- [Q-40: Twin-timeline rewind — implement?](questions/design.md#q-40-twin-timeline-rewind--implement) — _design_
|
||||
- [Q-41: Visual Dialog — one bidirectional scene schema — implement?](questions/design.md#q-41-visual-dialog--one-bidirectional-scene-schema--implement) — _design_
|
||||
- [Q-42: Immortal terminals — implement?](questions/design.md#q-42-immortal-terminals--implement) — _design_
|
||||
- [Q-43: Local cost ledger — implement?](questions/design.md#q-43-local-cost-ledger--implement) — _design_
|
||||
- [Q-44: Label-routed work queues / ticket dispatch — implement?](questions/design.md#q-44-label-routed-work-queues--ticket-dispatch--implement) — _design_
|
||||
- [Q-45: Semantic terminal — implement?](questions/design.md#q-45-semantic-terminal--implement) — _design_
|
||||
- [Q-46: Living codebase map — implement?](questions/design.md#q-46-living-codebase-map--implement) — _design_
|
||||
- [Q-47: Live mixed documents — implement?](questions/design.md#q-47-live-mixed-documents--implement) — _design_
|
||||
- [Q-48: Sealed-workspace mode — implement?](questions/design.md#q-48-sealed-workspace-mode--implement) — _design_
|
||||
- [Q-49: Review honorable mentions — which, if any, get promoted?](questions/design.md#q-49-review-honorable-mentions--which-if-any-get-promoted) — _design_
|
||||
- [Q-50: Web/WASM target after the dart:ffi pivot — fence, fix, or drop?](questions/architecture.md#q-50-webwasm-target-after-the-dartffi-pivot--fence-fix-or-drop) — _architecture_
|
||||
- [Q-51: Unify workspace lifecycle on a single fenced open primitive](questions/architecture.md#q-51-unify-workspace-lifecycle-on-a-single-fenced-open-primitive) — _architecture_
|
||||
|
||||
## Resolved questions
|
||||
|
||||
@@ -173,6 +193,7 @@ You might also want, project-permitting:
|
||||
- [Q-19: (withdrawn)](questions/process.md#q-19-withdrawn) — _process_
|
||||
- [Q-21: Pql absorbs planning vs keeps separate](questions/architecture.md#q-21-pql-absorbs-planning-vs-keeps-separate) — _architecture_
|
||||
- [Q-22: Ticket persistence strategy](questions/architecture.md#q-22-ticket-persistence-strategy) — _architecture_
|
||||
- [Q-23: SSH-remote development — run clide against a remote workspace](questions/architecture.md#q-23-ssh-remote-development--run-clide-against-a-remote-workspace) — _architecture_
|
||||
- [Q-28: Terminal strip scope — shell only or logs/errors/tests](questions/architecture.md#q-28-terminal-strip-scope--shell-only-or-logserrorstests) — _architecture_
|
||||
- [Q-32: MCP tool surface — minimum slash-ide or extended clide tools?](questions/architecture.md#q-32-mcp-tool-surface--minimum-slash-ide-or-extended-clide-tools) — _architecture_
|
||||
- [Q-33: MCP transport — SSE, WebSocket, stdio, or all?](questions/architecture.md#q-33-mcp-transport--sse-websocket-stdio-or-all) — _architecture_
|
||||
|
||||
@@ -73,7 +73,7 @@ Core, rendering, IPC, kernel, panel manager.
|
||||
### D-10: State management — `ChangeNotifier` + `ListenableBuilder`
|
||||
- **Date:** 2026-04-21
|
||||
- **Decision:** Per-feature state uses `ChangeNotifier` exposed through a feature facade (singleton-per-kernel); widgets subscribe via `ListenableBuilder`. No Riverpod, Provider, BLoC, or Redux.
|
||||
- **Rationale:** SDK-shipped, zero deps, trivial to fake in tests (hand-rolled fakes in [D-25](testing.md#d-25-mocks--mocktail-at-io-hand-rolled-fakes-for-changenotifiers)). Violates [D-31 prefer-zero-deps](tooling.md#d-31-prefer-zero-deps-exact-pin) otherwise. See [R-8](../rejected/architecture.md#r-8-riverpod--provider--bloc-for-state).
|
||||
- **Rationale:** SDK-shipped, zero deps, trivial to fake in tests (hand-rolled fakes in [D-25](testing.md#d-25-mocks--hand-rolled-fakes-throughout-mocktail-dropped)). Violates [D-31 prefer-zero-deps](tooling.md#d-31-prefer-zero-deps-exact-pin) otherwise. See [R-8](../rejected/architecture.md#r-8-riverpod--provider--bloc-for-state).
|
||||
- **Cost:** No codegen ergonomics; manual `notifyListeners()` discipline. The `ListenableBuilder.listenable` contract rejects rebuilds outside the subscribed notifier — intentional.
|
||||
- **Raised by:** 2026-04-21 planning.
|
||||
|
||||
@@ -500,4 +500,38 @@ Core, rendering, IPC, kernel, panel manager.
|
||||
- **Cross-reference:** [D-3](#d-3-pql-as-supporter-tool-clide-wraps-never-duplicates), [D-4](#d-4-ignore-file-strategy), [D-67](process.md#d-67-pql-changelog-files-are-committed-alongside-code), [D-79](#d-79-workspace-content-search-is-a-pure-dart-in-process-engine-outside-pql), [D-80](#d-80-filesread-allows-trusted-claude-config-roots-beyond-the-workspace), [D-92](tooling.md#d-92-ship-pql-bundled-with-clide), [D-94](#d-94-workspace-mode-is-a-first-class-extensible-declared-capability).
|
||||
- **Raised by:** 2026-06-11 — user, this planning session: a repo without `.pql/` is "invalid for clide"; non-git folder → "offer default no"; planning hooks contextual; unwritable repos degrade.
|
||||
|
||||
### D-96: Remote-execution footprint — no-install ssh-exec
|
||||
- **Date:** 2026-06-12
|
||||
- **Decision:** SSH-remote workspaces (T-329, shape A of [Q-23](../questions/architecture.md#q-23-ssh-remote-development--run-clide-against-a-remote-workspace)) use **stock OpenSSH only — nothing clide-specific is ever installed on the remote.** Interactive surfaces (terminal panes, the Claude process) run over `ssh -tt` PTY channels; command-style subsystems (git, pql, file ops, search) run as exec channels multiplexed over a persistent **ControlMaster** connection; file watching degrades to **polling** (debounced mtime/git-status sweep, `inotifywait` used opportunistically when present) that emits the same FileChange events, so the UI layer is unaware of the difference. Subsystems reach the remote through a `RemoteExecutionContext` seam instead of bare `Process.run`/`File`/`Directory`. The rejected alternative — an auto-pushed self-managed remote agent (VS Code Remote model) — would have bought native inotify and a stateful remote backend at the price of deploying and version-managing clide components on the remote.
|
||||
- **Rationale:** The user's standing constraint is decisive: no clide components to install, update, GC, or version-reconcile on remote machines. Zero-footprint also dissolves the agent model's open sub-questions (placement, multi-client sharing, version skew, cleanup) — they simply don't arise. The costs (per-command round-trip, polling watcher) are bounded and amortizable (ControlMaster reuses one authenticated connection); the agent model's costs are operational and permanent.
|
||||
- **D-56 reconciliation:** [D-56](#d-56-dissolve-daemon-process-flutter-app-hosts-ipc-server)'s "single process" rule is *strengthened*, not bent: with no-install there is no second clide process anywhere — the local Flutter app remains the only clide process, and the remote side is plain sshd + the tools already on the box. [D-5](#d-5-dart-core-sidecar-dissolved-ptyc-as-pql-peer) is likewise untouched — ssh is an external tool clide shells out to, not a second core language or runtime.
|
||||
- **Cost:** Every remote command pays an SSH round-trip (ControlMaster removes handshake cost, not latency). Watching is polling-grade — change events arrive on the sweep cadence, not instantly. The execution-context seam must be threaded through each subsystem that touches the filesystem or spawns processes; that sweep is the bulk of T-336. No stateful remote backend means event streams are synthesized locally from command results.
|
||||
- **Cross-reference:** Resolves [Q-23](../questions/architecture.md#q-23-ssh-remote-development--run-clide-against-a-remote-workspace). [D-97](#d-97-ssh-workspace-uri--system-ssh-auth) (naming + auth), [D-98](#d-98-remote-tool-contract--connect-preflight) (what must exist remotely), [D-99](#d-99-remote-session-identity-keyed-on-host-workspace) (identity), [D-94](#d-94-workspace-mode-is-a-first-class-extensible-declared-capability) (remote workspaces surface as a workspace mode — the reserved `ssh` value — so extensions gate on it declaratively). Implemented by the T-329 epic; execution layer is T-336.
|
||||
- **Raised by:** 2026-06-12 — user, resolving the T-330 footprint spike: "go with the no-install ssh-exec model."
|
||||
|
||||
### D-97: ssh:// workspace URI + system-ssh auth
|
||||
- **Date:** 2026-06-12
|
||||
- **Decision:** A remote workspace is named by the URI `ssh://[user@]host[:port]/abs/remote/path`. `host` may be a `~/.ssh/config` alias; user/port are optional and, when absent, resolve through ssh's own config machinery. **Auth delegates entirely to system ssh** — agent, keys, `~/.ssh/config`, ProxyJump, all of it; clide never stores credentials or implements an auth flow of its own. v1 connections run ssh in **BatchMode** (non-interactive): when auth would prompt, the connect fails with an actionable message ("set up key auth / ssh-agent for <host>") instead of clide hosting a password dialog. Windows (no standard ssh config surface) is an acknowledged v1 gap. The `WorkspaceRef` value type (T-332) is the canonical carrier — parse/round-trip of this URI, `host:path` display form, bare-path = local.
|
||||
- **Rationale:** Matches the epic's locked auth posture and pql's "wrap, don't duplicate" instinct applied to OpenSSH: the user's existing ssh config is the source of truth, and anything clide reimplements (agents, prompts, jump hosts) would be a worse, second implementation of it. BatchMode keeps the failure mode crisp instead of wedging a TTY prompt inside a GUI flow.
|
||||
- **Cost:** First-run UX depends on the user's ssh hygiene — no in-app password fallback. Host-alias resolution means the same workspace can be reachable under two names (`buildbox` vs `buildbox.lan`) and be keyed as two identities ([D-99](#d-99-remote-session-identity-keyed-on-host-workspace) keys on the *given* host string; aliasing dedupe is deliberately not attempted).
|
||||
- **Cross-reference:** [D-96](#d-96-remote-execution-footprint--no-install-ssh-exec), [D-99](#d-99-remote-session-identity-keyed-on-host-workspace). Implemented by T-332 (WorkspaceRef landed 2026-06-12; open-flow pending T-336).
|
||||
- **Raised by:** 2026-06-12 — T-330 spike artifacts, URI shape locked at epic planning (2026-06-10).
|
||||
|
||||
### D-98: Remote-tool contract + connect preflight
|
||||
- **Date:** 2026-06-12
|
||||
- **Decision:** What must exist on the remote, and what merely degrades. **Required:** a POSIX shell and `git` — without them the workspace cannot open (workspace validity, [D-95](#d-95-workspace-validity-and-onboarding-flow), requires a git repo). **Optional, degrading:** `pql` — absent, the planning/query surfaces (tickets, decisions, vault queries) go dark behind a banner, mirroring [D-95](#d-95-workspace-validity-and-onboarding-flow)'s read-mode degrade; clide cannot provision pql remotely under [D-96](#d-96-remote-execution-footprint--no-install-ssh-exec)'s no-install rule, so the banner tells the user what to install where. **Optional, degrading:** `claude` — absent, the Claude pane is disabled with a notice; terminal/editor/git stay fully live. On connect, a single batched preflight command probes all of these (one round-trip: `command -v` + version for each) and the result drives the degrade set; a missing *required* tool fails the open with the probe output.
|
||||
- **Rationale:** The contract keeps "remote" honest without smuggling an installer in: clide states what it found, works with what's there, and never mutates the remote toolset. One batched probe respects the per-command latency cost [D-96](#d-96-remote-execution-footprint--no-install-ssh-exec) accepts. Folding pql-absence into the existing degrade vocabulary (D-94 modes / D-95 banner) reuses a shipped pattern instead of inventing a remote-special one.
|
||||
- **Cost:** A degraded-but-open remote workspace is a new partial state to keep coherent (which surfaces dark, which live). Version *skew* (remote pql older than the bundled local one) is real and detected by the preflight but only surfaced, not reconciled, in v1.
|
||||
- **Cross-reference:** [D-92](tooling.md#d-92-ship-pql-bundled-with-clide) (bundling is local-only under no-install), [D-94](#d-94-workspace-mode-is-a-first-class-extensible-declared-capability), [D-95](#d-95-workspace-validity-and-onboarding-flow), [D-96](#d-96-remote-execution-footprint--no-install-ssh-exec).
|
||||
- **Raised by:** 2026-06-12 — T-330 spike artifacts ("decide the remote-tool contract: what must exist remotely, whether pql is hard-required or degrades, and how a preflight surfaces what is missing").
|
||||
|
||||
### D-99: Remote session identity keyed on (host, workspace)
|
||||
- **Date:** 2026-06-12
|
||||
- **Decision:** Workspace-keyed identity generalizes from *path* to *(host, path)* — local workspaces are `(null, path)`, so nothing changes for them. Consequences: Claude session identity ([D-41](#d-41-claude-panes-one-primary-per-repo-tmux-backed)'s one-primary-per-repo, [D-77](#d-77-drive-claude-via-the-stream-json-control-protocol-teams-become-a-clide-owned-coordination-layer)'s stream-json sessions) re-keys on (host, repo) — the same repo path on two hosts (or local + remote) is two distinct sessions, never one; Claude's `--resume` transcripts live on the host where claude runs (the remote's `~/.claude/…`), which falls out naturally because claude is spawned remotely. Per-workspace user-scope state ([D-93](#d-93-clide-writes-no-directories-of-its-own-into-the-workspace)/[D-70](#d-70-ipc-socket-path-is-per-workspace-deterministic)'s path-hash keying) hashes the WorkspaceRef canonical URI instead of the bare path — same generalization, same machinery. The host string is taken as given (alias ≠ FQDN; no dedupe, per [D-97](#d-97-ssh-workspace-uri--system-ssh-auth)).
|
||||
- **Rationale:** Path-only keying would silently fuse two different machines' checkouts of the same repo path into one session/layout/socket identity — wrong in every case. Hashing the canonical URI is the smallest amendment that fixes this everywhere at once, because every consumer already keys off one derived string.
|
||||
- **Amends [D-41](#d-41-claude-panes-one-primary-per-repo-tmux-backed) / [D-77](#d-77-drive-claude-via-the-stream-json-control-protocol-teams-become-a-clide-owned-coordination-layer):** "per repo" reads as "per (host, repo)" throughout; local keeps its existing identity (null host hashes identically to the pre-amendment bare path — no migration).
|
||||
- **Cost:** Renaming a host alias re-keys its sessions and layout state (accepted; same trade-off D-70 already made for moved repos).
|
||||
- **Cross-reference:** [D-41](#d-41-claude-panes-one-primary-per-repo-tmux-backed), [D-70](#d-70-ipc-socket-path-is-per-workspace-deterministic), [D-77](#d-77-drive-claude-via-the-stream-json-control-protocol-teams-become-a-clide-owned-coordination-layer), [D-93](#d-93-clide-writes-no-directories-of-its-own-into-the-workspace), [D-96](#d-96-remote-execution-footprint--no-install-ssh-exec), [D-97](#d-97-ssh-workspace-uri--system-ssh-auth). Implemented across T-332 (identity carrier) and T-333 (session re-key).
|
||||
- **Raised by:** 2026-06-12 — T-330 spike artifacts ("session identity keyed on (host, repo) amending D-41/D-77").
|
||||
|
||||
---
|
||||
|
||||
@@ -18,10 +18,10 @@ Test pyramid, drivers, client-side constraint.
|
||||
- **Cost:** Goldens have zero real text; layouts rely on widget tests. Acceptable.
|
||||
- **Raised by:** 2026-04-21 planning.
|
||||
|
||||
### D-25: Mocks — mocktail at IO, hand-rolled fakes for ChangeNotifiers
|
||||
- **Date:** 2026-04-21
|
||||
- **Decision:** `mocktail 1.0.4` mocks IO boundaries (sockets, processes, `dart:io` File/Directory). `ChangeNotifier` facades get hand-rolled fakes — tiny classes that extend `ChangeNotifier` with test-controlled setters. No `mocktail` for notifiers.
|
||||
- **Rationale:** Mocking a `ChangeNotifier` with a generated mock hides subscription bugs — `notifyListeners` becomes a mock call instead of actually firing. Hand-rolled fakes exercise the real subscription machinery.
|
||||
### D-25: Mocks — hand-rolled fakes throughout; mocktail dropped
|
||||
- **Date:** 2026-04-21 (amended 2026-06-12)
|
||||
- **Decision:** Test doubles are hand-rolled fakes — tiny classes that extend the real base (`ChangeNotifier` facades, `StreamJsonProcess`, `DaemonClient`) with test-controlled setters. **Amendment (2026-06-12, T-385):** `mocktail` was originally pinned for IO boundaries, but after the T-91 coverage drive it had zero imports — every IO seam ended up with an injected hand-rolled fake (`FakeDaemonClient`, fake process factories, recording event sinks) instead. The unused dep is dropped; the no-mocks-for-notifiers rule stands and in practice covers IO seams too.
|
||||
- **Rationale:** Mocking a `ChangeNotifier` with a generated mock hides subscription bugs — `notifyListeners` becomes a mock call instead of actually firing. Hand-rolled fakes exercise the real subscription machinery. The same held at IO seams: constructor-injected fakes kept tests on real control flow.
|
||||
- **Cost:** Roughly 20 lines per fake. Rounds out to less code than configuring a mocktail whenCall chain.
|
||||
- **Raised by:** 2026-04-21 planning.
|
||||
|
||||
|
||||
@@ -60,9 +60,15 @@ ticket persistence.
|
||||
- **Source:** 2026-04-21 planning.
|
||||
|
||||
### Q-23: SSH-remote development — run clide against a remote workspace
|
||||
- **Status:** Open
|
||||
- **Status:** Resolved → [D-96](../decisions/architecture.md#d-96-remote-execution-footprint--no-install-ssh-exec), [D-97](../decisions/architecture.md#d-97-ssh-workspace-uri--system-ssh-auth), [D-98](../decisions/architecture.md#d-98-remote-tool-contract--connect-preflight), [D-99](../decisions/architecture.md#d-99-remote-session-identity-keyed-on-host-workspace)
|
||||
- **Resolved (2026-06-12):** Shape (A) — execution remote, UI local — with the **no-install ssh-exec** footprint (user pick): stock OpenSSH only, `ssh -tt` PTYs + ControlMaster exec channels, polling watcher, zero clide components on the remote (D-96). Naming/auth via `ssh://` URI + system ssh in BatchMode (D-97); remote-tool contract with batched connect preflight (D-98); session + state identity re-keyed on (host, repo), amending D-41/D-77 (D-99). Implementation: T-329 epic, execution layer T-336.
|
||||
- **Question:** Clide today assumes the workspace, the daemon, and the Flutter UI all run on the same machine. A growing class of users edits on remote systems (build servers, GPU boxes, cloud dev environments). What's the architecture for "open repo on host-B from UI on host-A"? Two shapes: (A) daemon-on-remote — clide's Dart daemon runs on the remote; the app talks to it over an SSH-tunnelled unix socket or a dedicated TCP socket (mTLS?), pty/process/filesystem work stays server-side; local app is pure UI. (B) filesystem-mounted — remote mounted via sshfs/9p/rclone, daemon runs locally against the mount; simpler but every fs op + git call crosses the network, and PTYs get complicated (local shell on remote filesystem? ssh-exec per command?). (A) matches VS Code Remote / JetBrains Gateway; (B) matches nothing load-bearing. Sub-questions either way: auth (ssh-agent? per-project keys? OIDC?), tmux / Claude session persistence semantics (does primary-per-repo re-key on host + repo?), multi-host identity in `.pql/pql.db`, latency tolerance for the event stream, re-sync on disconnect.
|
||||
- **Context:** Surfaced 2026-04-22 during Tier-1 planning. Not a Tier 1 concern — terminal + Claude panes land local-first — but the daemon/IPC seam decisions (notably `D-5` and `D-6`) constrain the future answer. Worth scoping before Tier 6 (extension API) so third-party extensions don't accrue assumptions the remote path would have to unwind.
|
||||
- **Context:** Surfaced 2026-04-22 during Tier-1 planning. Not a Tier 1 concern — terminal + Claude panes land local-first — but the daemon/IPC seam decisions (notably `D-5` and `D-6`) constrain the future answer. Worth scoping before Tier 6 (extension API) so third-party extensions don't accrue assumptions the remote path would have to unwind. The 2026-06-11 Fable review (fable-ous.md Part IV, Tier 3 #14) reframed the differentiator and ranked T-329 as undersold: the agent runs on the buildbox while permission prompts render natively local — VS Code Remote moves the *editor*; nobody remotes the *agent control channel*. That framing favours shape (A).
|
||||
- **Triage (2026-06-12):** Shape (A) is effectively settled (T-329 epic locked: execution remote, UI + clipboard local, system ssh auth for v1). The model-independent backbone is proceeding: Phase 1 (T-331, `DaemonTransport` seam) landed. What remains open is the **footprint model** — the user decision T-330 gates on:
|
||||
1. **No-install ssh-exec** — zero remote footprint; stock `ssh -tt` PTYs + ControlMaster command channels; watching degrades to polling; heavier subsystem surface locally.
|
||||
2. **Auto-pushed self-managed agent** (VS Code Remote model) — clide deploys/version-checks a headless agent binary on connect; native inotify + stateful backend; but installs clide components on the remote, which the user has said they don't want to manage.
|
||||
|
||||
If (2), the agent sub-questions need answers before T-336 expands: placement (per-host `~/.clide/agent` likely), GC on disconnect/version-bump/repo-removal, multi-client sharing (IpcServer is already multi-connection, D-72), version skew (version-named binaries coexist). Either way the **remote-tool contract** needs a D-record: what must exist remotely (git/shell at minimum), whether pql is hard-required or degrades, and how a connect-preflight surfaces gaps. Evidence gap: the ControlMaster per-command latency probe (T-330) needs a reachable sshd — none in the dev environment; run it against a real remote before deciding if latency is the deciding factor.
|
||||
- **Source:** 2026-04-22 planning (user-raised).
|
||||
|
||||
### Q-22: Ticket persistence strategy
|
||||
@@ -153,4 +159,16 @@ ticket persistence.
|
||||
- **Context:** The only unshipped piece of the otherwise-complete native-Claude epic (T-132). Blocked on data availability, not on clide work — hence a question (when/how to revisit) rather than active scope. Option (c) interacts with D-75's "version-pinned coupling to CC internals" posture. Resolved by T-158 when a viable path lands.
|
||||
- **Source:** 2026-06-09 — split out of T-132 / T-158 (was "blocked on upstream"); project memory `claude-usage-budget-not-exposed`, GitHub anthropics/claude-code#44328.
|
||||
|
||||
### Q-50: Web/WASM target after the dart:ffi pivot — fence, fix, or drop?
|
||||
- **Status:** Open
|
||||
- **Question:** `flutter build web --wasm` no longer compiles: the tree-sitter FFI pivot and the native PTY both import `dart:ffi` unconditionally, which the wasm target forbids. That kills `make test-e2e` / `ui-dev` / `ui-smoke` and the Playwright harness regardless of the `cd app` staleness T-384 fixed. Options: (a) fence every `dart:ffi` import behind conditional imports with web stubs (ongoing tax on every future native binding, for a target CLAUDE.md calls "a happy accident"); (b) keep the harness parked and re-evaluate if/when a web build matters (D-26's Playwright driver stays dormant); (c) drop the web target + `tools/ui/` harness formally and amend D-26/D-32. The guardrail says don't compromise desktop fidelity for web — (a) leans against it; (b) defers; (c) is honest but irreversible-ish.
|
||||
- **Context:** Surfaced 2026-06-12 while fixing T-384 (dead make targets). The mechanical path fixes (post app/-flattening) are done; the Gitea workflow's e2e job is withheld with a pointer here. The startup-regression gate (D-27) and integration tests are unaffected — only the browser/Playwright surface is blocked.
|
||||
- **Source:** T-384 / 2026-06-11 Fable review (epic T-359).
|
||||
|
||||
### Q-51: Unify workspace lifecycle on a single fenced open primitive
|
||||
- **Status:** Open
|
||||
- **Question:** There is no single "open workspace X" primitive — only two half-primitives in different layers. `project.open(root)` (`lib/kernel/src/project.dart`) is the only repo-targeting path and is intrinsically *in-place*: it rebuilds services in the same process, reusing the shared `daemonBus`. `newWindow()` (`lib/builtin/menubar/src/file_actions.dart`) spawns a blank detached `Process.start` with no repo argument and no env scrubbing. To open a repo in a *new* window you must spawn a blank window and then run the in-place switch inside it. Should both fold behind one `WorkspaceService.open(root, {target: thisWindow | newWindow})` that is the *sole* deriver of IPC identity from a root — and, more fundamentally, should in-place switching survive at all, or should `workspace ⇒ window ⇒ process ⇒ socket ⇒ bus ⇒ session-id` be strictly one-to-one so the leak/bleed class becomes structurally impossible?
|
||||
- **Context:** Surfaced 2026-06-14 from [T-421](../../) (status-bar branch bleeds across parallel windows). The same root cause — scattered, per-entry-point workspace lifecycle with no single fencing owner — already produced T-367 (in-place switch leaked the entire previous service set) and T-269 (kept the previous repo's Claude session). If in-place switching is abolished, the teardown burden those tickets patch disappears entirely. Relevant decisions: [D-70](../decisions/architecture.md) (per-workspace socket path), [D-56](../decisions/architecture.md) (one server per workspace), [D-72](../decisions/architecture.md) (multi-connection serial dispatch).
|
||||
- **Source:** T-421 / 2026-06-14 user review.
|
||||
|
||||
---
|
||||
|
||||
@@ -0,0 +1,100 @@
|
||||
# Open Questions — Design
|
||||
|
||||
Feature proposals from the 2026-06-11 Fable review (fable-ous.md Part IV,
|
||||
epic [T-359]). Each asks the same question — are we going to implement this
|
||||
feature? — so the answer can resolve into a D-record (and an initiative
|
||||
ticket) or an R-record. Effort tags `[S/M/L/XL]` come from the review.
|
||||
|
||||
---
|
||||
|
||||
### Q-35: Agent Blame + Session Flight Recorder — implement?
|
||||
- **Status:** Open
|
||||
- **Question:** Are we going to implement agent blame — a gutter action on any line answering *which session, which turn, which prompt, which permission grant, what it cost*, opening the native conversation at the exact `tool_use` — plus a timeline scrubber to replay a session? `[L]`
|
||||
- **Context:** Two ideation lenses independently invented this. The transcript pipeline (`transcript_reader.dart`, `session_index.dart`) already parses everything needed. Cursor/Copilot cannot ship it: their logs live server-side by business design — local-and-committed transcripts are a structural moat.
|
||||
- **Source:** fable-ous.md Part IV, Tier 1 #1 (2026-06-11 Fable review).
|
||||
|
||||
### Q-36: Context X-ray — implement?
|
||||
- **Status:** Open
|
||||
- **Question:** Are we going to implement per-card token attribution ("this 40KB Bash tail is 12% of your window") plus a real compaction indicator? `[M]`
|
||||
- **Context:** `stream_json_session.dart` already parses usage and contextWindow per event; the renderer owns the cards. Would fix 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.
|
||||
- **Source:** fable-ous.md Part IV, Tier 1 #2 (2026-06-11 Fable review).
|
||||
|
||||
### Q-37: Trust Ledger + decision-aware permission prompts — implement?
|
||||
- **Status:** Open
|
||||
- **Question:** Are we going to implement a permission-rule ledger with provenance (which prompt, which session, which ticket; ticket-scoped expiry), and decision-aware prompts that chip the relevant D-record onto a `can_use_tool` card (edit touching pubspec.yaml → [D-31](../decisions/tooling.md#d-31-prefer-zero-deps-exact-pin), one keystroke to deny *with the decision cited*)? `[M]`
|
||||
- **Context:** Governance stops being documentation and becomes live agent policy. No competitor has a queryable in-repo decision system to attempt this. Builds on the D-78 interaction-zone prompt surface.
|
||||
- **Source:** fable-ous.md Part IV, Tier 1 #3 (2026-06-11 Fable review).
|
||||
|
||||
### Q-38: Agent Activity HUD — implement?
|
||||
- **Status:** Open
|
||||
- **Question:** Are we going to build the `OperationsRegistry` (T-59) once and feed it git/pql progress (T-59), sidebar badges (T-58), compaction state (T-244), and the status strip (T-274), with [Q-34](architecture.md#q-34-how--when-to-surface-the-accountteam-token-budget-given-upstream-doesnt-expose-it)'s budget slot reserved? `[M]`
|
||||
- **Context:** Four backlog tickets and one open question are secretly one feature. Prerequisite: fix the T-274 plumbing bug first or the HUD inherits blank-slot syndrome (root cause is on T-274; the ValueStream retrofit is T-386).
|
||||
- **Source:** fable-ous.md Part IV, Tier 1 #4 (2026-06-11 Fable review).
|
||||
|
||||
### Q-39: Active Ticket Context — implement?
|
||||
- **Status:** Open
|
||||
- **Question:** Are we going to bind picking up a ticket to the session — a "working on T-NNN" chip, auto `in_progress` flip, `(T-NNN)` pre-suggested in commit messages, changelog reminder on done? `[S]`
|
||||
- **Context:** Cheapest win in the review's whole feature list. Makes kanban ambient instead of homework, and makes trail/ledger features (Q-35, Q-43) reliable by giving every turn a ticket anchor.
|
||||
- **Source:** fable-ous.md Part IV, Tier 1 #5 (2026-06-11 Fable review).
|
||||
|
||||
### Q-40: Twin-timeline rewind — implement?
|
||||
- **Status:** Open
|
||||
- **Question:** Are we going to snapshot the worktree as hidden git refs (`git write-tree` → `refs/clide/checkpoints`) at every turn boundary, keyed to turn uuid, so every user-message card gains "restore files to before this"? `[L]`
|
||||
- **Context:** Claude's `/rewind` only restores what Claude itself edited; clide owns both timelines. Needs a retention/GC policy for the checkpoint refs.
|
||||
- **Source:** fable-ous.md Part IV, Tier 2 #6 (2026-06-11 Fable review).
|
||||
|
||||
### Q-41: Visual Dialog — one bidirectional scene schema — implement?
|
||||
- **Status:** Open
|
||||
- **Question:** Are we going to define one bidirectional scene schema where Claude draws ([D-91](../decisions/architecture.md#d-91-unified-conversation-drawing-card-backed-by-a-canvas-renderer) canvas cards), the user annotates in the interaction zone (T-260), and annotations return as *structured geometry + flattened PNG*, not prose?
|
||||
- **Context:** Two lenses converged here. The T-317/T-318 and T-260 specs should merge into one protocol *before* they become two dialects — this question is urgent in ordering even if the build is later. `[L]`
|
||||
- **Source:** fable-ous.md Part IV, Tier 2 #7 (2026-06-11 Fable review).
|
||||
|
||||
### Q-42: Immortal terminals — implement?
|
||||
- **Status:** Open
|
||||
- **Question:** Are we going to fuse T-258 (terminal as editor-mode peer) with T-325 live-tails so any long process — user shell *or* agent-spawned build — promotes to a full tmux-backed surface that survives restart? `[M]`
|
||||
- **Context:** "The build that never dies" is structural for clide, a plugin fantasy for Electron competitors. Resolving [Q-27](architecture.md#q-27-two-editor-split) (swap vs split) is part of it, as T-258 already notes.
|
||||
- **Source:** fable-ous.md Part IV, Tier 2 #8 (2026-06-11 Fable review).
|
||||
|
||||
### Q-43: Local cost ledger — implement?
|
||||
- **Status:** Open
|
||||
- **Question:** Are we going to persist per-turn cost/tokens against the active pql ticket so the board shows what each feature actually cost? (Tokens primary, dollars advisory — subscription auth reports notional costs.) `[M]`
|
||||
- **Context:** Flat-subscription opacity is the competitors' business model; turn-level local cost data is clide's birthright. Depends on Q-39 (active ticket binding) for reliable attribution.
|
||||
- **Source:** fable-ous.md Part IV, Tier 2 #9 (2026-06-11 Fable review).
|
||||
|
||||
### Q-44: Label-routed work queues / ticket dispatch — implement?
|
||||
- **Status:** Open
|
||||
- **Question:** Are we going to turn the board into an agent control surface — T-277 labels + the shipped pick-up path routing work queues, with an XL extension dispatching a ticket to a teammate session in an isolated git worktree (`SpawnSpec.cwd` already exists)? `[M→XL]`
|
||||
- **Context:** Local, no-telemetry background agents with the work item, isolation, review surface, and audit trail all in-repo.
|
||||
- **Source:** fable-ous.md Part IV, Tier 2 #10 (2026-06-11 Fable review).
|
||||
|
||||
### Q-45: Semantic terminal — implement?
|
||||
- **Status:** Open
|
||||
- **Question:** Are we going to inject OSC 133 markers (clide spawns the shell, injection is trivial) to lift scrollback into foldable command regions, with recognizers for test runners and stack traces, and real widgets between rows? `[XL]`
|
||||
- **Context:** xterm.js structurally cannot do widgets between rows. Hard prerequisite: the scrollback-unreachable bug (in T-378) — a semantic scrollback you can't scroll is a koan.
|
||||
- **Source:** fable-ous.md Part IV, Tier 3 #11 (2026-06-11 Fable review).
|
||||
|
||||
### Q-46: Living codebase map — implement?
|
||||
- **Status:** Open
|
||||
- **Question:** Are we going to render tree-sitter imports + pql links + git churn on the owned canvas, with live agent heat from `tool_use` events — watching Claude move through the codebase in real time? `[XL]`
|
||||
- **Context:** Needs the canvas surface (T-317 family) and the tree-sitter FFI work to be solid first.
|
||||
- **Source:** fable-ous.md Part IV, Tier 3 #12 (2026-06-11 Fable review).
|
||||
|
||||
### Q-47: Live mixed documents — implement?
|
||||
- **Status:** Open
|
||||
- **Question:** Are we going to make fenced blocks in the owned markdown renderer live embeds — canvas scenes, pql query results, decision cards, confirm-gated command buttons? Notebook-grade, zero webview. `[XL]`
|
||||
- **Context:** The `ClideMarkdownHooks` seam already exists.
|
||||
- **Source:** fable-ous.md Part IV, Tier 3 #13 (2026-06-11 Fable review).
|
||||
|
||||
### Q-48: Sealed-workspace mode — implement?
|
||||
- **Status:** Open
|
||||
- **Question:** Are we going to build an egress-audit proxy around the whole agent stack, operationalizing [D-60](../decisions/tooling.md#d-60-no-network-on-default-launch-path)/[D-64](../decisions/architecture.md#d-64-no-telemetry--architectural-commitment) into a provable property? `[XL]`
|
||||
- **Context:** The one feature in the review's list competitors cannot copy without breaking their own products.
|
||||
- **Source:** fable-ous.md Part IV, Tier 3 #15 (2026-06-11 Fable review).
|
||||
|
||||
### Q-49: Review honorable mentions — which, if any, get promoted?
|
||||
- **Status:** Open
|
||||
- **Question:** Which of the review's honorable mentions, if any, do we promote to tickets: Plan-to-Board bridge (ExitPlanMode approval files the plan as a ticket tree), Release Cockpit (renders `[Unreleased]` + one-action release cut — would also unstall the release-loop story T-393), Daily Helm (since-you-were-last-here pulse on the welcome screen), Total-recall conversation search (D-79 grep over the transcript corpus + fork-from-here), Shared Gaze (attach editor selection/scroll context to outgoing turns), Speakable Layouts (`clide layout apply review.yaml`), Agent fleet tray (per-workspace sockets — requires T-247's stale-socket fix first), Governance Graph (the D/Q/R/T web as a navigable map)?
|
||||
- **Context:** Kept as one record to avoid fifteen low-signal questions; promote individually as appetite appears.
|
||||
- **Source:** fable-ous.md Part IV, honorable mentions (2026-06-11 Fable review).
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user