V7 Deployment Guide

Documentation for Sessions

Session Tracking v7.0 - Production Deployment Guide

Pre-Deployment Checklist

1. Prerequisites ✅

2. Environment Setup

# Required environment variables
export MONGO_URI_AGENTS="mongodb://localhost:27017/agents"
export WORKSPACE_ID="editor2"  # or your workspace name

# Optional (defaults shown)
export SESSION_CIRCUIT_BREAKER_THRESHOLD=3
export SESSION_RESET_TIMEOUT=30000
export SESSION_OPERATION_TIMEOUT=5000

3. Pre-Migration Validation

# Validate current session state (v6.0)
node tools/scripts/database/session-validator.js

# Check MongoDB connectivity
mongosh $MONGO_URI_AGENTS --eval "db.runCommand({ ping: 1 })"

# Verify disk space (need ~100MB per 1000 sessions)
df -h sessions/

Deployment Steps

Phase 1: Dry-Run Migration (No Changes)

Duration: 5 minutes Risk: Zero (read-only)

# 1. Run migration in dry-run mode
node tools/scripts/database/session-migration-v7.ts --dry-run

# Expected output:
# ✅ All sessions validated
# ✅ No errors found
# Total sessions: X

If dry-run fails:

Phase 2: Backup Current State

Duration: 2 minutes Risk: Zero

# Create timestamped backup
BACKUP_DIR="sessions-backup-$(date +%Y%m%d-%H%M%S)"
cp -r sessions/ "$BACKUP_DIR"
tar -czf "$BACKUP_DIR.tar.gz" sessions/
echo "Backup created: $BACKUP_DIR.tar.gz"

# Verify backup
tar -tzf "$BACKUP_DIR.tar.gz" | head -5

Phase 3: Live Migration to MongoDB

Duration: 5-10 minutes for 1000 sessions Risk: Low (transactional with rollback)

# 1. Run migration for specific workspace
node tools/scripts/database/session-migration-v7.ts --workspace=editor2

# Expected output:
# 🚀 Session Migration v7.0
# ========================
# Found 1 workspace(s) to migrate
# 📦 Migrating workspace: editor2
# Found X session(s)
# ✅ Workspace editor2 migrated successfully
#
# 📊 Migration Summary
# ==================================================
# ✓ Migrated: X
# ⏭️  Skipped: 0
# ❌ Failed: 0
# ✅ Migration completed successfully!

# 2. Verify MongoDB data
mongosh $MONGO_URI_AGENTS --eval "
  db.sessions.countDocuments({ workspace: 'editor2' })
"

# 3. Check workspace state
mongosh $MONGO_URI_AGENTS --eval "
  db.workspace_state.findOne({ workspace: 'editor2' })
"

If migration fails:

# Rollback (delete MongoDB data)
node tools/scripts/database/session-migration-v7.ts --workspace=editor2 --rollback

# Restore from backup if needed
rm -rf sessions/
tar -xzf "$BACKUP_DIR.tar.gz"

# Fix issues and retry

Phase 4: Generate JSON Caches

Duration: 2 minutes Risk: Low (creates read-only files)

# Generate JSON cache files from MongoDB
node tools/scripts/database/session-sync-v7.ts

# Expected output:
# 🔄 Session Sync v7.0
# ===================
# Status: ✅ Completed
# Files Written: 2
#   ✓ sessions/sessions-history/editor2/history.json
#   ✓ sessions/active.json

# Verify JSON files
ls -lh sessions/active.json
ls -lh sessions/sessions-history/editor2/history.json

Phase 5: Validation & Health Check

Duration: 2 minutes Risk: Zero (read-only)

# 1. Check sync statistics
node tools/scripts/database/session-sync-v7.ts --stats

# 2. Run cleanup check
node tools/scripts/database/session-cleanup-v7.ts --dry-run

# 3. Test MCP integration (if using MCP)
# Just call preflight() from MCP - it will auto-detect v7

# 4. Verify circuit breaker state
# Should be "closed" (healthy)

Success Criteria:

Post-Deployment Monitoring

Immediate (First Hour)

# Monitor sync status every 5 minutes
watch -n 300 'node tools/scripts/database/session-sync-v7.ts --stats'

# Check for errors in logs
tail -f logs/session-service.log  # if logging configured

# Monitor MongoDB performance
mongosh $MONGO_URI_AGENTS --eval "
  db.currentOp()
"

Ongoing (First Week)

Daily checks:

  1. Sync cache statistics
  2. Check for multiple active sessions
  3. Verify circuit breaker metrics
  4. Monitor MongoDB connection
# Daily health check script
node tools/scripts/database/session-sync-v7.ts --stats
node tools/scripts/database/session-cleanup-v7.ts --dry-run

Rollback Procedures

Scenario 1: Migration Failed (MongoDB Data Corrupt)

Symptoms: Validation errors, duplicate sessions, data inconsistencies

# 1. Stop any running processes using MongoDB
# (kill MCP servers, agents, etc.)

# 2. Delete MongoDB collections
mongosh $MONGO_URI_AGENTS --eval "
  db.sessions.drop();
  db.workspace_state.drop();
  db.session_history_log.drop();
"

# 3. Restore JSON files from backup
rm -rf sessions/
tar -xzf "sessions-backup-YYYYMMDD-HHMMSS.tar.gz"

# 4. Continue using v6.0 (JSON-only)
# No code changes needed - v7 falls back automatically

Recovery Time: 5 minutes

Scenario 2: MongoDB Unavailable (Circuit Breaker Open)

Symptoms: "Circuit breaker open" warnings, "MongoDB not connected"

Action: Nothing! v7.0 automatically falls back to JSON cache.

# System continues working with JSON cache
# Just fix MongoDB connection:

# Check MongoDB is running
systemctl status mongod

# Restart if needed
systemctl restart mongod

# Verify connection
mongosh $MONGO_URI_AGENTS --eval "db.runCommand({ ping: 1 })"

# Circuit breaker will auto-recover in 30 seconds
# Or manually reset:
# (requires running app context - happens automatically)

Recovery Time: Automatic (30 seconds)

Scenario 3: Corrupted JSON Cache

Symptoms: JSON parse errors, "cache is stale" warnings

# Regenerate from MongoDB (source of truth)
node tools/scripts/database/session-sync-v7.ts --force

# Verify files
cat sessions/active.json | jq .
cat sessions/sessions-history/editor2/history.json | jq . | head

# If still corrupted, delete and regenerate
rm sessions/active.json
rm -rf sessions/sessions-history/
node tools/scripts/database/session-sync-v7.ts

Recovery Time: 2 minutes

Scenario 4: Complete System Failure (Nuclear Option)

Symptoms: Everything broken, need to start fresh

# 1. Stop all services

# 2. Delete EVERYTHING
rm -rf sessions/
mongosh $MONGO_URI_AGENTS --eval "
  db.sessions.drop();
  db.workspace_state.drop();
"

# 3. Restore from backup
tar -xzf "sessions-backup-YYYYMMDD-HHMMSS.tar.gz"

# 4. Re-run migration from scratch
node tools/scripts/database/session-migration-v7.ts --workspace=editor2
node tools/scripts/database/session-sync-v7.ts

# 5. Validate
node tools/scripts/database/session-cleanup-v7.ts --dry-run

Recovery Time: 10 minutes

Performance Tuning

MongoDB Indexes (Already Created)

// sessions collection
db.sessions.createIndex({ workspace: 1, sessionNumber: -1 });
db.sessions.createIndex({ sessionID: 1, workspace: 1 }, { unique: true });
db.sessions.createIndex({ status: 1, lastUpdatedAt: -1 });
db.sessions.createIndex({ workspace: 1, status: 1 });

// workspace_state collection
db.workspace_state.createIndex({ workspace: 1 }, { unique: true });

Query Performance Verification

# Check query performance (should be < 100ms)
mongosh $MONGO_URI_AGENTS --eval "
  db.sessions.find({ workspace: 'editor2', status: 'active' }).explain('executionStats')
"

# Look for:
# - executionTimeMillis < 100
# - executionStats.totalDocsExamined ~= nReturned (using index)

Circuit Breaker Tuning

// In your app configuration
sessionService.configure({
  failureThreshold: 5,     // Increase for less sensitive
  resetTimeout: 60000,     // Increase for slower recovery
  successThreshold: 3,     // Increase for stricter recovery
  operationTimeout: 2000,  // Decrease for faster failover
});

Troubleshooting

Issue: "Version conflict" errors during updates

Cause: Optimistic locking detected concurrent update Solution: This is EXPECTED behavior (preventing race conditions). Retry the operation.

// Automatic retry (built-in)
sessionService.updateSession(sessionID, workspace, {
  title: 'Updated',
  version: 1, // Will auto-retry on conflict
});

Issue: "Circuit breaker open" persists

Cause: MongoDB repeatedly failing Solution: Fix MongoDB, then manually reset circuit breaker

# Check MongoDB logs
journalctl -u mongod -n 100

# Fix connection issues
# Circuit breaker will auto-recover in 30 seconds
# Or wait for automatic reset timeout

Issue: Multiple active sessions found

Cause: Race condition during migration or manual edits Solution: Use cleanup tool

node tools/scripts/database/session-cleanup-v7.ts --workspace=editor2
# Keeps most recent, deactivates others

Issue: JSON cache out of sync with MongoDB

Cause: Sync hasn't run, or manual MongoDB edits Solution: Force sync

node tools/scripts/database/session-sync-v7.ts --force

Success Metrics

Measure these after 1 week:

  1. Zero race conditions - No version conflict cascades
  2. < 100ms latency - MongoDB queries fast
  3. > 99% uptime - Circuit breaker rarely open
  4. Zero data loss - All sessions accounted for
  5. < 5 minutes recovery - From any failure scenario

Dashboard (if monitoring configured):

Support & Escalation

Common Issues:

  1. Migration fails → Check validation, fix data, retry
  2. MongoDB down → System auto-falls back to cache (no action needed)
  3. JSON corrupted → Re-sync from MongoDB
  4. Version conflicts → Expected behavior (optimistic locking working)

When to Escalate:

Quick Reference:

# Health check
node tools/scripts/database/session-sync-v7.ts --stats

# Fix issues
node tools/scripts/database/session-cleanup-v7.ts

# Re-sync cache
node tools/scripts/database/session-sync-v7.ts --force

# Nuclear rollback
# (see Scenario 4 above)

Deployment Confidence: 95% Rollback Capability: Complete Downtime Required: Zero (graceful fallback) Data Loss Risk: Zero (transactional + backups)