claude: Bash live-tail detection + read-only file follower (T-325, core)

The detection/follow core for the live-tail sub-card, with the UI wiring to follow. Claude Code runs every Bash tool itself and clide only sees the final tool_result block — we can't mirror the running process, so instead we detect a file-backed source the command follows and open our own read-only follower on the same file. - bash_tail_source.dart: detectBashTailSource() parses a Bash command for a single, safe, file-backed source (tail/cat/less with one file arg, inside the workspace via resolveUnderRoot). Returns null for a pipe-into-tail, a redirect, two files, or a path outside the repo — the caller then shows a "nothing to follow" note. bashHasTailIntent() gates WHEN the segment appears: v1 triggers on `tail`/follow-flags only, so ordinary cat/ls/git cards stay clean (cat/less remain detectable for later). - file_tail_follower.dart: a polling, read-only `tail -f`-style follower (no subprocess, no touching Claude's command) that emits the trailing window then appended deltas, and re-reads from the top on truncation. Tested: 19 parser cases (incl. the `git push | tail -25` and outside- workspace null cases), the intent predicate, and the follower (initial window / appended delta / missing file / rotation / start / stop). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-11 17:12:53 +02:00
parent d43ddfed9c
commit 898a0316e5
10 changed files with 510 additions and 0 deletions
@@ -133,6 +133,10 @@ You might also want, project-permitting:
 - [D-89: inline pasted-image thumbnails that expand to the lightbox](decisions/design.md#d-89-inline-pasted-image-thumbnails-that-expand-to-the-lightbox) — _design_
 - [D-90: clide:// deep links — paranoid allowlist + user confirmation](decisions/architecture.md#d-90-clide-deep-links--paranoid-allowlist--user-confirmation) — _architecture_
 - [D-91: Unified conversation drawing card backed by a canvas renderer](decisions/architecture.md#d-91-unified-conversation-drawing-card-backed-by-a-canvas-renderer) — _architecture_
+- [D-92: Ship pql bundled with clide](decisions/tooling.md#d-92-ship-pql-bundled-with-clide) — _tooling_
+- [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_

 ## Open questions

@@ -23,6 +23,7 @@ Core, rendering, IPC, kernel, panel manager.

 ### D-4: Ignore file strategy
 - **Date:** 2026-04-20 (was ADR 0004; ported from the claudian lineage)
+- **Amendment (2026-06-11):** Per [D-93](#d-93-clide-writes-no-directories-of-its-own-into-the-workspace), clide no longer writes a `.clide/` directory into the repo; only `.pql/` is added to `.gitignore` at install time. The `.clide/` mention below is retained for history.
 - **Decision:** One mechanism everywhere: the `ignore_files:` list in `.pql/config.yaml`. Ordered list of gitignore-shaped files; later entries win on per-pattern conflicts. pql defaults to `ignore_files: [.gitignore]`. Per [D-3](#d-3-pql-as-supporter-tool-clide-wraps-never-duplicates), clide writes the list on load — `[.gitignore, .clideignore]` if `.clideignore` exists, else `[.gitignore]`. `.clideignore` carries **only** the clide-specific deviations from `.gitignore` (supports `!pattern` negations); never duplicate gitignore's contents. Walker magic: none except `.git/` — every other tool-owned dir (`.pql/`, `.clide/`) is added to `.gitignore` at install time; exclusion flows through the normal `ignore_files:` chain.
 - **Context:** Every file-enumerating surface in clide (pql query panels, canvas drivers, graph view, file watchers, pane lists, file tree) needs to skip the obvious junk — `vendor/`, `node_modules/`, `dist/`, build artifacts — or results drown in noise. Clide's working assumption is that the git repo *is* the workspace — no separate "vault" concept.
 - **Rationale:** Users get one config knob, in a file they might already know (pql users) or never need to touch (clide-only users). `.clideignore` is short by design — it's deltas, not a full list. Sidecar consumers read the same key and apply identical precedence, so Claude and the user always see the same filtered surface.
@@ -190,6 +191,7 @@ Core, rendering, IPC, kernel, panel manager.

 ### D-53: State persistence across sessions
 - **Date:** 2026-04-22
+- **Amendment (2026-06-11):** Per [D-93](#d-93-clide-writes-no-directories-of-its-own-into-the-workspace), this state moves from in-repo `.clide/settings.yaml` to user-scope storage keyed by workspace-path hash. The `.clide/settings.yaml` references below are retained for history.
 - **Decision:** The following layout state is persisted across app restarts: collapse state of left and right panels, active left section (tickets/decisions/files/git/pr), active right context type, pql pane expanded/collapsed, editor split ratio when open, fuzzy find recent picks. Stored via `SettingsStore` in project-scoped settings (`.clide/settings.yaml`).
 - **Rationale:** Users expect their workspace layout to survive restarts. Without persistence, every launch starts at the default layout preset, which is disorienting when the user has customised their column widths and panel states.
 - **Cost:** Adds write-on-change to several layout operations. Must handle migration if the setting keys evolve. `.clide/settings.yaml` is already gitignored, so personal layout state stays personal.
@@ -469,4 +471,33 @@ Core, rendering, IPC, kernel, panel manager.
 - **Relationship:** Narrows [Q-4](../questions/architecture.md#q-4-canvas-schema-compatibility-with-obsidian) — clide's canvas is its own HTML-canvas-inspired JSON; Obsidian `.canvas` is an *import* format via conversion, not the native schema. Consumes the stdin/`--file` JSON input plumbing (T-315). Subsumes the standalone icon card (T-313) and image-annotation work (T-316) as templates of this card. **Merges the former Tier-5 "canvas and graph view" epic (T-7) into one canvas epic (T-317):** the Tier-5 canvas *pane* (T-322, interactive/editable — distinct from the display-only conversation card) and graph *view* (T-323) consume the same shared renderer; T-7 is cancelled as superseded. The conversation drawing card stays display-only per [D-78]; the canvas pane is a full interactive pane. (D-17 "panels are extension-shaped" is unaffected and still governs the panes.)
 - **Raised by:** 2026-06-10 — user, while refining the icon-preview card (T-313): "make it all into one drawing card that receives a json input and selects based on the context inside the json what to draw … pull the entire thing closer to a dynamic canvas than a bunch of one-off renderers." Clarified the model is HTML `<canvas>` (not Obsidian's), templates-over-primitives, per-object label/description, and reuse as the `.canvas` renderer; before/after comparisons, SVGs, icons, and graphs all become things you send into the card.

+### D-93: clide writes no directories of its own into the workspace
+- **Date:** 2026-06-11
+- **Decision:** clide-the-IDE contributes **zero** directories to a workspace. The only tool-owned directories physically written into a repo are `.git/` (git's, brought by the user) and `.pql/` (pql's repo data — index + planning changelog). All IDE-local per-workspace state — panel collapse, active sections, split ratios, project theme, recent picks ([D-53](#d-53-state-persistence-across-sessions)), and any future per-repo extension DB — moves to **user scope**, stored outside the repo and keyed by a hash of the workspace path, the same convention the IPC socket already uses ([D-70](#d-70-ipc-socket-path-is-per-workspace-deterministic)). If clide ever needs shared, *committed* per-repo config, it lives as clide-owned keys in `.pql/config.yaml` (the existing `ignore_files:` precedent, [D-3](#d-3-pql-as-supporter-tool-clide-wraps-never-duplicates)/[D-4](#d-4-ignore-file-strategy)) — never a new directory.
+- **Context:** clide previously wrote project-scoped settings to an in-repo `.clide/` directory ([D-53](#d-53-state-persistence-across-sessions)). Even gitignored, that put an IDE scratch dir physically inside the user's repo. "Written in the repo" — not "checked in" — is the thing being minimized.
+- **Rationale:** One tool dir in the repo (`.pql/`), and it earns its place because it holds data *about* the repo. Personal IDE state is not repo data, so it belongs in user scope — exactly where [D-70](#d-70-ipc-socket-path-is-per-workspace-deterministic) and [D-41](#d-41-claude-panes-one-primary-per-repo-tmux-backed) already keep per-workspace runtime state. Nothing shared is lost: `.clide/settings.yaml` was already gitignored, so it was never committed anyway.
+- **Cost:** A one-time migration of any existing in-repo `.clide/settings.yaml` to user scope, then dropping the dir. Per-workspace state inherits [D-70](#d-70-ipc-socket-path-is-per-workspace-deterministic)'s trade-off: moving or renaming a repo re-keys it and resets personal layout.
+- **Amends [D-4](#d-4-ignore-file-strategy):** D-4's clause "`.clide/`) is added to `.gitignore` at install time" is moot — clide no longer writes `.clide/` into the repo. Only `.pql/` is added to `.gitignore` at install time.
+- **Amends [D-53](#d-53-state-persistence-across-sessions):** persisted layout state moves from in-repo `.clide/settings.yaml` to user-scope storage keyed by workspace-path hash.
+- **Cross-reference:** [D-3](#d-3-pql-as-supporter-tool-clide-wraps-never-duplicates), [D-4](#d-4-ignore-file-strategy), [D-53](#d-53-state-persistence-across-sessions), [D-70](#d-70-ipc-socket-path-is-per-workspace-deterministic), [D-41](#d-41-claude-panes-one-primary-per-repo-tmux-backed).
+- **Raised by:** 2026-06-11 — user: "I am not a fan of IDEs tossing in multiple dirs … only the pql dir which contains repo data gets [written] in repo."
+
+### D-94: Workspace mode is a first-class, extensible declared capability
+- **Date:** 2026-06-11
+- **Decision:** A clide workspace runs in exactly one **mode** at a time, drawn from an open, extensible vocabulary — initially `edit` (full local read/write; the default) and `read` (read-only; no writable `.pql/`), with `remote`, `ssh`, and `webui` reserved as future values. Every extension declares the modes it supports in its manifest (`modes: [edit, read]`); an extension with no declaration is assumed `edit`-only. The extension host activates an extension only when the active workspace mode is in its declared set — unsupported extensions stay dormant. New modes are added as new vocabulary values **without schema changes**; the open SSH-remote question ([Q-23](../questions/architecture.md#q-23-ssh-remote-development--run-clide-against-a-remote-workspace)) is expected to resolve *into* a mode value, not a parallel mechanism.
+- **Context:** Read-mode degrade ([D-95](#d-95-workspace-validity-and-onboarding-flow)) needs to know which extensions remain functional without pql and without write access. A boolean `read_mode_safe` would answer only today's question and would not compose with the `remote`/`ssh`/`webui` modes already on the horizon.
+- **Rationale:** Modelling capability as a declared mode set is uniform and future-proof — one mechanism the host gates on, one place extensions opt in, and third-party extensions participate by declaring. Reserving the future values now means remote/ssh/webui work plugs into an existing seam instead of inventing its own.
+- **Cost:** Every builtin extension must declare its modes (a one-time classification pass); the host gains mode-gating logic; the vocabulary is open-ended and must stay coherent as values accrue. Defaulting an undeclared extension to `edit`-only is conservative but may surprise authors.
+- **Cross-reference:** [D-17](extensions.md#d-17-panels-are-extension-shaped-from-day-one), [D-95](#d-95-workspace-validity-and-onboarding-flow), [Q-23](../questions/architecture.md#q-23-ssh-remote-development--run-clide-against-a-remote-workspace).
+- **Raised by:** 2026-06-11 — user: "read_mode_safe: true is not leaving space for further modes (ssh mode, remote mode, webui mode, read mode, edit mode). Prepare it for that."
+
+### D-95: Workspace validity and onboarding flow
+- **Date:** 2026-06-11
+- **Decision:** A clide workspace is valid only when it is a git repo with an initialized `.pql/`. Two consequences. **(1) Git is a precondition the user owns.** clide never auto-runs `git init`; opening a non-git folder *offers* initialization (**default no**, with a guard that warns when a parent `.git` would make this a nested repo) or lets the user pick another folder. **(2) pql is clide-provisioned.** Because pql now ships bundled ([D-92](tooling.md#d-92-ship-pql-bundled-with-clide)), an uninitialized repo triggers a **required, idempotent** prep flow that reconciles state (virgin / pql-user / partially-init / fully-init / previously-declined) and **discloses exactly what it writes** — `.gitignore` entries for `.pql/`, pql's config, and (only on opt-in) git hooks. The mandatory floor is pql **config + index** (the files/query/ignore engine); the **planning layer** (decisions/tickets + the changelog hooks of [D-67](process.md#d-67-pql-changelog-files-are-committed-alongside-code), which alter the user's git workflow) is a **contextual opt-in** offered when the user first opens the Decisions or Tickets surface — never forced at onboarding. A writable repo with no `.pql/` is *invalid-until-initialized*; a repo clide **cannot** write (read-only mount, no permission) degrades to **read mode** ([D-94](#d-94-workspace-mode-is-a-first-class-extensible-declared-capability)) — file tree, editor, and the pure-Dart content search ([D-79](#d-79-workspace-content-search-is-a-pure-dart-in-process-engine-outside-pql)) stay live; pql-backed surfaces go dark behind a clear banner. A decline is remembered in user scope, keyed by repo path; clide does not re-nag, and an explicit "initialize workspace" command is always available.
+- **Context:** [D-4](#d-4-ignore-file-strategy) already specified that `.pql/` is "added to `.gitignore` at install time" — presuming an install-time event that never had a trigger. Bundling pql ([D-92](tooling.md#d-92-ship-pql-bundled-with-clide)) is what makes "pql required" honest: clide can always provide the means to create `.pql/`. This record is that missing trigger.
+- **Rationale:** pql is clide's core query/ignore engine, not just the ticket board, so a repo without it is degraded for *core editing*, not only planning — gating on `.pql/` is truthful. Git, by contrast, is a foundational, identity-level user decision (and `git init` in the wrong place is a footgun), so clide offers but never imposes it. Splitting the mandatory config+index from the opt-in planning hooks keeps the invasive git-workflow change consensual and contextual. Read-mode degrade keeps clide usable as an editor on repos it cannot write — consistent with [D-80](#d-80-filesread-allows-trusted-claude-config-roots-beyond-the-workspace)'s read appetite — instead of refusing them outright.
+- **Cost:** An onboarding/state-reconciliation flow with a disclosing modal. The installer must handle the known hooks gotcha (`pql init` writes to `.git/hooks` and ignores an existing `core.hooksPath`) — it must not silently clobber a repo that sets `core.hooksPath`. The read-mode path gates extensions by their declared modes ([D-94](#d-94-workspace-mode-is-a-first-class-extensible-declared-capability)) and must provide graceful fallbacks where pql surfaces go dark.
+- **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.
+
 ---
@@ -91,4 +91,13 @@ Toolchain, supply chain, CI, ignore strategy.
 - **Cross-reference:** [D-31](#d-31-prefer-zero-deps-exact-pin), [D-42](#d-42-dependencies-documented-in-licensesyaml), [D-61](#d-61-dependency-vetting-checklist), `POLICY.md`.
 - **Raised by:** 2026-04-26 policy-to-decision migration (T-28).

+### D-92: Ship pql bundled with clide
+- **Date:** 2026-06-11
+- **Decision:** clide ships `pql` as a vendored, version-pinned native binary — the same model used for git via dugite ([D-59](#d-59-bundled-git-via-dugite-native)). The pinned binary lives under `native/<platform>/` with a `BUILD.md` provenance record ([D-63](#d-63-vendored-binary-rebuild-process)) and an `assets/licenses.yaml` entry ([D-42](#d-42-dependencies-documented-in-licensesyaml), [D-65](#d-65-license-compatibility-matrix)). Resolution order is: `CLIDE_PQL_BIN` env override (dev escape hatch — e.g. pointing at a pql built side-by-side) → bundled binary resolved against the **install directory** (next to the executable, never workspace-relative) → system `pql` on PATH. The bundled copy never self-updates — the pin is the contract, so `pql self-update` is inert for it. A version floor is enforced *softly*: if the resolved pql (override or PATH) is older than the pinned floor, the Problems panel surfaces it rather than clide silently mis-driving an incompatible binary. CI runs the in-tree binary instead of provisioning pql on the runner.
+- **Context:** pql is clide's files/query/ignore engine **and** its planning engine ([D-3](architecture.md#d-3-pql-as-supporter-tool-clide-wraps-never-duplicates)), yet it was an unmanaged external dependency: users installed and updated it themselves, with no version pin. Beyond the "update the binary, then install it" friction, an old PATH pql replaying the changelog ([D-67](process.md#d-67-pql-changelog-files-are-committed-alongside-code)) is a latent *corruption* risk, not merely a missing-feature one. This is a distribution gap, not an architecture one.
+- **Rationale:** Bundling makes a fresh clone/install work with zero separate pql setup, pins the version clide was tested against (closing the changelog-schema-skew risk), and reuses the proven dugite pattern and its supply-chain gates ([D-60](#d-60-no-network-on-default-launch-path)/[D-61](#d-61-dependency-vetting-checklist)/[D-63](#d-63-vendored-binary-rebuild-process)). It is **additive, not a fork**: pql stays a standalone tool, clide still wraps and never reimplements ([D-3](architecture.md#d-3-pql-as-supporter-tool-clide-wraps-never-duplicates)), and pql's universality for terminal/VS Code users is untouched. pql being a pure-Go, no-CGo static binary makes per-platform bundling cheap.
+- **Cost:** A pinned binary per shipped platform (linux-x64 now; macOS arm64/x64 when those builds land), each carried through the [D-63](#d-63-vendored-binary-rebuild-process) rebuild ritual on every pql release — the same bump cadence as dugite and tree-sitter. Resolving the bundled binary against the install dir and **never** a workspace-relative path is mandatory: a repo could otherwise plant `native/pql` and gain code execution (the T-98 dugite lesson).
+- **Cross-reference:** [D-3](architecture.md#d-3-pql-as-supporter-tool-clide-wraps-never-duplicates), [D-59](#d-59-bundled-git-via-dugite-native), [D-60](#d-60-no-network-on-default-launch-path), [D-61](#d-61-dependency-vetting-checklist), [D-63](#d-63-vendored-binary-rebuild-process), [D-42](#d-42-dependencies-documented-in-licensesyaml), [D-65](#d-65-license-compatibility-matrix), [D-67](process.md#d-67-pql-changelog-files-are-committed-alongside-code).
+- **Raised by:** 2026-06-11 — user: "pql updates live outside this repo and people have to first update the pql binaries and install them."
+
 ---