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.
rm stale
Julius Marminge709cd02cf48c
diff --git a/.plans/pr89-review-feedback-resolution-plan.md b/.plans/pr89-review-feedback-resolution-plan.mddeleted file mode 100644index 5757ee7b1..000000000--- a/.plans/pr89-review-feedback-resolution-plan.md+++ /dev/null@@ -1,421 +0,0 @@-# 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.-