Merge pull request #125 from jsilvanus/claude/subagents-deploy-142-148-dhe3mq

Claude/subagents deploy 142 148 dhe3mq

Author: jsilvanus

.changeset/remove-lsp-tcp-transport.md

@@ -0,0 +1,5 @@
+---
+"gitsema": minor
+---
+
+Removed the `tools lsp --tcp` transport entirely (previously deprecated in Phase 120 in favor of `--websocket --key`): raw TCP had no authentication mechanism at all, and nothing in the test suite exercised it. `gitsema tools lsp`/`gitsema lsp` are now stdio or `--websocket` only — use `--websocket <bind-address> --key <token>` for network-reachable LSP access.

CLAUDE.md

@@ -257,7 +257,7 @@ Preferred entry point for all long-running protocol servers. Subcommands:
 | Subcommand | Description |
 |---|---|
 | `gitsema tools mcp` | Start the MCP stdio server (AI tool interface) |
-| `gitsema tools lsp [--tcp <port>]` | Start the LSP semantic hover server (JSON-RPC over stdio or TCP; `--tcp` is deprecated, use `--websocket`) |
+| `gitsema tools lsp [--websocket <bind-address>]` | Start the LSP semantic hover server (JSON-RPC over stdio or WebSocket) |
 | `gitsema tools serve [--port n] [--key token] [--ui]` | Start the HTTP API server (remote embedding backend) |
 
 The old top-level `gitsema mcp`, `gitsema lsp`, and `gitsema serve` still work as hidden backward-compat aliases.
@@ -395,7 +395,7 @@ git repo
    │                        chattydeerProvider.ts, cliProvider.ts, cliAdapters.ts — HTTP / local-CLI LLM backends
    │                        redact.ts         — secret/PII redaction applied to all outbound LLM content
 [ src/core/llm/ ]          narrator.ts       — system-prompt builders shared by narrator/guide/skill generator
-[ src/core/lsp/ ]          server.ts         — JSON-RPC semantic hover server (stdio, `--websocket`, or deprecated `--tcp`)
+[ src/core/lsp/ ]          server.ts         — JSON-RPC semantic hover server (stdio or `--websocket`)
 [ src/core/viz/ ]          htmlRenderer*.ts  — interactive HTML output for evolution/search/clusters/map
 [ src/core/models/ ]       types.ts          — shared embedding/result type definitions
    ↓
@@ -694,4 +694,3 @@ For the full list of gaps and planned work, see [`docs/PLAN.md`](docs/PLAN.md) a
 | Gap | Notes |
 |---|---|
 | **Python model server** | Docker image and Dockerfile provided to avoid local Rust/wheel issues on Windows; use Docker to run the modelserver. |
-| **Deprecated `tools lsp --tcp`** | No Bearer-token mechanism at all (review10 §3.5), unlike `--websocket`/`--http` which support `--key`/`GITSEMA_WEBSOCKET_KEY`/`GITSEMA_MCP_HTTP_KEY` — raw TCP has no header to carry a token in. Deprecated in favor of `--websocket` (Phase 120) rather than given a bespoke handshake-auth protocol; a deprecation warning is printed on every invocation, but the flag still works and is not yet scheduled for removal. |

README.md

@@ -185,7 +185,7 @@ Copies the active index into another storage backend (sqlite/postgres/qdrant) vi
 | Command | Description |
 |---|---|
 | `gitsema tools mcp [--remote <url>] [--remote-key <token>] [--remote-timeout <ms>] [--websocket <bind-address>] [--http <bind-address>] [--key <token>]` | Start the MCP stdio server (AI tool interface) |
-| `gitsema tools lsp [--tcp <port>] [--websocket <bind-address>] [--key <token>] [--remote <url>] [--remote-key <token>] [--remote-timeout <ms>] [--diagnostics]` | Start the LSP semantic hover server (JSON-RPC over stdio, TCP, or WebSocket) — `--tcp` is deprecated, use `--websocket` |
+| `gitsema tools lsp [--websocket <bind-address>] [--key <token>] [--remote <url>] [--remote-key <token>] [--remote-timeout <ms>] [--diagnostics]` | Start the LSP semantic hover server (JSON-RPC over stdio or WebSocket) |
 | `gitsema tools serve [--port n] [--key token] [--ui]` | Start the HTTP API server (remote embedding backend) |
 
 The old top-level `gitsema mcp`, `gitsema lsp`, and `gitsema serve` still work as hidden backward-compat aliases.
@@ -210,7 +210,7 @@ server-push notification and remote delegation is request/response-only).
 
 **WebSocket transport (Phase 116):** `--websocket <bind-address>` (e.g.
 `--websocket 0.0.0.0:4242`) listens on a fixed `/mcp` or `/lsp` path instead of
-stdio/TCP. `--key <token>` requires a matching `Authorization: Bearer <token>`
+stdio. `--key <token>` requires a matching `Authorization: Bearer <token>`
 header on the WS upgrade request, falling back to `GITSEMA_WEBSOCKET_KEY` if
 `--key` is omitted (shared by `tools mcp --websocket` and `tools lsp
 --websocket`); gitsema does not terminate TLS, so put a reverse proxy in front
@@ -234,13 +234,6 @@ response/request header), capped at 100 concurrent sessions; request bodies
 are capped the same way as `tools serve` (`GITSEMA_MAX_BODY_SIZE`, default
 1mb). Binding a non-loopback host without a key prints a startup warning.
 
-**`--tcp` is deprecated:** `tools lsp --tcp` has no authentication mechanism at
-all (unlike `--websocket`/`--http`), and raw TCP has no header to carry a
-bearer token in — any client that can reach the port gets full LSP access. Use
-`--websocket <bind-address> --key <token>` instead, which covers the same
-network-LSP use case with working auth. A deprecation warning is printed on
-every `--tcp` invocation; the flag is not yet scheduled for removal.
-
 `gitsema tools serve` defaults `POST /api/v1/remote/index` to **persistent** mode:
 the cloned repo and its index are stored under `GITSEMA_DATA_DIR` (default
 `~/.gitsema/data`) and reused on subsequent requests (fetch + incremental index

docs/PLAN.md

@@ -115,8 +115,6 @@
 |   [Phase 97 — Full-toolset guide, tool interpretation registry, skill generation, Ollama docs](#phase-97-—-full-toolset-guide-tool-interpretation-registry-skill-generation-ollama-docs) | 3281 |
 |   [Phase 98 — CLI-based AI tool backends for narrator/guide](#phase-98-—-cli-based-ai-tool-backends-for-narratorguide) | 3342 |
 |   [Phase 99 — `--provider ollama` for narrator/guide + Ollama model discovery](#phase-99-—-provider-ollama-for-narratorguide-ollama-model-discovery) | 3406 |
-| [Long-Term Investments](#long-term-investments) | 3447 |
-| [Non-goals for now (revisited later)](#non-goals-for-now-revisited-later) | 3464 |
 |   [Phase 100 — Persistent, registry-backed server-side repo storage](#phase-100-—-persistent-registry-backed-server-side-repo-storage) | 3472 |
 |   [Phases 101–103 — Pluggable storage backends & index scoping](#phases-101–103-—-pluggable-storage-backends-index-scoping) | 3540 |
 |   [Phase 104 — Full-toolset guide coverage, per-command `--narrate`, and a guided `gitsema setup` wizard](#phase-104-—-full-toolset-guide-coverage-per-command-narrate-and-a-guided-gitsema-setup-wizard) | 3742 |
@@ -3457,31 +3455,6 @@ is given.
 
 **Status:** ✅ complete.
 
-## Long-Term Investments
-
-| Feature | Complexity | Notes |
-|---------|:----------:|-------|
-| Plugin API for custom analysers | High | Allow third-party modules to register their own search/analysis commands |
-
-> **Note:** the "pgvector migration path for >500K blobs" item formerly listed
-> here was implemented by Phases 101-103 (`storage.backend=postgres\|qdrant`,
-> see [Phases 101-103](#phases-101–103-—-pluggable-storage-backends-index-scoping)).
-> SQLite remains the default for new projects.
-
-**Scale notes (updated for v0.81.0):**
-
-- **Search memory:** auto early-cut (Phase 82) now guards the default search path — reservoir sampling kicks in at 50 K candidates without any flags. ANN path (`gitsema index build-vss`) eliminates the candidate-load entirely for large indexes.
-- **Indexing time:** commit-message embedding is now parallelised (Phase 83). The read/embed/store pipeline (Phase 69) + parallel commit embedding together keep both phases off the critical path. The remaining serial bottleneck is commit-graph walking itself (git rev-list) which is I/O-bound.
-- **Chunk/symbol candidate expansion:** when `--chunks` or `--vss` is combined with a large index the candidate pool grows 3–10× before scoring. Monitor RSS when indexing large monorepos with `--chunker function`.
-
-## Non-goals for now (revisited later)
-
-| Feature | Reasoning | 
-|---------|:----------:|-------|
-| Python model server (GPU Docker) | We already have Node.js embedeer and if we want Docker+python, we can use ollama. |
-
----
-
 ### Phase 100 — Persistent, registry-backed server-side repo storage
 
 **Goal:** Make `gitsema tools serve`'s `POST /api/v1/remote/index` persist cloned
@@ -6043,6 +6016,68 @@ detail):
 
 ---
 
+### Phase 149 — Remove `tools lsp --tcp`
+
+**Design:** no separate design doc — scoped directly from a `/whatnext`
+audit finding: review10 §3.5 flagged `tools lsp --tcp` as an unauthenticated
+network transport (raw TCP has no header to carry a Bearer token in), Phase
+120 deprecated it in favor of `--websocket --key` rather than fixing it, and
+Phase 120's own entry explicitly floated removal as "a separate,
+explicitly-scheduled future phase once usage data/feedback suggests it's
+safe." The audit confirmed no test in the suite exercises `--tcp` or
+`startLspTcpServer` (`grep -rln "startLspTcpServer\|--tcp" tests/` returns
+nothing), so removal is a clean cut with no test fallout to reconcile.
+
+**Goal:** Actually remove the `--tcp <port>` transport (not just deprecate
+it further) from `gitsema tools lsp` and the legacy `gitsema lsp` alias,
+closing the unauthenticated-transport gap by deleting the surface entirely
+rather than continuing to carry it forward.
+
+**Scope:**
+1. Removed the `--tcp <port>` Commander option and its handling from `tools
+   lsp` (`src/cli/commands/tools.ts`) and the top-level `gitsema lsp`
+   backward-compat alias (`src/cli/commands/lsp.ts`).
+2. Removed `startLspTcpServer()` from `src/core/lsp/server.ts`, along with
+   the now-unused `node:net` `createServer` import that only existed to
+   support it.
+3. Deleted the `gitsema tools lsp --tcp <port>` row from
+   `docs/deprecations.md` §1 (hard deprecations) per that file's own stated
+   policy — "delete its row only after the removal has actually shipped" —
+   and bumped its "Last updated" date.
+4. Updated `README.md`, `docs/features.md`, `docs/parity.md`, and
+   `CLAUDE.md` to remove `--tcp` references: README's and features.md's
+   `tools lsp` command-reference rows now read `[--websocket
+   <bind-address>] [--key <token>] ...` with no TCP mention;
+   `docs/parity.md`'s §0 transport table, legend, and flag-coherence rows
+   for `tools lsp` drop the `--tcp` column entirely (LSP is now stdio or
+   `--websocket` only, matching MCP's existing stdio/`--websocket`/`--http`
+   pattern); `CLAUDE.md`'s "Known gaps & future phases" table entry, which
+   previously described `--tcp` as an open, deprecated gap, now describes
+   the removal instead.
+5. Added `.changeset/remove-lsp-tcp-transport.md` (`minor` severity,
+   following this repo's established precedent of using `minor` rather than
+   `major` for breaking changes pre-1.0 — see `.changeset/deprecate-lsp-tcp.md`
+   and `.changeset/author-http-route-parity.md`).
+
+**Acceptance criteria:**
+- `gitsema tools lsp --tcp <port>` and `gitsema lsp --tcp <port>` no longer
+  parse as valid invocations (Commander has no `--tcp` option registered).
+- `startLspTcpServer` no longer exists anywhere in `src/`.
+- `docs/deprecations.md` no longer lists `--tcp` in §1.
+- `README.md`/`docs/features.md`/`docs/parity.md`/`CLAUDE.md` describe LSP
+  as available over stdio or `--websocket` only.
+- `pnpm build && pnpm test` clean — no test referenced `--tcp` or
+  `startLspTcpServer` before this change, so this is a clean removal.
+
+**Files touched:** `src/cli/commands/tools.ts`, `src/cli/commands/lsp.ts`,
+`src/core/lsp/server.ts`, `docs/deprecations.md`, `README.md`,
+`docs/features.md`, `docs/parity.md`, `CLAUDE.md`, `docs/PLAN.md`,
+`.changeset/remove-lsp-tcp-transport.md`.
+
+**Status:** ✅ complete.
+
+---
+
 ## Deployment scenarios & usage envisioning
 
 The architecture of gitsema supports three distinct deployment scenarios, each with different operational models and target users. This section clarifies the intended usage patterns and the infrastructure requirements for each.

docs/deprecations.md

@@ -4,7 +4,7 @@ Canonical list of every deprecated command, flag, and transport in gitsema:
 what replaced it, when it was deprecated, and whether (and when) it's
 scheduled for removal.
 
-**Last updated:** 2026-07-01
+**Last updated:** 2026-07-02
 
 **Removal policy:** gitsema has never set a removal date for anything in this
 file. Every hard deprecation below has been kept indefinitely since it was
@@ -37,7 +37,6 @@ functional — the warning is the only behavior change.
 | `gitsema clear-model` | `gitsema index clear-model` | Phase 71 (v0.71.0) | Not scheduled | `src/cli/register/indexing.ts:315-318` |
 | `gitsema build-vss` | `gitsema index build-vss` | Phase 71 (v0.71.0) | Not scheduled | `src/cli/register/indexing.ts:324-329` |
 | `gitsema policy check` (two-word) | `gitsema policy-check` (kebab-case) | Phase 94 (v0.91.0) | Not scheduled | `src/cli/register/analysis.ts:63-75` |
-| `gitsema tools lsp --tcp <port>` | `gitsema tools lsp --websocket <bind-address> --key <token>` | Phase 120 | Not scheduled (raw TCP has no header to carry a Bearer token in — see §3) | `src/cli/commands/tools.ts:92,126-133` |
 | `POST /api/v1/analysis/multi-repo-search` | `POST /api/v1/search` with a `repos: string[]` body param | Phase 138 | Not scheduled | `src/server/routes/analysis.ts` (`multi-repo-search` handler); response carries a `Deprecation: true` header + a `Link: </api/v1/search>; rel="successor-version"` header on every call instead of a stderr warning (this is an HTTP route, not a CLI command) |
 
 `POST /analysis/multi-repo-search`'s bare 4-param shape (`query`, `repoIds`,