Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.
harden transport
Julius Marminge320f249a3139
diff --git a/.oxfmtrc.json b/.oxfmtrc.jsonindex 8bb9df724..f0fbfde6d 100644--- a/.oxfmtrc.json+++ b/.oxfmtrc.json@@ -6,7 +6,8 @@"dist-electron","node_modules","bun.lock",- "*.tsbuildinfo"+ "*.tsbuildinfo",+ "**/routeTree.gen.ts"],"experimentalSortPackageJson": {}}diff --git a/.plans/16-frontend-contract-schema-validation-alignment.md b/.plans/16-frontend-contract-schema-validation-alignment.mdnew file mode 100644index 000000000..5ead8949c--- /dev/null+++ b/.plans/16-frontend-contract-schema-validation-alignment.md@@ -0,0 +1,182 @@+# Plan: Frontend Contract Schema Validation Alignment++## Summary+Align frontend input/output validation with `@t3tools/contracts` schemas so the web client stops relying on ad-hoc checks and unsafe casts at critical boundaries.++## Goals+1. Decode all WebSocket envelopes with shared contract schemas.+2. Decode push payloads before handing them to app logic.+3. Replace duplicated frontend range/input checks with contract schema decoding.+4. Validate project search params with shared constraints before dispatch.+5. Validate script keybinding updates with `KeybindingRule` schema before RPC.+6. Propagate branded IDs (`ThreadId`, `ProjectId`, etc.) through typed app flow after single ingress conversion.++## Non-Goals+- No protocol shape changes.+- No server behavior changes unless uncovered by failing tests.+- No UI redesign; only validation/transport boundary hardening.++## Phase 1: WebSocket Envelope Decoding++### Issue+`apps/web/src/wsTransport.ts` parses JSON and performs manual object/cast checks (`as WsPush`) instead of decoding with contracts.++### Changes+1. Decode inbound messages with contract schema union (`WsResponse`).+2. Remove manual push/response shape checks that duplicate schema logic.+3. Convert decode failures into safe no-op handling with structured debug logging.++### Target Files+- `apps/web/src/wsTransport.ts`+- `apps/web/src/wsTransport.test.ts`++### Tests+1. Accept valid push envelope and route to channel listener.+2. Accept valid response envelope and resolve pending request.+3. Reject malformed envelope without crashing transport.++## Phase 2: Push Payload Decoding at API Boundary++### Issue+`apps/web/src/wsNativeApi.ts` forwards unknown push payloads and uses direct casts (`data as WsWelcomePayload`).++### Changes+1. Decode `server.welcome` payload with `WsWelcomePayload`.+2. Decode `terminal.event` payload with `TerminalEvent`.+3. Decode `orchestration.domainEvent` payload with `OrchestrationEvent`.+4. Skip invalid payloads safely and keep subscriptions alive.++### Target Files+- `apps/web/src/wsNativeApi.ts`+- `apps/web/src/wsNativeApi.test.ts`++### Tests+1. Valid welcome payload is delivered and cached.+2. Invalid welcome payload is ignored.+3. Valid terminal/orchestration events are forwarded.+4. Invalid push data does not invoke consumers.++## Phase 3: Replace Duplicated Checkpoint Range Validation++### Issue+`apps/web/src/lib/providerReactQuery.ts` duplicates `fromTurnCount`/`toTurnCount` validation rules already represented in contracts.++### Changes+1. Use `OrchestrationGetTurnDiffInput` / `OrchestrationGetFullThreadDiffInput` decoding before RPC calls.+2. Remove bespoke integer/range checks where schema decoding can be authoritative.+3. Preserve current UX behavior (`enabled` gating + retry policy).++### Target Files+- `apps/web/src/lib/providerReactQuery.ts`+- `apps/web/src/lib/providerReactQuery.test.ts`++### Tests+1. Valid range decodes and calls expected RPC.+2. Invalid range fails fast and avoids RPC call.+3. `fromTurnCount === 0` path still routes to `getFullThreadDiff`.++## Phase 4: Project Search Input Validation from Contracts++### Issue+`apps/web/src/lib/projectReactQuery.ts` forwards search inputs without enforcing `ProjectSearchEntriesInput` constraints, and `ChatView` can pass empty query strings.++### Changes+1. Decode project search input with `ProjectSearchEntriesInput` before request dispatch.+2. Gate query execution when query is empty after trim.+3. Replace magic search limit usage with shared constant (`PROJECT_SEARCH_ENTRIES_MAX_LIMIT`) or schema-safe value.++### Target Files+- `apps/web/src/lib/projectReactQuery.ts`+- `apps/web/src/components/ChatView.tsx`+- `apps/web/src/lib/projectReactQuery.test.ts`++### Tests+1. Empty query does not dispatch request.+2. Over-limit values are rejected or clamped via schema-safe path.+3. Valid queries still return prior placeholder behavior.++## Phase 5: Script/Keybinding Validation Consistency++### Issue+`ProjectScriptsControl` and `ChatView` rely mostly on local non-empty checks while sending keybinding data into a contract-validated endpoint (`server.upsertKeybinding`).++### Changes+1. Add pre-submit decode for keybinding payload using `KeybindingRule`.+2. Normalize and validate keybinding values via schema before calling `upsertKeybinding`.+3. Keep existing script ID command generation logic, but ensure command + key are schema-valid before mutation.++### Target Files+- `apps/web/src/components/ProjectScriptsControl.tsx`+- `apps/web/src/components/ChatView.tsx`+- (optional helper) `apps/web/src/projectScripts.ts`+- `apps/web/src/components/ProjectScriptsControl.test.tsx` (or logic test file)++### Tests+1. Invalid keybinding string surfaces UI validation error and blocks submission.+2. Valid keybinding updates still persist and refresh cached server config.+3. Editing existing script preserves valid keybinding mapping behavior.++## Phase 6: Branded ID Flow (Single Ingress Branding)++### Issue+Frontend currently converts plain strings to branded IDs repeatedly (`asThreadId`, `asProjectId`, etc.) at many callsites, which spreads unsafe conversions across app logic.++### Desired Model+1. Convert/decode to branded IDs once at ingress boundaries.+2. Keep IDs branded through store state, selectors, and command/query builders.+3. Avoid repeated `*.makeUnsafe` wrappers in feature logic.++### Boundary Rules+1. Router/search params (string) -> decode to branded IDs at route boundary.+2. Storage/network payloads (untyped JSON) -> decode with contract schemas at transport/query boundary.+3. ID generation (`newThreadId`, `newProjectId`, etc.) remains branded at source.+4. UI components should consume typed IDs from store/hooks, not raw strings.++### Changes+1. Introduce a thin typed ID layer in web app (or reuse contracts decoders directly) for safe `unknown -> branded` conversion at boundaries.+2. Refactor web store and thread/project domain types to carry branded IDs where feasible.+3. Replace repeated `asThreadId`/`asProjectId` callsites in:+ - `apps/web/src/components/ChatView.tsx`+ - `apps/web/src/components/Sidebar.tsx`+ - `apps/web/src/components/BranchToolbar.tsx`+ - `apps/web/src/lib/providerReactQuery.ts`+4. Keep unavoidable casts isolated in one boundary module (not feature components).+5. Minimize/remove broad `asXId` helpers from `apps/web/src/lib/orchestrationIds.ts` once flow is typed.++### Target Files+- `apps/web/src/lib/orchestrationIds.ts`+- `apps/web/src/types.ts`+- `apps/web/src/store.ts`+- `apps/web/src/components/ChatView.tsx`+- `apps/web/src/components/Sidebar.tsx`+- `apps/web/src/components/BranchToolbar.tsx`+- `apps/web/src/lib/providerReactQuery.ts`+- route boundary files (`apps/web/src/routes/*`) as needed++### Tests+1. Type-level regression checks (compile-time) proving command builders accept branded IDs directly.+2. Route/load path tests verifying invalid ID ingress is rejected/fails safely.+3. Existing behavior tests still pass for thread/project operations after refactor.++## Cross-Cutting Execution Notes+1. Prefer a small shared frontend utility for Effect schema decoding to avoid repeated `decodeUnknownSync` boilerplate.+2. Use `Schema.decodeUnknownEither` or equivalent non-throwing path where event stream robustness matters.+3. Keep failure behavior fail-soft at stream boundaries (drop invalid events, keep transport running).+4. Brands are TypeScript-level constraints; JSON boundaries still require decode/re-brand at ingress.++## Validation Checklist+1. `bun run lint`+2. `bun run test --filter=@t3tools/web` (or equivalent web test command in repo)+3. Manual smoke checks:+ - App boot + welcome sync+ - Terminal stream still renders+ - Diff panel loads checkpoint ranges+ - Path autocomplete search remains responsive+ - Script add/edit with keybinding works in Electron flow++## Done Criteria+1. No unsafe push/event casts remain at core WebSocket boundaries.+2. Frontend no longer duplicates contract input validation for checkpoint range and project search.+3. Keybinding submission path is schema-validated before RPC.+4. Branded IDs flow through frontend feature code without repeated `asThreadId`/`asProjectId` wrappers.+5. Updated tests cover malformed payload and invalid input regressions.diff --git a/.plans/pr89-review-feedback-resolution-plan.md b/.plans/pr89-review-feedback-resolution-plan.mdnew file mode 100644index 000000000..5757ee7b1--- /dev/null+++ b/.plans/pr89-review-feedback-resolution-plan.md@@ -0,0 +1,421 @@+# PR #89 Review Feedback Resolution Plan++## Context+- Source: GitHub review threads/comments on PR `#89` (`Add server-side orchestration engine with event sourcing`).+- Triage baseline:+ - 147 threads, 149 comments total.+ - 54 active unresolved threads.+ - Deduped to 47 unique active issues.+ - Filtered invalid/wrong claims: 2 issue clusters.+ - Net actionable backlog: 45 unique issues.++## Objectives+1. Remove high-risk runtime failure modes first (worker/fiber death, unrecoverable ingestion stalls).+2. Preserve event-sourcing correctness under failure/retry (projection, receipts, checkpoint ordering).+3. Resolve client-visible correctness regressions (branch/session races, markdown link parsing).+4. Close low-signal or duplicate review noise with explicit disposition.++## Non-Goals+- No protocol reintroduction for removed `providers.event` channel (invalid comment cluster).+- No architecture rewrite beyond targeted hardening and correctness fixes needed to land PR safely.++## Execution Order+1. **Phase A (P0): Runtime fault tolerance**+2. **Phase B (P0/P1): Checkpoint consistency + sequencing**+3. **Phase C (P1): Persistence/projection correctness**+4. **Phase D (P1/P2): Runtime/platform hardening**+5. **Phase E (P1/P2): Web/client correctness**+6. **Phase F (P2): Cleanup/typing hygiene + review thread closure**++---++## Phase A (P0) - Runtime Fault Tolerance++### A1) Provider runtime ingestion loop can die permanently on one dispatch error+- Issue:+ - `ProviderRuntimeIngestion` uses `Effect.forever(Queue.take(...).flatMap(processEvent))` without local recovery. A single failure can terminate the worker fiber.+- Planned resolution:+ - Wrap per-item processing with `Effect.catch` (don't use `catchAllCause` as that is a signal for detects which should not be recovered from) and structured logging (`event.type`, `sessionId`, `threadId if known`).+ - Keep queue consumer alive after failures.+ - Add a bounded error counter metric/log cadence to avoid log spam.+- Target files:+ - `apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts`+ - `apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts`+- Tests:+ - Add test where first dispatch fails, second event still processes successfully.+ - Assert worker remains alive and queue continues draining.++### A2) Provider command reactor loop can die permanently on provider-side failure+- Issue:+ - `ProviderCommandReactor` queue consumer also runs forever with no protection around `processDomainEvent`.+- Planned resolution:+ - Apply same per-item fault boundary as A1.+ - Differentiate retryable provider errors vs invariant errors for log level (`warn` vs `error`).+- Target files:+ - `apps/server/src/orchestration/Layers/ProviderCommandReactor.ts`+ - `apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts`+- Tests:+ - Inject provider service failure for one event and verify subsequent events still execute.++### A3) Checkpoint reactor worker can die and halt checkpointing for process lifetime+- Issue:+ - `CheckpointReactor` queue worker has no internal error boundary; checkpoint/git failures can stop all future checkpoint handling.+- Planned resolution:+ - Add per-item recovery with contextual logging.+ - Keep worker alive for transient checkpoint/git errors.+ - Optionally emit `thread.activity.append` error activity for visibility when checkpoint operations fail.+- Target files:+ - `apps/server/src/orchestration/Layers/CheckpointReactor.ts`+ - `apps/server/src/orchestration/Layers/CheckpointReactor.test.ts`+- Tests:+ - Simulate failing `CheckpointStore` call on one event; verify next event still processes.++### A4) WS message handler can surface unhandled rejection at runtime+- Issue:+ - `Effect.runPromise(handleMessage(...))` path flagged for potential unhandled rejection.+- Planned resolution:+ - Add explicit `.catch` with structured logging on message processing invocation path.+ - Ensure one bad message cannot destabilize the WebSocket server.+- Target files:+ - `apps/server/src/wsServer.ts`+ - `apps/server/src/wsServer.test.ts`+- Tests:+ - Add regression test forcing `handleMessage` error and assert server still accepts/processes subsequent messages.++---++## Phase B (P0/P1) - Checkpoint Consistency + Sequencing++### B1) Revert flow uses forked completion dispatch and can expose stale read model window+- Issue:+ - `thread.revert.complete` dispatch is forked in reactor path, allowing downstream logic to observe stale state during revert completion window.+- Planned resolution:+ - Make revert completion dispatch part of the same serialized effect flow (await it rather than fire-and-forget).+ - Preserve ordering guarantees: fs restore/provider rollback/delete ref -> completion command -> next dependent work.+- Target files:+ - `apps/server/src/orchestration/Layers/CheckpointReactor.ts`+ - `apps/server/src/orchestration/Layers/CheckpointReactor.test.ts`+- Tests:+ - Add ordering test ensuring revert completion is visible before subsequent checkpoint-dependent processing.++### B2) Turn-count inference can be wrong when positional index diverges from authoritative count+- Issue:+ - `inferCheckpointTurnCountByTurnId` fallback behavior may infer count from position, leading to incorrect revert semantics.+- Planned resolution:+ - Use authoritative checkpoint metadata when available.+ - Restrict positional fallback to explicit best-effort mode and prevent it from driving destructive operations.+- Target files:+ - `apps/web/src/session-logic.ts`+ - `apps/web/src/session-logic.test.ts`+- Tests:+ - Add cases where positional order differs from persisted turn count and assert correct count resolution.++### B3) Inconsistent input normalization across checkpoint store methods+- Issue:+ - Some `CheckpointStore` methods trim/normalize input while others do not, creating inconsistent ref/cwd behavior.+- Planned resolution:+ - Introduce shared normalization utility and apply uniformly across all public `CheckpointStore` methods.+ - Keep normalization semantics explicit and covered by tests.+- Target files:+ - `apps/server/src/checkpointing/Layers/CheckpointStore.ts`+ - existing checkpointing tests (and add targeted method-level tests)+- Tests:+ - Parameterized tests that call all methods with leading/trailing whitespace and assert consistent behavior.++### B4) Duplicate checkpoint-ref generation logic across runtime and tests+- Issue:+ - `checkpointRefForThreadTurn` logic is duplicated across multiple files, creating drift risk.+- Planned resolution:+ - Extract a single shared helper module for checkpoint ref generation.+ - Migrate runtime and test callsites to helper.+- Target files:+ - `apps/server/src/checkpointing/*` or `apps/server/src/orchestration/*` shared helper (new)+ - `apps/server/src/wsServer.ts`+ - `apps/server/src/orchestration/Layers/CheckpointReactor.ts`+ - impacted tests/integration harnesses+- Tests:+ - Add dedicated helper tests for deterministic encoding format and stability.++---++## Phase C (P1) - Persistence / Projection Correctness++### C1) Event append and projection update can diverge on mid-pipeline failure+- Issue:+ - If event append succeeds and projection/update fails, state can become desynchronized.+- Planned resolution:+ - Rework processing boundary so in-memory and persisted projection updates happen in a single coherent success path.+ - If projection fails, fail command deterministically and record consistent receipt/error path.+- Target files:+ - `apps/server/src/orchestration/Layers/OrchestrationEngine.ts`+ - `apps/server/src/orchestration/Layers/ProjectionPipeline.ts`+ - related persistence layer files as needed+- Tests:+ - Simulate projection failure post-append and verify deterministic observable state + receipt behavior.++### C2) Engine error handling/receipt semantics are incomplete for non-invariant failures+- Issue:+ - Non-invariant failures may not persist failure receipt consistently, weakening idempotency/retry behavior.+- Planned resolution:+ - Define explicit receipt policy for invariant vs infrastructure failures.+ - Persist rejected receipt shape with error classification and retryability signal.+- Target files:+ - `apps/server/src/orchestration/Layers/OrchestrationEngine.ts`+ - `apps/server/src/persistence/Layers/OrchestrationCommandReceipts.ts`+ - `apps/server/src/orchestration/*test.ts`+- Tests:+ - Retry same `commandId` after failure and assert deterministic replay/idempotency behavior.++### C3) Projection pipeline fallback can preserve orphaned messages (FK risk)+- Issue:+ - Gap-filling fallback logic can retain messages tied to removed turns.+- Planned resolution:+ - Remove fallback or strictly filter fallback messages by retained turn ids.+ - Validate FK-safe mutation path.+- Target files:+ - `apps/server/src/orchestration/Layers/ProjectionPipeline.ts`+ - `apps/server/src/orchestration/Layers/ProjectionPipeline.test.ts`+- Tests:+ - Revert/delete turn scenarios proving no orphaned message rows remain.++### C4) Snapshot projector barrier includes projectors not read by snapshot query+- Issue:+ - Barrier can wait for projector state not represented in returned payload, causing sequence mismatch/replay confusion.+- Planned resolution:+ - Align `REQUIRED_SNAPSHOT_PROJECTORS` with actual snapshot query surface.+ - Add explicit comment/contract for inclusion criteria.+- Target files:+ - `apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts`+ - `apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts`+- Tests:+ - Validate `snapshotSequence` monotonic correctness against included tables/data only.++### C5) NodeSqlite client resource/typing hazards+- Issue:+ - `executeUnprepared` statement lifecycle and return-shape comments indicate leak/type hazards.+- Planned resolution:+ - Wrap prepare/finalize in `Effect.acquireUseRelease`.+ - Correct return typing contract and caller expectations.+- Target files:+ - `apps/server/src/persistence/NodeSqliteClient.ts`+ - `apps/server/src/persistence/NodeSqliteClient.test.ts`+- Tests:+ - Resource cleanup test (finalize always invoked).+ - Return-shape test for `run` paths.++### C6) Event metadata defaults created at module load are fragile+- Issue:+ - Shared `defaultMetadata` object pattern risks stale defaults if future event construction forgets overrides.+- Planned resolution:+ - Replace static default object with per-event metadata factory function.+ - Avoid mutable shared default structures.+- Target files:+ - `apps/server/src/orchestration/decider.ts`+ - decider/orchestration tests+- Tests:+ - Ensure unique event metadata (`eventId`, timestamps) per decision invocation.++### C7) Provider session directory read-modify-write lost update risk+- Issue:+ - Concurrent upserts can clobber fields without transactional/version guard.+- Planned resolution:+ - Introduce transaction or optimistic version check around merge-upsert path.+- Target files:+ - `apps/server/src/provider/Layers/ProviderSessionDirectory.ts`+ - corresponding test file(s)+- Tests:+ - Concurrency test with competing updates preserving expected merged state.++---++## Phase D (P1/P2) - Runtime / Platform Hardening++### D1) WS upgrade reject path socket safety+- Issue:+ - Potential `EPIPE/ECONNRESET` during reject write path and response flush concerns.+- Planned resolution:+ - Attach socket error listener in reject path and use `socket.end` where appropriate.+ - Keep behavior deterministic under disconnect-mid-handshake.+- Target files:+ - `apps/server/src/wsServer.ts`+ - `apps/server/src/wsServer.test.ts`+- Tests:+ - Add handshake-disconnect scenario confirming no crash.++### D2) PTY adapter platform selection and lifecycle races+- Issue:+ - Bun+Windows selection can hit `Effect.die`.+ - `didExit` guard can drop buffered output.+ - executable-fix flag can be set before successful chmod.+- Planned resolution:+ - Gate Bun PTY path by platform capability.+ - Adjust output/exit ordering to avoid dropped data.+ - Move helper-executable flag set after successful chmod.+- Target files:+ - `apps/server/src/ptyAdapter.ts`+ - `apps/server/src/ptyAdapter.test.ts`+- Tests:+ - Platform selection unit test.+ - Output-after-exit race regression test.+ - chmod failure retry behavior test.++### D3) Shell PATH probing robustness+- Issue:+ - `-il` can pollute output; fish shell PATH formatting may not be colon-separated.+- Planned resolution:+ - Switch probing flags/commands to deterministic non-interactive mode.+ - Add fish-specific join handling or fallback validation.+- Target files:+ - `apps/server/src/os-jank.ts`+ - add/extend tests+- Tests:+ - Parsing tests for bash/zsh/fish simulated outputs.++### D4) Effect callback cleanup omissions+- Issue:+ - Missing cleanup function can leak server handles on interruption.+- Planned resolution:+ - Ensure `Effect.callback` paths return cleanup that closes listeners/servers.+- Target files:+ - `apps/server/src/config.ts`+ - relevant tests+- Tests:+ - Start/interrupt lifecycle test verifies no leaked handles.++---++## Phase E (P1/P2) - Web / Client Correctness++### E1) Pending approvals indicator is non-functional+- Issue:+ - `pendingApprovalByThreadId` map is currently static/empty, so badge never reflects real state.+- Planned resolution:+ - Derive map from authoritative read model activity/pending approval state.+ - Remove dead map initialization pattern.+- Target files:+ - `apps/web/src/components/Sidebar.tsx`+ - add sidebar logic tests+- Tests:+ - Given approval activity in thread, badge appears and clears appropriately.++### E2) Branch toolbar dual-write can cause flicker/inconsistent session state+- Issue:+ - Local `SET_THREAD_BRANCH` + server command dispatch creates temporary contradictory state.+- Planned resolution:+ - Move to single-source update path: server command + read-model sync.+ - Keep optimistic UI only if it is reconciled safely.+- Target files:+ - `apps/web/src/components/BranchToolbar.tsx`+ - `apps/web/src/components/BranchToolbar.logic.test.ts`+- Tests:+ - Ensure no local stale session overwrite when server model update arrives.++### E3) Markdown link parser false-positive scheme + double decode+- Issue:+ - `script.ts:10` misclassified as external scheme.+ - file URL path can be decoded twice.+- Planned resolution:+ - Tighten external scheme detection (`://` or equivalent guard).+ - Avoid second decode when source was already parsed from file URL.+- Target files:+ - `apps/web/src/markdown-links.ts`+ - `apps/web/src/markdown-links.test.ts`+- Tests:+ - Add tests for `script.ts:10`, percent-encoded file names, and valid external schemes.++### E4) WS transport request/error edge cases+- Issue:+ - Spreading params into body can override reserved keys.+ - malformed error payload can resolve instead of reject.+- Planned resolution:+ - Normalize request envelope shape to prevent key collisions.+ - Harden error decoding fallback so promise rejects on any error object.+- Target files:+ - `apps/web/src/wsTransport.ts`+ - add/extend wsTransport tests+- Tests:+ - Reserved key collision case.+ - Error object without message still rejects with fallback.++### E5) Sidebar width bootstrap from localStorage can default incorrectly+- Issue:+ - `Number(null) === 0` can force unintended min width on first load.+- Planned resolution:+ - Explicit null/empty guard before number parse.+- Target files:+ - `apps/web/src/routes/_chat.$threadId.tsx`+ - add route/component unit test+- Tests:+ - First-load with missing key preserves default width behavior.++---++## Phase F (P2) - Cleanup / Typing Hygiene++### F1) Symbol-safe string interpolation for error messages+- Issue:+ - Interpolating raw symbol causes TypeError in some error formatting paths.+- Planned resolution:+ - Use `String(cause)`/safe coercion helper consistently.+- Target files:+ - `apps/server/src/orchestration/Errors.ts`+ - `apps/server/src/provider/Layers/ProviderService.ts`+- Tests:+ - Add symbol/undefined/function cause formatting tests.++### F2) Remove redundant union members and dead error classes if truly unused+- Issue:+ - Redundant type entries and potentially dead error classes increase noise.+- Planned resolution:+ - Remove redundant union members.+ - Either remove dead classes or document retained intent with usage boundary.+- Target files:+ - `apps/server/src/checkpointing/Errors.ts`+ - related type/tests+- Tests:+ - Type-level and runtime regression checks around error mapping.++### F3) Documentation cleanup comments+- Issue:+ - Review flagged temporary marker in docs.+- Planned resolution:+ - Remove transient marker if no longer needed.+- Target files:+ - `AGENTS.md`++---++## Review Comment Disposition Plan++### Duplicate clusters to close with one canonical fix comment+1. `providers.event` restoration requests (same underlying claim).+2. Build script `node scripts/bundle-client.ts` (same claim repeated).+3. CheckpointStore normalization duplicates.+4. `handledTurnStartKeys` growth duplicates.+5. checkpoint-ref helper duplication variants.++### Invalid/wrong clusters to close as “no action”+1. Reintroduce `providers.event` channel:+ - Current contracts/channel surface does not define it.+ - PR is intentionally orchestration-domain-event based.+2. Build script cannot run `.ts` under Node:+ - Repository pins modern Node and script executes successfully in current environment.++---++## Verification and Quality Gates++### Required per phase+1. Implement targeted tests for backend behavior changes (no mocking out core business logic).+2. Run affected package test suites (at minimum):+ - `bun run --cwd apps/server test`+ - `bun run --cwd apps/web test`+3. Run root lint before marking phase complete:+ - `bun run lint`++### Final pre-merge gate+1. Full lint pass with no new warnings introduced by this work.+2. Server tests pass for orchestration/reactor/checkpoint/persistence packages.+3. Web tests pass for markdown/branch/sidebar/ws transport paths.+4. Resolve or explicitly disposition all active review threads with links to fixes.+diff --git a/SPEC.md b/SPEC.mdindex 42881e298..175a3f552 100644--- a/SPEC.md+++ b/SPEC.md@@ -527,6 +527,7 @@ Projection consistency rules:1. `orchestration.getSnapshot` is fully served from projection tables and returns `snapshotSequence: number`.2. Snapshot must include `projects[]` from `projection_projects`.3. Thread snapshot must include `checkpoints[]` from `projection_checkpoints`:+- `turnId: TurnId`- `completedAt: IsoDateTime`- `status`@@ -534,15 +535,23 @@ Projection consistency rules:- `checkpointRef: CheckpointRef`- `assistantMessageId?: MessageId`- `checkpointTurnCount: number`+4. Client does not require `listCheckpoints` RPC:+- checkpoint list comes from snapshot projections- full diff text comes from `orchestration.getTurnDiff` backed by `checkpoint_diff_blobs`+5. Provider session identity is not a client routing key:+- client acts on `ThreadId`- server resolves provider session internally via `projection_thread_sessions`+6. `snapshotSequence` is derived from `projection_state`:+- if snapshot depends on multiple projectors, use the minimum `lastAppliedSequence` across those projectors.+7. Event subscription handoff contract:+- client performs `getSnapshot` and reads `snapshotSequence`- client subscribes/replays with `fromSequenceExclusive = snapshotSequence`- server guarantees no gap between snapshot visibility and subsequent event stream from that sequence.@@ -557,14 +566,17 @@ Projection consistency rules:### 7.6 Existing Repository Placement1. `ProjectsRepository`+- Fits as projection/query access on top of `projection_projects` plus orchestration command dispatch for writes.- Must not bypass command->event append path for mutations.2. `CheckpointsRepository`+- Fits as projection/query access on top of `projection_checkpoints` plus `checkpoint_diff_blobs` (or git-service on-demand diff implementation).- Represents the same concept as prior `turn_diff_summary`; canonical naming is `checkpoint`.- Must not be an independent source of truth outside orchestration events.3. `ProviderSessionsRepository`+- Fits as server-internal runtime persistence on top of `provider_session_runtime`, with domain-visible state projected into `projection_thread_sessions`.- Not part of client RPC/domain aggregate boundary.diff --git a/apps/web/src/routeTree.gen.ts b/apps/web/src/routeTree.gen.tsindex 20f8541ae..880d5ef64 100644--- a/apps/web/src/routeTree.gen.ts+++ b/apps/web/src/routeTree.gen.ts@@ -8,111 +8,111 @@// You should NOT make any changes in this file as it will be overwritten.// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.-import { Route as rootRouteImport } from "./routes/__root";-import { Route as ChatRouteImport } from "./routes/_chat";-import { Route as ChatIndexRouteImport } from "./routes/_chat.index";-import { Route as ChatSettingsRouteImport } from "./routes/_chat.settings";-import { Route as ChatThreadIdRouteImport } from "./routes/_chat.$threadId";+import { Route as rootRouteImport } from './routes/__root'+import { Route as ChatRouteImport } from './routes/_chat'+import { Route as ChatIndexRouteImport } from './routes/_chat.index'+import { Route as ChatSettingsRouteImport } from './routes/_chat.settings'+import { Route as ChatThreadIdRouteImport } from './routes/_chat.$threadId'const ChatRoute = ChatRouteImport.update({- id: "/_chat",+ id: '/_chat',getParentRoute: () => rootRouteImport,-} as any);+} as any)const ChatIndexRoute = ChatIndexRouteImport.update({- id: "/",- path: "/",+ id: '/',+ path: '/',getParentRoute: () => ChatRoute,-} as any);+} as any)const ChatSettingsRoute = ChatSettingsRouteImport.update({- id: "/settings",- path: "/settings",+ id: '/settings',+ path: '/settings',getParentRoute: () => ChatRoute,-} as any);+} as any)const ChatThreadIdRoute = ChatThreadIdRouteImport.update({- id: "/$threadId",- path: "/$threadId",+ id: '/$threadId',+ path: '/$threadId',getParentRoute: () => ChatRoute,-} as any);+} as any)export interface FileRoutesByFullPath {- "/": typeof ChatIndexRoute;- "/$threadId": typeof ChatThreadIdRoute;- "/settings": typeof ChatSettingsRoute;+ '/': typeof ChatIndexRoute+ '/$threadId': typeof ChatThreadIdRoute+ '/settings': typeof ChatSettingsRoute}export interface FileRoutesByTo {- "/$threadId": typeof ChatThreadIdRoute;- "/settings": typeof ChatSettingsRoute;- "/": typeof ChatIndexRoute;+ '/$threadId': typeof ChatThreadIdRoute+ '/settings': typeof ChatSettingsRoute+ '/': typeof ChatIndexRoute}export interface FileRoutesById {- __root__: typeof rootRouteImport;- "/_chat": typeof ChatRouteWithChildren;- "/_chat/$threadId": typeof ChatThreadIdRoute;- "/_chat/settings": typeof ChatSettingsRoute;- "/_chat/": typeof ChatIndexRoute;+ __root__: typeof rootRouteImport+ '/_chat': typeof ChatRouteWithChildren+ '/_chat/$threadId': typeof ChatThreadIdRoute+ '/_chat/settings': typeof ChatSettingsRoute+ '/_chat/': typeof ChatIndexRoute}export interface FileRouteTypes {- fileRoutesByFullPath: FileRoutesByFullPath;- fullPaths: "/" | "/$threadId" | "/settings";- fileRoutesByTo: FileRoutesByTo;- to: "/$threadId" | "/settings" | "/";- id: "__root__" | "/_chat" | "/_chat/$threadId" | "/_chat/settings" | "/_chat/";- fileRoutesById: FileRoutesById;+ fileRoutesByFullPath: FileRoutesByFullPath+ fullPaths: '/' | '/$threadId' | '/settings'+ fileRoutesByTo: FileRoutesByTo+ to: '/$threadId' | '/settings' | '/'+ id: '__root__' | '/_chat' | '/_chat/$threadId' | '/_chat/settings' | '/_chat/'+ fileRoutesById: FileRoutesById}export interface RootRouteChildren {- ChatRoute: typeof ChatRouteWithChildren;+ ChatRoute: typeof ChatRouteWithChildren}-declare module "@tanstack/react-router" {+declare module '@tanstack/react-router' {interface FileRoutesByPath {- "/_chat": {- id: "/_chat";- path: "";- fullPath: "/";- preLoaderRoute: typeof ChatRouteImport;- parentRoute: typeof rootRouteImport;- };- "/_chat/": {- id: "/_chat/";- path: "/";- fullPath: "/";- preLoaderRoute: typeof ChatIndexRouteImport;- parentRoute: typeof ChatRoute;- };- "/_chat/settings": {- id: "/_chat/settings";- path: "/settings";- fullPath: "/settings";- preLoaderRoute: typeof ChatSettingsRouteImport;- parentRoute: typeof ChatRoute;- };- "/_chat/$threadId": {- id: "/_chat/$threadId";- path: "/$threadId";- fullPath: "/$threadId";- preLoaderRoute: typeof ChatThreadIdRouteImport;- parentRoute: typeof ChatRoute;- };+ '/_chat': {+ id: '/_chat'+ path: ''+ fullPath: '/'+ preLoaderRoute: typeof ChatRouteImport+ parentRoute: typeof rootRouteImport+ }+ '/_chat/': {+ id: '/_chat/'+ path: '/'+ fullPath: '/'+ preLoaderRoute: typeof ChatIndexRouteImport+ parentRoute: typeof ChatRoute+ }+ '/_chat/settings': {+ id: '/_chat/settings'+ path: '/settings'+ fullPath: '/settings'+ preLoaderRoute: typeof ChatSettingsRouteImport+ parentRoute: typeof ChatRoute+ }+ '/_chat/$threadId': {+ id: '/_chat/$threadId'+ path: '/$threadId'+ fullPath: '/$threadId'+ preLoaderRoute: typeof ChatThreadIdRouteImport+ parentRoute: typeof ChatRoute+ }}}interface ChatRouteChildren {- ChatThreadIdRoute: typeof ChatThreadIdRoute;- ChatSettingsRoute: typeof ChatSettingsRoute;- ChatIndexRoute: typeof ChatIndexRoute;+ ChatThreadIdRoute: typeof ChatThreadIdRoute+ ChatSettingsRoute: typeof ChatSettingsRoute+ ChatIndexRoute: typeof ChatIndexRoute}const ChatRouteChildren: ChatRouteChildren = {ChatThreadIdRoute: ChatThreadIdRoute,ChatSettingsRoute: ChatSettingsRoute,ChatIndexRoute: ChatIndexRoute,-};+}-const ChatRouteWithChildren = ChatRoute._addFileChildren(ChatRouteChildren);+const ChatRouteWithChildren = ChatRoute._addFileChildren(ChatRouteChildren)const rootRouteChildren: RootRouteChildren = {ChatRoute: ChatRouteWithChildren,-};+}export const routeTree = rootRouteImport._addFileChildren(rootRouteChildren)- ._addFileTypes<FileRouteTypes>();+ ._addFileTypes<FileRouteTypes>()diff --git a/apps/web/src/wsTransport.test.ts b/apps/web/src/wsTransport.test.tsnew file mode 100644index 000000000..e47073fc2--- /dev/null+++ b/apps/web/src/wsTransport.test.ts@@ -0,0 +1,175 @@+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";++import { WsTransport } from "./wsTransport";++type WsEventType = "open" | "message" | "close" | "error";+type WsListener = (event?: { data?: unknown }) => void;++const sockets: MockWebSocket[] = [];++class MockWebSocket {+ static readonly CONNECTING = 0;+ static readonly OPEN = 1;+ static readonly CLOSING = 2;+ static readonly CLOSED = 3;++ readyState = MockWebSocket.CONNECTING;+ readonly sent: string[] = [];+ private readonly listeners = new Map<WsEventType, Set<WsListener>>();++ constructor(_url: string) {+ sockets.push(this);+ }++ addEventListener(type: WsEventType, listener: WsListener) {+ const listeners = this.listeners.get(type) ?? new Set<WsListener>();+ listeners.add(listener);+ this.listeners.set(type, listeners);+ }++ send(data: string) {+ this.sent.push(data);+ }++ close() {+ this.readyState = MockWebSocket.CLOSED;+ this.emit("close");+ }++ open() {+ this.readyState = MockWebSocket.OPEN;+ this.emit("open");+ }++ serverMessage(data: unknown) {+ this.emit("message", { data });+ }++ private emit(type: WsEventType, event?: { data?: unknown }) {+ const listeners = this.listeners.get(type);+ if (!listeners) return;+ for (const listener of listeners) {+ listener(event);+ }+ }+}++const originalWebSocket = globalThis.WebSocket;++function getSocket(): MockWebSocket {+ const socket = sockets.at(-1);+ if (!socket) {+ throw new Error("Expected a websocket instance");+ }+ return socket;+}++beforeEach(() => {+ sockets.length = 0;++ Object.defineProperty(globalThis, "window", {+ configurable: true,+ value: {+ location: { hostname: "localhost", port: "3020" },+ desktopBridge: undefined,+ },+ });++ globalThis.WebSocket = MockWebSocket as unknown as typeof WebSocket;+});++afterEach(() => {+ globalThis.WebSocket = originalWebSocket;+ vi.restoreAllMocks();+});++describe("WsTransport", () => {+ it("routes valid push envelopes to channel listeners", () => {+ const transport = new WsTransport("ws://localhost:3020");+ const socket = getSocket();+ socket.open();++ const listener = vi.fn();+ transport.subscribe("providers.event", listener);++ socket.serverMessage(+ JSON.stringify({+ type: "push",+ channel: "providers.event",+ data: { status: "ok" },+ }),+ );++ expect(listener).toHaveBeenCalledTimes(1);+ expect(listener).toHaveBeenCalledWith({ status: "ok" });++ transport.dispose();+ });++ it("resolves pending requests for valid response envelopes", async () => {+ const transport = new WsTransport("ws://localhost:3020");+ const socket = getSocket();+ socket.open();++ const requestPromise = transport.request("projects.list");+ const sent = socket.sent.at(-1);+ if (!sent) {+ throw new Error("Expected request envelope to be sent");+ }++ const requestEnvelope = JSON.parse(sent) as { id: string };+ socket.serverMessage(+ JSON.stringify({+ id: requestEnvelope.id,+ result: { projects: [] },+ }),+ );++ await expect(requestPromise).resolves.toEqual({ projects: [] });++ transport.dispose();+ });++ it("drops malformed envelopes without crashing transport", () => {+ const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});+ const transport = new WsTransport("ws://localhost:3020");+ const socket = getSocket();+ socket.open();++ const listener = vi.fn();+ transport.subscribe("providers.event", listener);++ socket.serverMessage("{ invalid-json");+ socket.serverMessage(+ JSON.stringify({+ type: "push",+ channel: 42,+ data: { bad: true },+ }),+ );+ socket.serverMessage(+ JSON.stringify({+ type: "push",+ channel: "providers.event",+ data: { ok: true },+ }),+ );++ expect(listener).toHaveBeenCalledTimes(1);+ expect(listener).toHaveBeenCalledWith({ ok: true });+ expect(warnSpy).toHaveBeenCalledTimes(2);+ expect(warnSpy).toHaveBeenNthCalledWith(1, "Dropped inbound WebSocket envelope", {+ reason: "decode-failed",+ issue:+ "SchemaError: SyntaxError: Expected property name or '}' in JSON at position 2 (line 1 column 3)",+ raw: "{ invalid-json",+ });+ expect(warnSpy).toHaveBeenNthCalledWith(2, "Dropped inbound WebSocket envelope", {+ reason: "decode-failed",+ issue: expect.stringContaining("SchemaError: Expected string, got 42"),+ raw: '{"type":"push","channel":42,"data":{"bad":true}}',+ });++ transport.dispose();+ });+});diff --git a/apps/web/src/wsTransport.ts b/apps/web/src/wsTransport.tsindex de05dca98..8911d3598 100644--- a/apps/web/src/wsTransport.ts+++ b/apps/web/src/wsTransport.ts@@ -1,4 +1,5 @@-import type { WsPush } from "@t3tools/contracts";+import { WebSocketResponse, WsPush, WsResponse, WebSocketRequest } from "@t3tools/contracts";+import { Cause, Schema, SchemaIssue } from "effect";type PushListener = (data: unknown) => void;@@ -10,6 +11,14 @@ interface PendingRequest {const REQUEST_TIMEOUT_MS = 60_000;const RECONNECT_DELAYS_MS = [500, 1_000, 2_000, 4_000, 8_000];+const decodeWsResponseFromJson = Schema.decodeUnknownExit(Schema.fromJsonString(WsResponse));+const isWsPushEnvelope = Schema.is(WsPush);++function isWebSocketResponseEnvelope(+ message: typeof WsResponse.Type,+): message is WebSocketResponse {+ return message instanceof WebSocketResponse;+}interface WsRequestEnvelope {id: string;@@ -127,25 +136,24 @@ export class WsTransport {}private handleMessage(raw: unknown) {- let parsed: unknown;- try {- parsed = JSON.parse(String(raw));- } catch {+ const exit = decodeWsResponseFromJson(raw);+ if (exit._tag === "Failure") {+ console.warn("Dropped inbound WebSocket envelope", {+ reason: "decode-failed",+ raw,+ issue: Cause.pretty(exit.cause),+ });return;}-- if (!parsed || typeof parsed !== "object") return;-- const message = parsed as Record<string, unknown>;+ const message = exit.value;// Push event- if (message.type === "push") {- const push = message as unknown as WsPush;- const channelListeners = this.listeners.get(push.channel);+ if (isWsPushEnvelope(message)) {+ const channelListeners = this.listeners.get(message.channel);if (channelListeners) {for (const listener of channelListeners) {try {- listener(push.data);+ listener(message.data);} catch {// Swallow listener errors}@@ -155,23 +163,20 @@ export class WsTransport {}// Response to a request- if (typeof message.id === "string") {- const responseId = message.id;- const pending = this.pending.get(responseId);- if (!pending) return;+ if (!isWebSocketResponseEnvelope(message)) {+ return;+ }- clearTimeout(pending.timeout);- this.pending.delete(responseId);-- if (- message.error &&- typeof message.error === "object" &&- typeof (message.error as { message?: unknown }).message === "string"- ) {- pending.reject(new Error((message.error as { message: string }).message));- } else {- pending.resolve(message.result);- }+ const pending = this.pending.get(message.id);+ if (!pending) return;++ clearTimeout(pending.timeout);+ this.pending.delete(message.id);++ if (message.error) {+ pending.reject(new Error(message.error.message));+ } else {+ pending.resolve(message.result);}}