# 8. State & Edge Cases

## Status Lifecycles

### Session Status

```
idle → active (message sent) → streaming (response in progress) → idle
                                                                 ↘ error → idle
```

No explicit session close. Sessions become inactive when CLI process exits or times out.

### Onboarding Research Status

```
pending → researching → completed
                      ↘ failed (can retry)
```

Stored in `company_profiles.research_status`.

### Execution Status

```
running → completed
        → failed
        → timeout (exceeded timeout_ms)
        → stale (detected as orphaned)
        → cancelled (manual cancellation)
```

Applies to: `execution_history.status`, `executions.status`.

**Stale detection:** Scheduler checks for executions stuck in 'running' beyond their timeout and marks them 'stale'.

### Cloud Mount Health

```
unmounted → mounting → mounted
                     ↘ degraded → remounting → mounted
                                             ↘ degraded (persistent failure)
```

Stored in `cloud_mounts.health_status`.

### Cloud Connection Status

```
pending → authorized (OAuth successful)
        → revoked (user or admin revoked)
```

Stored in `cloud_connections.status`.

### Schedule State

```
enabled (cron active) ↔ disabled (cron paused)
```

`schedules.enabled` is an integer (0/1). Toggle via `/api/scheduler/enable/:name` and `/disable/:name`.

## Edge Cases

### Authentication

| Case | Behavior |
|------|----------|
| JWT_SECRET not set | Falls back to hardcoded dev default (insecure) |
| JWT with deleted user | Token validates but user lookup fails → 401 |
| Concurrent logins | Both sessions valid (no single-session enforcement) |
| Browser data cleared | Session lost, user must re-login. Filesystem sessions survive. |
| Container restart | JWT_SECRET may change (if env-based), invalidating all tokens |

### Chat Sessions

| Case | Behavior |
|------|----------|
| Claude CLI crashes mid-response | WebSocket error event, partial response shown |
| WebSocket disconnect | Client auto-reconnects, new CLI process spawned |
| Very large response | Streamed token-by-token, no size limit enforced |
| Concurrent messages from same user | Each spawns separate CLI process |
| API key invalid or expired | Error surfaced in chat: "Claude is not configured" |
| File system full | CLI write operations fail, error in response |

### File Operations

| Case | Behavior |
|------|----------|
| File exceeds size limit | 413 response, file rejected |
| Path traversal attempt | `safePath()` blocks with error |
| Duplicate filename upload | Overwrites existing file (no versioning) |
| Delete system file (CLAUDE.md) | UI prevents deletion via `isCloudItem()` / `canDeleteFolder()` checks |
| Concurrent file writes | SQLite busy_timeout (10s) handles contention, filesystem has no lock |

### Scheduling

| Case | Behavior |
|------|----------|
| Duplicate execution (same slot) | `UNIQUE(schedule_id, scheduled_for)` constraint prevents |
| Schedule fires while previous still running | New execution starts (no queue, no backpressure) |
| Server restart during execution | Execution stays 'running', eventually marked 'stale' |
| Invalid cron expression | Validation at creation time, rejected with 400 |
| Timezone edge cases | Handled by `cron-parser` with timezone support |
| NULL cron_expression | On-demand task only, never auto-fires |

### Cloud Drives

| Case | Behavior |
|------|----------|
| OAuth token expired | Automatic refresh via stored refresh_token |
| Refresh token revoked | Connection marked 'revoked', manual re-auth required |
| rclone process dies | Mount health → 'degraded', auto-remount attempted |
| Network timeout | `RCLONE_RC_TIMEOUT_MS` (default 60s), error returned |
| Large file download | Streamed, no memory buffering |
| Concurrent mount operations | rclone handles internally |

### Database

| Case | Behavior |
|------|----------|
| Database corruption | `PRAGMA integrity_check` on startup, warn in logs |
| Concurrent writes | `busy_timeout = 10000` waits up to 10s for lock |
| Database file missing | Auto-created with full schema from init.sql |
| Migration failure | Error logged, server may start in degraded state |
| `RESET_DATABASE=true` | Full schema rebuild (destroys all data) |

### Admin Operations

| Case | Behavior |
|------|----------|
| Delete only admin user | TBD -- no protection against this currently |
| Delete user with active sessions | CASCADE deletes session records, CLI process orphaned |
| Change own admin status | TBD -- UI may not prevent self-demotion |

## Empty States

| Screen | Empty State |
|--------|------------|
| Chat | Welcome message with suggested prompts |
| File Tree | "No files" with upload button CTA |
| Skills | Empty list with "Create skill" button |
| Schedules | Empty list with "Create schedule" button |
| Meetings | No active meeting indicator |
| Git | "No repository" or "No changes" |
| Analytics | "No data" with refresh button |
| Users (admin) | First user always exists |

## Loading States

| Screen | Loading Pattern |
|--------|----------------|
| Chat response | Token-by-token streaming, animated dots |
| File tree | Skeleton loader |
| Skill list | Spinner |
| Schedule list | Spinner |
| Analytics reports | Section-by-section loading |
| Cloud file browsing | Spinner with directory path |
| Onboarding research | Step-by-step progress messages |

## Error States

| Error | User-Facing Message | Recovery |
|-------|-------------------|----------|
| Claude not configured | "Claude is not configured" banner | Setup form |
| API key invalid | "Invalid API key" in chat | Reconfigure in settings |
| Database error | 500 error | Restart container |
| File upload too large | "File exceeds maximum size" | Reduce file size |
| Network error | "Connection lost" | Auto-reconnect attempt |
| Permission denied (non-admin) | 403 response | Contact admin |
| WebSocket failure | "Reconnecting..." banner | Auto-retry |

## Race Conditions

| Scenario | Mitigation |
|----------|-----------|
| Two users editing CLAUDE.md | Last write wins (no locking) |
| Schedule fires during server shutdown | Execution stays 'running', marked 'stale' on restart |
| Multiple file uploads to same path | Last write wins (filesystem) |
| Concurrent API key validation | bcrypt is thread-safe, no issue |
| Stats refresh triggered while running | `stats_refresh_log` status check prevents duplicate |
| OAuth callback arrives after timeout | Connection stays 'pending' until successful callback |

## Timezone Handling

- **Schedules:** Stored timezone per schedule, evaluated by `cron-parser`
- **Timestamps:** All database timestamps are UTC (ISO 8601 strings or `CURRENT_TIMESTAMP`)
- **Display:** Client-side conversion to local timezone
- **Logs:** UTC timestamps in JSONL files