# Full-stack feature changes How a Pipelines feature that crosses layers is built, checked and handed over. The **Feature** workflow (`docs/workflows/feature.md`) follows this guide; it records what worked for the chat, terminal, file and discovery features built on 2026-11-08/09 (turn diffs, shell commands and the interactive terminal, the permanent terminal, Pipelines chat tools, thinking levels, file upload, rename, move and delete, dismissible commands, connection recovery). ## Layers and where a feature touches them | Layer | Where | Typical change | |---|---|---| | Protocol | `internal/protocol/` | New request/frame types in their own file; the `Message` field in `message.go` is additive and `omitempty` so older peers keep working | | Persistence | `internal/pipeline/` | A new table in its own file with `init…` called from `store.go`; bounded rows; survives restarts | | Server | `internal/server/` | Handlers in new files named for the area (`chat_*`, `terminal_*`, `home_files_*`), routed from `chat.go`/`websocket.go`; pushed frames to every client watching | | Harness adapters | `internal/claude`, `internal/codex`, `internal/opencode` | Per-harness mechanism checked against the installed CLI or app-server schema; unsupported means no feature, never a fake | | Web proxy | `web/serve.mjs`, `web/src/peerRelay.js` | Only for new HTTP paths: authenticated route plus the peer-relay allowlist | | App | `app/lib/features//` | Small files; Material and Cupertino; reached through the chat's own gateway so multi-machine chats work | | Fixture | `app/tool/perf/*_fixture.dart`, `app/tool/search_selection_probe_entry.dart` | A `?param=1` option that renders the new states for captures | Shared files every feature touches (`message.go`, `chat_hub.go`, `store.go`, `chat_thread_view.dart`, `perf_fixture.dart`): keep edits there to a few lines and put the logic in new files. Parallel features then merge with small, additive conflicts. ## Rules that held up - **Security boundary.** Everything goes through the authenticated `/connect` websocket. Home-folder access uses `expandHomePath`, `resolveInsideHome` and `specialFilesystem`; symlinks are operated on, not followed. Internal endpoints (for example `/mcp`) must not be reachable through the web proxy; add a proxy test. Typed input, passwords and tokens are never logged or stored. Credentials never cross machines. - **Bounds.** Every retained buffer, list and payload has a limit (for example 1 MiB output, 50 runs, 512 KiB views, 5 notifications a minute) and reports truncation instead of failing silently. - **Platform reality.** Check what the installed tools accept (for example `codex app-server generate-json-schema`, `claude` control requests, OpenCode's API). Browsers reserve some shortcuts (Ctrl/Cmd+T, Ctrl+Tab); say which ones work where. - **Desktop vs phone.** Web themes are pinned to Android, so desktop checks use `prefersCompactHitTargets` (device platform), not the theme platform. - **Shared environments.** Never use the production server (127.0.0.1:8080, web 8083), real chats, the personal Fold, or restart shared services. ## Verification - **Focused tests while editing.** Go: `go test ./internal/ -run `. App: `cd app && tool/memwatch/full.sh 'test/a_test.dart test/b'` (the whole path list is one quoted argument) and `tool/analyze.sh`. Web: `cd web && node --test test/`. Never bare `flutter test`. - **Scratch end-to-end** for server behaviour: build `./cmd/pipelines-server`, run it with an isolated `HOME`, a scratch `-db`, `-addr 127.0.0.1:0` (an OS-chosen port) and `PIPELINES_MDNS=off`, drive it over the websocket, then stop every process. Real harness runs need credentials; when they are missing, say so rather than claim them. - **Rendered evidence** for visible changes: build the full-app fixture once (`flutter build web --target tool/search_selection_probe_entry.dart --output build/probe-app`) and capture with `app/tool/capture/` at wide (1400x900) and narrow (560x1000) sizes, light and dark, Material and Cupertino where relevant. Open every PNG cited. - **Known pre-existing failures** (as of 2026-11-09, on untouched main): 44 tests in `app/test/application/*` (pending launch-update timer) and, under a `umask 077` shell, `internal/claude` `TestServiceTokenIsPassedOnlyFromAPrivateFile` and `internal/opencode` `TestStageDiscoveryRequiresPrivateRegistrationBeforeSessionWork`. The installed server (and so the delivery gate) runs with `Umask 63` (077), so the gate's Go check sets `umask 022` first. Compare against a worktree of main before blaming a change. - **Notes.** Each feature leaves `app/notes/.md` with behaviour, protocol, limits, security and the exact verification output. ## Delivery (manager, not the workflow) The workflow commits a reviewed candidate; the server's delivery gate checks it and lands it on main. Deployment is separate and only on request: `./install` (web and server), a restart only when no chat or run is active, then `./install --apk` (native build), `./install --macos --publish --flutter ` and `./install --linux --publish`.