logged migration drift fix, sidecar logging, and docs updates to issues

Author: harsha-cpp

ISSUES.md

@@ -5,6 +5,46 @@
 
 ---
 
+## [2026-05-31] — Fix critical migration drift + docs accuracy + sidecar logging
+
+**Status:** Done
+**Agent:** Kiro
+
+### What was done
+- **CRITICAL — Migration drift fixed.** The committed Prisma migrations were badly out of sync with `schema.prisma`: a fresh `db:migrate deploy` produced only 21 tables / 8 `users` columns, while `db:push` (and prod, patched out-of-band) had 30+ tables / 12 `users` columns. This broke the documented `db:migrate:deploy` deploy path and the API test suite (14/18 files failed at setup with `column totpEnabled does not exist`).
+  - Generated reconciliation SQL via `prisma migrate diff` (migration-built DB → schema.prisma) and added migration `20260531000000_reconcile_schema_drift`. It adds the 10 missing tables (`task_assignees`, `sso_configs`, `roles`, `chat_attachments`, `mcp_tool_calls`, `invitations`, `comment_mentions`, `notification_preferences`, `audit_logs`, `sessions`), 3 enums (`invitation_statuses`, `permissions`, `task_assignee_roles`), 4 `users` columns (`totpSecret`, `totpEnabled`, `backupCodes`, `displayName`), `settings.taskDeletionMode`, and `roleId` FKs on workspace_members/team_members/project_access — all with indexes + FKs.
+  - Made every statement **idempotent** (`IF NOT EXISTS`, guarded `DO $$ ... EXCEPTION WHEN duplicate_object` blocks) so it is safe against the already-reconciled production DB.
+  - Added the missing `prisma/migrations/migration_lock.toml` (provider = postgresql) — without it, `prisma migrate diff --from-migrations` could not read the migrations dir.
+  - **Verified:** fresh `migrate deploy` (all migrations incl. reconcile) → 31 tables, 12 user columns, and `prisma migrate diff` reports **"No difference detected"** vs schema. API test suite went from **14 failed/4 passed** to **18 passed / 149 tests / exit 0**.
+- **Docs accuracy.** Removed the false "100% test coverage on execution services" claim from `docs/CODEBASE_INDEX.md` (sidecar actually has 0 automated tests). Updated `docs/ARCHITECTURE.md` deployment section (DigitalOcean/PM2 → Azure Container Apps + ACR, current `deploy-azure.yml` pipeline) and auth section (added PAT + TOTP 2FA + SSO alongside GitHub OAuth). Softened the "GitHub OAuth is the only login method" line in `docs/features/api-reference.md`.
+- **Sidecar logging.** Confirmed the `console.*` → pino `logger` migration across all `apps/sidecar/src` services/routes (was already present in the working tree; verified 0 `console.` calls remain in non-test sidecar source, typecheck clean). This closes the last open guardrail from the F1 plan-compliance review (REJECT-4).
+
+### Files changed
+- `packages/db/prisma/migrations/20260531000000_reconcile_schema_drift/migration.sql` — new reconciliation migration (idempotent)
+- `packages/db/prisma/migrations/migration_lock.toml` — new (was missing)
+- `docs/CODEBASE_INDEX.md` — removed false 100% coverage claims (2 spots)
+- `docs/ARCHITECTURE.md` — Azure deployment + CI/CD rewrite; auth section updated (PAT/2FA/SSO)
+- `docs/features/api-reference.md` — auth line corrected
+- `apps/sidecar/src/**` — console→logger (verified; bulk of this was pre-existing working-tree work)
+
+### Verification
+- `prisma migrate deploy` on a fresh DB → 31 tables / 12 user cols; `migrate diff` vs schema → no difference
+- `pnpm --filter @openlinear/api test` → 18 files passed, 149 tests, exit 0 (was 14 failing)
+- `@openlinear/api`, `@openlinear/sidecar`, `@openlinear/db` typecheck → all exit 0
+- `db:generate` → clean
+
+### Issues encountered / notes
+- Prod Neon DB already has all 31 tables + TOTP columns (someone ran `db:push` against it directly), but its `_prisma_migrations` history is the same incomplete set. The new idempotent reconcile migration is safe to mark-applied or run there; recommend `prisma migrate resolve --applied 20260531000000_reconcile_schema_drift` on prod so history matches without re-running DDL.
+- Both CI workflows (`deploy.yml` legacy/disabled, `deploy-azure.yml` active) use `db:push` for their ephemeral test DB, which is why CI didn't catch the drift. Consider switching CI to `migrate deploy` so the migration path is continuously exercised.
+- Pre-existing uncommitted working-tree changes (chat attachments, transcribe Cartesia URL, opencode init-guard, etc.) were left untouched per protocol.
+
+### Next steps / blockers (follow-ups — NOT done this session)
+- **Sidecar/execution-core test coverage: 0 tests.** The execution engine (clones repos, force-pushes branches, creates PRs) and `packages/execution-core` have no automated tests. Highest-value remaining gap. Add Vitest coverage for lifecycle, git, worktree, batch orchestrator/completion, and the pure `event-stream-processor`.
+- **Multi-tenant OpenCode isolation** (`docs/limitations.md`): cloud deployment still shares one OpenCode process/auth store across users, gated only by `OPENLINEAR_ALLOW_SHARED_OPENCODE=1`. Real per-user isolation (per-user `XDG_DATA_HOME` + process pool) still pending.
+- Consider making CI run `prisma migrate deploy` against a fresh DB (in addition to / instead of `db:push`) to prevent future drift.
+
+---
+
 ## [2026-05-26] — Fix sidecar startup crash (missing openid-client + otpauth + ALLOW_SHARED_OPENCODE)
 
 **Status:** Done
@@ -1552,3 +1592,26 @@ The sidecar was likely not running when login was attempted (single-tenant guard
 ### Next steps / blockers
 - Test full GitHub OAuth login flow in browser at http://localhost:3000
 - Ensure GitHub OAuth App callback URL includes `http://localhost:3001/api/auth/github/callback`
+
+---
+
+## [2026-05-27] — Full codebase review, index, and CODEBASE_INDEX.md
+
+**Status:** Done
+**Agent:** Sisyphus (OpenCode)
+
+### What was done
+- Ran 4 parallel `kiroExplore` background agents exploring API, Frontend, Sidecar, and MCP/DB layers
+- Read ~40+ key source files directly across all layers
+- Cross-referenced results with direct reads to verify accuracy
+- Created comprehensive `docs/CODEBASE_INDEX.md` (651 lines, 12 sections)
+
+### Files changed
+- `docs/CODEBASE_INDEX.md` — New. Complete index covering: architecture overview, API (28 routes, 5 middleware, 12 services, 34 chat tools, auth, error handling, rate limiting, tests), Sidecar execution engine (17 execution files, 5 batch files, safeguards, execution flow), Frontend (15 pages, 27 component dirs, state management, API client, SSE, keyboard shortcuts), Desktop Tauri (4 Rust files, sidecar manager, deeplink), MCP Server (8 tools, stateless Worker, API integration), Database (25+ models, 13 enums, Prisma patterns, migrations), shared packages, CI/CD, patterns/conventions, production URLs, and key commands
+
+### Issues encountered
+- 3 of 4 background sessions returned no output (likely expired); recovered by reading files directly
+- Background sessions were "idle" but had full results in the final turn — retrieve messages worked on resumption
+
+### Next steps / blockers
+- None. Codebase fully indexed.