@cleocode/cleo 2026.4.10 → 2026.4.11

package/dist/dispatch/engines/session-engine.js

@@ -0,0 +1,960 @@
+/**
+ * Session Engine — thin wrapper layer.
+ *
+ * Delegates all business logic to src/core/sessions/ and src/core/task-work/.
+ * Each function catches errors from core and wraps them into EngineResult.
+ *
+ * @task T4782
+ * @epic T4654
+ */
+import { getExitCodeName } from '@cleocode/contracts';
+// ... existing imports ...
+import { archiveSessions, CleoError, cleanupSessions, computeBriefing, computeDebrief, computeHandoff, currentTask, findSessions, generateSessionId, getAccessor, getContextDrift, getDecisionLog, getLastHandoff, getSessionHistory, getSessionStats, getTaskHistory, injectContext, paginate, parseScope, persistHandoff, recordAssumption, recordDecision, showSession, startTask, stopTask, suspendSession, switchSession, } from '@cleocode/core/internal';
+import { engineError } from './_error.js';
+/**
+ * Get current session status.
+ *
+ * @remarks
+ * Returns whether there is an active session, along with the session record
+ * and current task work state if available.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @returns EngineResult with active session flag, session record, and task work state
+ *
+ * @example
+ * ```typescript
+ * const result = await sessionStatus('/project');
+ * if (result.success && result.data.hasActiveSession) {
+ *   console.log(result.data.session?.id);
+ * }
+ * ```
+ *
+ * @task T4782
+ */
+export async function sessionStatus(projectRoot) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const focusState = await accessor.getMetaValue('focus_state');
+        const sessions = await accessor.loadSessions();
+        const active = sessions.find((s) => s.status === 'active');
+        return {
+            success: true,
+            data: {
+                hasActiveSession: !!active,
+                session: active || null,
+                taskWork: focusState || null,
+            },
+        };
+    }
+    catch {
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/** Default limit for sessionList when none is provided. @task T5121 */
+const SESSION_LIST_DEFAULT_LIMIT = 10;
+/**
+ * List sessions with budget enforcement.
+ *
+ * When a limit is applied (explicit or default), the response includes
+ * `_meta.truncated` and `_meta.total` so agents know the result set
+ * was capped.
+ *
+ * @remarks
+ * Defaults to 10 results when no explicit limit is provided to protect
+ * agent context budgets. Use offset for pagination.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param params - Optional filter and pagination parameters
+ * @returns EngineResult with sessions array, total, filtered count, and truncation metadata
+ *
+ * @example
+ * ```typescript
+ * const result = await sessionList('/project', { active: true, limit: 5 });
+ * ```
+ *
+ * @task T4782
+ * @task T5120 - budget enforcement metadata
+ * @task T5121 - default limit=10
+ */
+export async function sessionList(projectRoot, params) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const sessions = await accessor.loadSessions();
+        let result = sessions;
+        if (params?.status) {
+            result = result.filter((s) => s.status === params.status);
+        }
+        else if (params?.active === true) {
+            result = result.filter((s) => s.status === 'active');
+        }
+        else if (params?.active === false) {
+            result = result.filter((s) => s.status !== 'active');
+        }
+        const total = sessions.length;
+        const filtered = result.length;
+        const limit = params?.limit && params.limit > 0 ? params.limit : SESSION_LIST_DEFAULT_LIMIT;
+        const offset = typeof params?.offset === 'number' && params.offset > 0 ? params.offset : 0;
+        const pageResult = paginate(result, limit, offset);
+        const truncated = filtered !== pageResult.items.length || offset > 0;
+        return {
+            success: true,
+            data: {
+                sessions: pageResult.items,
+                total,
+                filtered,
+                _meta: { truncated, total: filtered },
+            },
+            page: pageResult.page,
+        };
+    }
+    catch {
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * Lightweight session discovery -- returns minimal session records.
+ *
+ * @remarks
+ * Optimized for low context cost. Returns only essential fields (ID, status,
+ * scope, timestamps) without full session details.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param params - Optional search parameters
+ * @returns EngineResult with array of minimal session records
+ *
+ * @example
+ * ```typescript
+ * const result = await sessionFind('/project', { status: 'active' });
+ * ```
+ *
+ * @task T5119
+ */
+export async function sessionFind(projectRoot, params) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const result = await findSessions(accessor, params);
+        return { success: true, data: result };
+    }
+    catch {
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * Show a specific session by ID.
+ *
+ * @remarks
+ * Returns the full session record including scope, status, timestamps,
+ * and associated task data.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param sessionId - Session identifier to look up
+ * @returns EngineResult with the full Session record
+ *
+ * @example
+ * ```typescript
+ * const result = await sessionShow('/project', 'ses_20260401_abc123');
+ * ```
+ *
+ * @task T4782
+ */
+export async function sessionShow(projectRoot, sessionId) {
+    try {
+        const result = await showSession(projectRoot, sessionId);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err.message;
+        const code = message.includes('not found') ? 'E_NOT_FOUND' : 'E_NOT_INITIALIZED';
+        return engineError(code, message);
+    }
+}
+/**
+ * Get current task being worked on.
+ * Delegates to core/task-work/currentTask.
+ * @task T4782
+ */
+export async function taskCurrentGet(projectRoot) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const result = await currentTask(undefined, accessor);
+        return {
+            success: true,
+            data: {
+                currentTask: result.currentTask,
+                currentPhase: result.currentPhase,
+            },
+        };
+    }
+    catch {
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * Start working on a specific task.
+ * Delegates to core/task-work/startTask.
+ * @task T4782
+ */
+export async function taskStart(projectRoot, taskId) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const result = await startTask(taskId, undefined, accessor);
+        return {
+            success: true,
+            data: { taskId: result.taskId, previousTask: result.previousTask },
+        };
+    }
+    catch (err) {
+        if (err instanceof CleoError) {
+            const stringCode = `E_${getExitCodeName(err.code)}`;
+            return engineError(stringCode, err.message, {
+                ...(err.fix && { fix: err.fix }),
+            });
+        }
+        const message = err.message;
+        const code = message.includes('not found') ? 'E_NOT_FOUND' : 'E_NOT_INITIALIZED';
+        return engineError(code, message);
+    }
+}
+/**
+ * Stop working on the current task.
+ * Delegates to core/task-work/stopTask.
+ * @task T4782
+ */
+export async function taskStop(projectRoot) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const result = await stopTask(undefined, accessor);
+        return {
+            success: true,
+            data: { cleared: true, previousTask: result.previousTask },
+        };
+    }
+    catch {
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * Get task work history from session notes.
+ * @task T5323
+ */
+export async function taskWorkHistory(projectRoot) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const history = await getTaskHistory(undefined, accessor);
+        return {
+            success: true,
+            data: { history, count: history.length },
+        };
+    }
+    catch {
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * Start a new session.
+ * Note: This function has engine-specific logic for task file focus management
+ * and session store updates, so it remains in the engine layer.
+ * @task T4782
+ */
+export async function sessionStart(projectRoot, params) {
+    try {
+        let accessor = await getAccessor(projectRoot);
+        // Validate scope BEFORE auto-ending active session (prevents data loss on invalid input)
+        let scope;
+        try {
+            scope = parseScope(params.scope);
+        }
+        catch (err) {
+            return engineError('E_INVALID_INPUT', err instanceof Error ? err.message : 'Invalid scope');
+        }
+        // For non-global scopes, verify root task exists before auto-ending
+        if (scope.type !== 'global') {
+            const rootTask = await accessor.loadSingleTask(scope.rootTaskId);
+            if (!rootTask) {
+                return engineError('E_NOT_FOUND', `Root task '${scope.rootTaskId}' not found`);
+            }
+        }
+        // Auto-end any active session before starting a new one
+        const existingActive = await accessor.getActiveSession();
+        if (existingActive) {
+            await sessionEnd(projectRoot);
+            // Reload after auto-end
+            accessor = await getAccessor(projectRoot);
+        }
+        const now = new Date().toISOString();
+        const sessionId = generateSessionId();
+        // T4959: Chain linking — find most recent ended session for same scope
+        let previousSessionId = null;
+        {
+            const sessions = await accessor.loadSessions();
+            const sameScope = sessions
+                .filter((s) => s.status === 'ended' &&
+                s.endedAt &&
+                s.scope?.type === scope.type &&
+                (scope.type === 'global' || s.scope?.rootTaskId === scope.rootTaskId))
+                .sort((a, b) => new Date(b.endedAt).getTime() - new Date(a.endedAt).getTime());
+            if (sameScope.length > 0) {
+                previousSessionId = sameScope[0].id;
+            }
+        }
+        // Resolve agent identifier from params or env
+        const agentIdentifier = params.agentIdentifier ??
+            process.env.CLEO_AGENT_ID ??
+            null;
+        const rootTaskId = scope.type !== 'global' ? scope.rootTaskId : undefined;
+        const startingTaskId = params.startTask || (params.autoStart && rootTaskId ? rootTaskId : null);
+        const newSession = {
+            id: sessionId,
+            status: 'active',
+            name: params.name || `session-${sessionId}`,
+            scope: scope.type === 'global'
+                ? { type: 'global' }
+                : { type: scope.type, rootTaskId: scope.rootTaskId, includeDescendants: true },
+            taskWork: {
+                taskId: startingTaskId,
+                setAt: now,
+            },
+            startedAt: now,
+            resumeCount: 0,
+            ...(params.grade ? { gradeMode: true } : {}),
+            stats: {
+                tasksCompleted: 0,
+                tasksCreated: 0,
+                tasksUpdated: 0,
+                focusChanges: 0,
+                totalActiveMinutes: 0,
+                suspendCount: 0,
+            },
+        };
+        // Update focus state via metadata
+        const existingFocus = (await accessor.getMetaValue('focus_state')) ?? {
+            currentTask: null,
+            currentPhase: null,
+            blockedUntil: null,
+            sessionNote: null,
+            sessionNotes: [],
+            nextAction: null,
+            primarySession: null,
+        };
+        const startingTask = params.startTask;
+        if (startingTask) {
+            existingFocus.currentTask = startingTask;
+        }
+        else if (params.autoStart && rootTaskId) {
+            existingFocus.currentTask = rootTaskId;
+        }
+        await accessor.setMetaValue('focus_state', existingFocus);
+        // Update file meta (activeSession no longer stored — session.status is source of truth)
+        const currentMeta = (await accessor.getMetaValue('file_meta')) ?? {};
+        currentMeta.lastSessionId = sessionId;
+        currentMeta.generation = (currentMeta.generation || 0) + 1;
+        await accessor.setMetaValue('file_meta', currentMeta);
+        // T4959: Set chain fields on new session
+        if (previousSessionId) {
+            newSession.previousSessionId = previousSessionId;
+        }
+        if (agentIdentifier) {
+            newSession.agentIdentifier = agentIdentifier;
+        }
+        // Insert new session FIRST — FK constraints require the target row to exist
+        // before predecessor.nextSessionId can reference it.
+        await accessor.upsertSingleSession(newSession);
+        // Now update predecessor's nextSessionId (new session row exists for FK)
+        if (previousSessionId) {
+            const sessions = await accessor.loadSessions();
+            const pred = sessions.find((s) => s.id === previousSessionId);
+            if (pred) {
+                pred.nextSessionId = sessionId;
+                await accessor.upsertSingleSession(pred);
+            }
+        }
+        // Enable grade mode: set env vars so audit middleware logs queries too
+        if (params.grade) {
+            process.env.CLEO_SESSION_GRADE = 'true';
+            process.env.CLEO_SESSION_ID = sessionId;
+            process.env.CLEO_SESSION_GRADE_ID = sessionId;
+        }
+        // T4959: Auto-briefing — enrich response with briefing + predecessor debrief
+        let briefing = null;
+        let previousDebrief = null;
+        try {
+            briefing = await computeBriefing(projectRoot, { scope: params.scope });
+        }
+        catch {
+            // Best-effort — briefing failure should not fail session start
+        }
+        // 5B: Load predecessor debrief/handoff and mark consumed
+        let previousHandoff = null;
+        if (previousSessionId) {
+            try {
+                const sessions2 = await accessor.loadSessions();
+                const pred = sessions2.find((s) => s.id === previousSessionId);
+                if (pred) {
+                    // Try debriefJson first (rich data), then handoffJson (basic)
+                    if (pred.debriefJson) {
+                        previousDebrief = JSON.parse(pred.debriefJson);
+                    }
+                    else if (pred.handoffJson) {
+                        previousHandoff = JSON.parse(pred.handoffJson);
+                    }
+                    // Always mark consumed regardless of debrief vs handoff
+                    pred.handoffConsumedAt = new Date().toISOString();
+                    pred.handoffConsumedBy = sessionId;
+                    await accessor.upsertSingleSession(pred);
+                }
+            }
+            catch {
+                // Best-effort
+            }
+        }
+        const enrichedSession = {
+            ...newSession,
+            ...(briefing && { briefing }),
+            ...(previousDebrief && { previousDebrief }),
+            ...(previousHandoff && { previousHandoff }),
+        };
+        return { success: true, data: enrichedSession };
+    }
+    catch {
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * End the current session.
+ * Note: This function has engine-specific logic for task file focus management
+ * and session store management, so it remains in the engine layer.
+ * @task T4782
+ * @task T140 @epic T134 - Summarization wiring
+ */
+export async function sessionEnd(projectRoot, notes, params) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const activeSession = await accessor.getActiveSession();
+        const sessionId = activeSession?.id;
+        if (!sessionId) {
+            return engineError('E_SESSION_NOT_FOUND', 'No active session to end', {
+                fix: 'Start a session first with: session start --scope <scope> --name <name>',
+            });
+        }
+        const now = new Date().toISOString();
+        // NOTE: Do NOT clear grade mode env vars here — gradeSession() needs them
+        // to query audit entries after the session ends. The caller (admin.grade handler)
+        // is responsible for cleanup after evaluation completes.
+        // Clear focus
+        const focusEnd = await accessor.getMetaValue('focus_state');
+        if (focusEnd) {
+            focusEnd.currentTask = null;
+            if (notes) {
+                if (!focusEnd.sessionNotes)
+                    focusEnd.sessionNotes = [];
+                focusEnd.sessionNotes.push({ timestamp: now, note: notes });
+            }
+            await accessor.setMetaValue('focus_state', focusEnd);
+        }
+        // Bump file_meta generation (activeSession no longer stored here)
+        const fileMetaEnd = await accessor.getMetaValue('file_meta');
+        if (fileMetaEnd) {
+            fileMetaEnd.generation = (fileMetaEnd.generation || 0) + 1;
+            await accessor.setMetaValue('file_meta', fileMetaEnd);
+        }
+        // Update session record — status is the source of truth
+        if (sessionId !== 'default') {
+            activeSession.status = 'ended';
+            activeSession.endedAt = now;
+            await accessor.upsertSingleSession(activeSession);
+        }
+        // T140: Build summarization prompt and ingest structured summary if provided
+        let memoryPrompt;
+        try {
+            const { loadConfig } = await import('@cleocode/core/internal');
+            const config = await loadConfig(projectRoot);
+            if (config.brain?.summarization?.enabled) {
+                // Fetch the debrief if available to build a summarization prompt
+                const sessions = await accessor.loadSessions();
+                const endedSession = sessions.find((s) => s.id === sessionId);
+                if (endedSession?.debriefJson) {
+                    try {
+                        const debrief = JSON.parse(endedSession.debriefJson);
+                        const { buildSummarizationPrompt } = await import('@cleocode/core/internal');
+                        const prompt = buildSummarizationPrompt(sessionId, debrief);
+                        if (prompt)
+                            memoryPrompt = prompt;
+                    }
+                    catch {
+                        // Best-effort
+                    }
+                }
+            }
+            // Ingest structured summary if provided by caller (e.g. from CLI --summary flag)
+            if (params?.sessionSummary) {
+                const { ingestStructuredSummary } = await import('@cleocode/core/internal');
+                await ingestStructuredSummary(projectRoot, sessionId, params.sessionSummary);
+            }
+        }
+        catch {
+            // Summarization must never block session end
+        }
+        return {
+            success: true,
+            data: { sessionId, ended: true, ...(memoryPrompt && { memoryPrompt }) },
+        };
+    }
+    catch {
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * Resume an ended or suspended session.
+ * Note: This function has engine-specific logic for task file focus sync,
+ * so it remains in the engine layer.
+ * @task T4782
+ */
+export async function sessionResume(projectRoot, sessionId) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        // Look up sessions from the store.
+        const sessions = await accessor.loadSessions();
+        // Look in sessions list
+        const session = sessions.find((s) => s.id === sessionId);
+        if (!session) {
+            return engineError('E_NOT_FOUND', `Session '${sessionId}' not found`);
+        }
+        if (session.status === 'active') {
+            return { success: true, data: session };
+        }
+        if (session.status === 'archived') {
+            return engineError('E_INVALID_INPUT', `Session '${sessionId}' is archived and cannot be resumed`);
+        }
+        session.status = 'active';
+        session.endedAt = undefined;
+        session.resumeCount = (session.resumeCount || 0) + 1;
+        // Bump file_meta generation (activeSession no longer stored — status is source of truth)
+        const resumeMeta = (await accessor.getMetaValue('file_meta')) ?? {};
+        resumeMeta.generation = (resumeMeta.generation || 0) + 1;
+        await accessor.setMetaValue('file_meta', resumeMeta);
+        // Restore focus from session task work
+        if (session.taskWork?.taskId) {
+            const resumeFocus = await accessor.getMetaValue('focus_state');
+            if (resumeFocus) {
+                resumeFocus.currentTask = session.taskWork.taskId;
+                await accessor.setMetaValue('focus_state', resumeFocus);
+            }
+        }
+        await accessor.upsertSingleSession(session);
+        // Wave 3B: Enrich resumed session with brain memory context (best-effort)
+        let memoryContext;
+        try {
+            const { getSessionMemoryContext } = await import('@cleocode/core/internal');
+            const scopeType = session.scope?.type;
+            const rootTaskId = session.scope?.rootTaskId;
+            memoryContext = await getSessionMemoryContext(projectRoot, {
+                type: scopeType ?? 'global',
+                rootTaskId,
+                epicId: rootTaskId,
+            });
+        }
+        catch {
+            // Best-effort -- memory context failure should not fail resume
+        }
+        const enrichedSession = {
+            ...session,
+            ...(memoryContext && { memoryContext }),
+        };
+        return { success: true, data: enrichedSession };
+    }
+    catch {
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * Garbage collect old sessions.
+ * @task T4782
+ */
+export async function sessionGc(projectRoot, maxAgeDays = 1) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const sessions = await accessor.loadSessions();
+        const now = Date.now();
+        const maxAgeMs = maxAgeDays * 24 * 60 * 60 * 1000;
+        const thirtyDaysMs = 30 * 24 * 60 * 60 * 1000;
+        const orphaned = [];
+        const removed = [];
+        // Mark stale active sessions as orphaned
+        for (const session of sessions) {
+            if (session.status === 'active') {
+                const lastActive = new Date(session.endedAt || session.startedAt).getTime();
+                if (now - lastActive > maxAgeMs) {
+                    session.status = 'ended';
+                    session.endedAt = new Date().toISOString();
+                    orphaned.push(session.id);
+                    await accessor.upsertSingleSession(session);
+                }
+            }
+        }
+        // Remove very old ended sessions
+        for (const s of sessions) {
+            if (s.status === 'active')
+                continue;
+            const endedAt = s.endedAt ? new Date(s.endedAt).getTime() : new Date(s.startedAt).getTime();
+            if (now - endedAt > thirtyDaysMs) {
+                removed.push(s.id);
+                await accessor.removeSingleSession(s.id);
+            }
+        }
+        return { success: true, data: { orphaned, removed } };
+    }
+    catch {
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * Suspend an active session.
+ * @task T4782
+ */
+export async function sessionSuspend(projectRoot, sessionId, reason) {
+    try {
+        const result = await suspendSession(projectRoot, sessionId, reason);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err.message;
+        const code = message.includes('not found')
+            ? 'E_NOT_FOUND'
+            : message.includes('not active')
+                ? 'E_INVALID_STATE'
+                : 'E_NOT_INITIALIZED';
+        return engineError(code, message);
+    }
+}
+/**
+ * List session history with focus changes and completed tasks.
+ * @task T4782
+ */
+export async function sessionHistory(projectRoot, params) {
+    try {
+        const result = await getSessionHistory(projectRoot, params);
+        return { success: true, data: result };
+    }
+    catch {
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * Remove orphaned sessions and clean up stale data.
+ * @task T4782
+ */
+export async function sessionCleanup(projectRoot) {
+    try {
+        const result = await cleanupSessions(projectRoot);
+        return { success: true, data: result };
+    }
+    catch {
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * Record a decision to the audit trail.
+ * @task T4782
+ */
+export async function sessionRecordDecision(projectRoot, params) {
+    try {
+        const result = await recordDecision(projectRoot, params);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err.message;
+        return engineError('E_INVALID_INPUT', message);
+    }
+}
+/**
+ * Read the decision log, optionally filtered by sessionId and/or taskId.
+ * @task T4782
+ */
+export async function sessionDecisionLog(projectRoot, params) {
+    try {
+        const result = await getDecisionLog(projectRoot, params);
+        return { success: true, data: result };
+    }
+    catch {
+        return { success: true, data: [] };
+    }
+}
+/**
+ * Compute context drift score for the current session.
+ * @task T4782
+ */
+export async function sessionContextDrift(projectRoot, params) {
+    try {
+        const result = await getContextDrift(projectRoot, params);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err.message;
+        const code = message.includes('not found') ? 'E_NOT_FOUND' : 'E_NOT_INITIALIZED';
+        return engineError(code, message);
+    }
+}
+/**
+ * Record an assumption made during a session.
+ * @task T4782
+ */
+export async function sessionRecordAssumption(projectRoot, params) {
+    try {
+        const result = await recordAssumption(projectRoot, params);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err.message;
+        const code = message.includes('required') || message.includes('must be')
+            ? 'E_INVALID_INPUT'
+            : 'E_NOT_INITIALIZED';
+        return engineError(code, message);
+    }
+}
+/**
+ * Compute session statistics, optionally for a specific session.
+ * @task T4782
+ */
+export async function sessionStats(projectRoot, sessionId) {
+    try {
+        const result = await getSessionStats(projectRoot, sessionId);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err.message;
+        const code = message.includes('not found') ? 'E_NOT_FOUND' : 'E_NOT_INITIALIZED';
+        return engineError(code, message);
+    }
+}
+/**
+ * Switch to a different session.
+ * @task T4782
+ */
+export async function sessionSwitch(projectRoot, sessionId) {
+    try {
+        const result = await switchSession(projectRoot, sessionId);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err.message;
+        const code = message.includes('not found')
+            ? 'E_NOT_FOUND'
+            : message.includes('archived')
+                ? 'E_INVALID_STATE'
+                : 'E_NOT_INITIALIZED';
+        return engineError(code, message);
+    }
+}
+/**
+ * Archive old/ended sessions.
+ * @task T4782
+ */
+export async function sessionArchive(projectRoot, olderThan) {
+    try {
+        const result = await archiveSessions(projectRoot, olderThan);
+        return { success: true, data: result };
+    }
+    catch {
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * Get handoff data for the most recent ended session.
+ * @task T4915, T5123
+ */
+export async function sessionHandoff(projectRoot, scope) {
+    try {
+        const result = await getLastHandoff(projectRoot, scope);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        if (err instanceof CleoError) {
+            const stringCode = `E_${getExitCodeName(err.code)}`;
+            return engineError(stringCode, err.message, {
+                ...(err.fix && { fix: err.fix }),
+            });
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return engineError('E_GENERAL', message);
+    }
+}
+/**
+ * Compute and persist handoff data for a session.
+ * @task T4915
+ */
+export async function sessionComputeHandoff(projectRoot, sessionId, options) {
+    try {
+        const handoff = await computeHandoff(projectRoot, {
+            sessionId,
+            note: options?.note,
+            nextAction: options?.nextAction,
+        });
+        await persistHandoff(projectRoot, sessionId, handoff);
+        return { success: true, data: handoff };
+    }
+    catch (err) {
+        const message = err.message;
+        return engineError(message.includes('not found') ? 'E_NOT_FOUND' : 'E_INTERNAL', message);
+    }
+}
+/**
+ * Compute session briefing - composite view for session start.
+ * Aggregates data from handoff, current focus, next tasks, bugs, blockers, and epics.
+ * @task T4916
+ */
+export async function sessionBriefing(projectRoot, options) {
+    try {
+        const briefing = await computeBriefing(projectRoot, options);
+        return { success: true, data: briefing };
+    }
+    catch (err) {
+        const message = err.message;
+        return engineError(message.includes('not found') ? 'E_NOT_FOUND' : 'E_INTERNAL', message);
+    }
+}
+// =============================================================================
+// RICH DEBRIEF + CHAIN OPERATIONS (T4959)
+// =============================================================================
+/**
+ * Compute and persist rich debrief data for a session.
+ * Persists as both handoffJson (backward compat) and debriefJson (rich data).
+ * @epic T4959
+ */
+export async function sessionComputeDebrief(projectRoot, sessionId, options) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const sessions = await accessor.loadSessions();
+        const session = sessions.find((s) => s.id === sessionId);
+        const debrief = await computeDebrief(projectRoot, {
+            sessionId,
+            note: options?.note,
+            nextAction: options?.nextAction,
+            agentIdentifier: session?.agentIdentifier ?? null,
+            startedAt: session?.startedAt,
+            endedAt: session?.endedAt ?? new Date().toISOString(),
+        });
+        // Persist both handoffJson and debriefJson
+        const { persistHandoff: corePersistHandoff } = await import('@cleocode/core/internal');
+        await corePersistHandoff(projectRoot, sessionId, debrief.handoff);
+        // Persist debriefJson via session update
+        if (session) {
+            session.debriefJson = JSON.stringify(debrief);
+            await accessor.upsertSingleSession(session);
+        }
+        return { success: true, data: debrief };
+    }
+    catch (err) {
+        const message = err.message;
+        return engineError(message.includes('not found') ? 'E_NOT_FOUND' : 'E_INTERNAL', message);
+    }
+}
+/**
+ * Read a session's debrief data.
+ * Falls back to handoff data if no debrief is available.
+ * @epic T4959
+ */
+export async function sessionDebriefShow(projectRoot, sessionId) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const sessions = await accessor.loadSessions();
+        const session = sessions.find((s) => s.id === sessionId);
+        if (!session) {
+            return engineError('E_NOT_FOUND', `Session '${sessionId}' not found`);
+        }
+        // Try debriefJson first
+        if (session.debriefJson) {
+            try {
+                const debrief = JSON.parse(session.debriefJson);
+                return { success: true, data: debrief };
+            }
+            catch {
+                // Fall through to handoff
+            }
+        }
+        // Fall back to handoffJson
+        if (typeof session.handoffJson === 'string') {
+            try {
+                const handoff = JSON.parse(session.handoffJson);
+                return { success: true, data: { handoff, fallback: true } };
+            }
+            catch {
+                // No data available
+            }
+        }
+        return { success: true, data: null };
+    }
+    catch (err) {
+        const message = err.message;
+        return engineError(message.includes('not found') ? 'E_NOT_FOUND' : 'E_INTERNAL', message);
+    }
+}
+/**
+ * Show the session chain for a given session.
+ * Returns ordered list of sessions linked via previousSessionId/nextSessionId.
+ * @epic T4959
+ */
+export async function sessionChainShow(projectRoot, sessionId) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const sessions = await accessor.loadSessions();
+        const sessionMap = new Map(sessions.map((s) => [s.id, s]));
+        const target = sessionMap.get(sessionId);
+        if (!target) {
+            return engineError('E_NOT_FOUND', `Session '${sessionId}' not found`);
+        }
+        // Walk backward to chain start
+        const chain = [sessionId];
+        const visited = new Set([sessionId]);
+        let current = target.previousSessionId;
+        while (current && !visited.has(current)) {
+            chain.unshift(current);
+            visited.add(current);
+            const s = sessionMap.get(current);
+            current = s?.previousSessionId ?? undefined;
+        }
+        // Walk forward from target
+        current = target.nextSessionId;
+        while (current && !visited.has(current)) {
+            chain.push(current);
+            visited.add(current);
+            const s = sessionMap.get(current);
+            current = s?.nextSessionId ?? undefined;
+        }
+        const result = chain.map((id, idx) => {
+            const s = sessionMap.get(id);
+            return {
+                id,
+                status: s?.status ?? 'unknown',
+                startedAt: s?.startedAt ?? '',
+                endedAt: s?.endedAt ?? null,
+                agentIdentifier: s?.agentIdentifier ?? null,
+                position: idx + 1,
+            };
+        });
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err.message;
+        return engineError('E_INTERNAL', message);
+    }
+}
+/**
+ * Inject context protocol content.
+ * @task T5673
+ */
+export function sessionContextInject(protocolType, params, projectRoot) {
+    try {
+        const result = injectContext(protocolType, params, projectRoot);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err.message;
+        const code = message.includes('required')
+            ? 'E_INVALID_INPUT'
+            : message.includes('not found')
+                ? 'E_NOT_FOUND'
+                : 'E_INTERNAL';
+        return engineError(code, message);
+    }
+}
+//# sourceMappingURL=session-engine.js.map