Merge pull request #84 from ichinya/feat/codex-session-scan-performance

feat(sessions): enhance session file handling and optimize limit snapshot

Author: ichinya

.prettierignore

@@ -6,5 +6,6 @@ data/
 *.sqlite
 .ai-factory/
 docs-html/
+*SFConflict*
 playwright-report/
 test-results/

AGENTS.md

@@ -14,7 +14,7 @@ Autonomous task management system with Kanban board and AI subagents. Tasks flow
 - **Runtime Abstraction:** `@aif/runtime` workspace (runtime/provider contracts + registry)
 - **Database:** SQLite (better-sqlite3 + drizzle-orm)
 - **Frontend:** React 19 + Vite + TailwindCSS 4
-- **Runtime:** Pluggable adapter system (`@aif/runtime`) — built-in Claude (Agent SDK) + Codex (CLI/API) + OpenRouter (API) adapters
+- **Runtime:** Pluggable adapter system (`@aif/runtime`) — built-in Claude (Agent SDK) + Codex (SDK/CLI/API) + OpenRouter (API) adapters
 - **Agent:** Runtime-neutral coordinator + node-cron
 - **Testing:** Vitest
 
@@ -60,7 +60,7 @@ packages/
 │   └── src/
 │       ├── index.ts         # Server entry point
 │       ├── routes/          # tasks.ts, projects.ts, chat.ts, runtimeProfiles.ts
-│       ├── services/        # runtime.ts, fastFix.ts, roadmapGeneration.ts
+│       ├── services/        # runtime.ts, codexIndex.ts, fastFix.ts, roadmapGeneration.ts
 │       ├── middleware/      # logger.ts, rateLimit.ts, zodValidator.ts
 │       ├── schemas.ts       # Zod request validation
 │       └── ws.ts            # WebSocket handler

docs/api.md

@@ -341,6 +341,7 @@ Used by API/agent services to trigger project-scoped WebSocket broadcasts withou
 ## Runtime Profiles
 
 Runtime profiles carry non-secret transport/model config plus the latest persisted runtime-limit snapshot used by API, agent, and UI surfaces.
+For local Codex runtimes (`runtimeId=codex` with `sdk`/`cli` transport), `/runtime-profiles` and `/runtime-profiles/effective/*` now read limit overlays from the SQLite Codex index (`codex_limit_heads`) maintained by the background API indexer. Request handlers do not perform direct `~/.codex/sessions` scans.
 
 ### List Runtime Profiles
 
@@ -367,6 +368,7 @@ GET /runtime-profiles/effective/chat/:projectId
 ```
 
 Both responses include the resolved `profile` object (or `null`) plus source metadata. When a profile is present, its payload includes `runtimeLimitSnapshot` and `runtimeLimitUpdatedAt`.
+If no indexed Codex head is available for the resolved account/project scope, the response falls back to the persisted profile snapshot.
 
 ### Runtime Limit Snapshot Shape
 
@@ -672,6 +674,7 @@ GET /runtime-profiles
 
 `scope=project` requires `projectId`. `scope=global` returns only reusable profiles (`projectId = null`).
 `scope=visible` is the default when omitted.
+For local Codex profiles, this endpoint overlays the response from indexed Codex limit heads in SQLite instead of scanning `~/.codex/sessions` during request handling.
 
 ### Effective Runtime Resolution
 
@@ -874,6 +877,7 @@ DELETE /chat/sessions/:id
 ```
 
 Chat sessions persist the runtime profile chosen when the session starts. This keeps older conversations tied to the runtime they were created with even if the project's current default changes later.
+For local Codex runtimes, session discovery uses the indexed `codex_sessions` read-model. Session detail/message reads resolve `sessionId -> filePath` from the same index before compatibility fallback to runtime-adapter lookups.
 
 `POST` and `PUT` accept `runtimeProfileId` as an optional field. The value must be either a global profile or one owned by the same project.
 

docs/architecture.md

@@ -88,6 +88,7 @@ Runtime-limit state is normalized once in `@aif/runtime` and then persisted in S
 - adapters translate provider-specific quota signals into a shared `runtimeLimitSnapshot` contract;
 - `runtime_profiles.runtime_limit_snapshot_json` stores the latest authoritative profile-level state;
 - `tasks.runtime_limit_snapshot_json` stores a task-level copy when work is blocked by quota pressure or hard exhaustion.
+- API runs a background Codex indexer that reconciles `~/.codex/sessions` into SQLite read-model tables (`codex_sessions`, `codex_limit_heads`, `codex_limit_history`, `codex_index_cursors`) so hot endpoints (`/chat/sessions`, `/runtime-profiles`) use DB reads instead of request-path filesystem scans.
 
 The source is explicit in the snapshot (`provider_api`, `sdk_event`, `api_headers`, `turn_usage`) so upper layers do not need adapter-specific branching.
 
@@ -290,6 +291,9 @@ Key tables:
 - **runtime_profiles** — project-scoped or global runtime/provider profiles with non-secret transport/model config plus authoritative runtime-limit state (`runtime_limit_snapshot_json`, `runtime_limit_updated_at`)
 - **projects** — project metadata plus default runtime profile ids for tasks and chat
 - **chat_sessions / chat_messages** — persisted chat state with runtime profile/session linkage
+- **codex_sessions** — indexed Codex session metadata keyed by runtime session id and source file state
+- **codex_limit_heads / codex_limit_history** — latest and recent normalized Codex limit snapshots keyed by account fingerprint/project scope/limit id
+- **codex_index_cursors** — per-indexer progress/watermark state for incremental reconcile
 - **task_comments** — human/agent comments with optional attachments
 
 ### Indexes
@@ -303,6 +307,9 @@ Runtime index bootstrap creates the following indexes via `CREATE INDEX IF NOT E
 - `idx_tasks_project_status` — composite for ordered task-list queries
 - `idx_task_comments_task_id` — comment lookups by task
 - `idx_tasks_locked` — parallel execution: find unlocked or stale-locked tasks
+- `idx_codex_sessions_project_root_updated` / `idx_codex_sessions_file_path` — local Codex session listing and session-id/file-path lookup
+- `idx_codex_limit_heads_lookup` — account/project/limit scoped head overlay queries
+- `idx_codex_limit_history_head` / `idx_codex_limit_history_account` — bounded recent limit history by head and account scope
 
 ## See Also