@cleocode/cleo 2026.3.37 → 2026.3.39

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

@@ -1,869 +0,0 @@
-/**
- * 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 { archiveSessions, CleoError, cleanupSessions, computeBriefing, computeDebrief, computeHandoff, currentTask, findSessions, generateSessionId, getContextDrift, getDecisionLog, getLastHandoff, getSessionHistory, getSessionStats, getTaskHistory, injectContext, paginate, parseScope, persistHandoff, recordAssumption, recordDecision, showSession, startTask, stopTask, suspendSession, switchSession, } from '@cleocode/core/internal';
-// ... existing imports ...
-import { getAccessor } from '@cleocode/core/internal';
-import { getExitCodeName } from '@cleocode/contracts';
-import { engineError } from './_error.js';
-/**
- * Get current session status.
- * @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.
- *
- * @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.
- *
- * @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.
- * @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);
-        // Write to sessions store so resume/suspend can find the session.
-        {
-            // T4959: Set chain fields on new session
-            if (previousSessionId) {
-                newSession.previousSessionId = previousSessionId;
-                // Update predecessor's nextSessionId
-                const sessions = await accessor.loadSessions();
-                const pred = sessions.find((s) => s.id === previousSessionId);
-                if (pred) {
-                    pred.nextSessionId = sessionId;
-                    await accessor.upsertSingleSession(pred);
-                }
-            }
-            if (agentIdentifier) {
-                newSession.agentIdentifier = agentIdentifier;
-            }
-            await accessor.upsertSingleSession(newSession);
-        }
-        // 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
- */
-export async function sessionEnd(projectRoot, notes) {
-    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);
-        }
-        return { success: true, data: { sessionId, ended: true } };
-    }
-    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