@cleocode/cleo 2026.4.57 → 2026.4.59

package/dist/dispatch/domains/admin.js

@@ -0,0 +1,791 @@
+/**
+ * Admin Domain Handler (Dispatch Layer)
+ *
+ * Consolidates system domain operations into the canonical "admin"
+ * domain. Handles version, health, config, stats, context, job management,
+ * dashboard, log, sequence, init, backup, restore, migrate, cleanup,
+ * safestop, inject.generate, token, adr, export, import, install.global,
+ * and context.inject.
+ *
+ * All operations delegate to native engine functions from system-engine,
+ * config-engine, and init-engine.
+ *
+ * @epic T4820
+ * @task T5671
+ */
+import { clearTokenUsage, computeHelp, deleteTokenUsage, exportSnapshot, exportTasks, exportTasksPackage, findAdrs, getDefaultSnapshotPath, getLogger, getProjectRoot, importSnapshot, importTasks, importTasksPackage, listAdrs, listTokenUsage, paginate, readSnapshot, recordTokenExchange, showAdr, showTokenUsage, summarizeTokenUsage, syncAdrsToDb, validateAllAdrs, writeSnapshot, } from '@cleocode/core/internal';
+import { backupRestore, configGet, configListPresets, configSet, configSetPreset, getVersion, initProject, sessionContextInject, systemBackup, systemCleanup, systemContext, systemDash, systemDoctor, systemFix, systemHealth, systemHooksMatrix, systemInjectGenerate, systemListBackups, systemLog, systemMigrate, systemPaths, systemRestore, systemRoadmap, systemRuntime, systemSafestop, systemScaffoldHub, systemSequence, systemSmoke, systemStats, } from '../lib/engine.js';
+import { OPERATIONS } from '../registry.js';
+import { errorResult, getListParams, handleErrorResult, unsupportedOp, wrapResult, } from './_base.js';
+import { dispatchMeta } from './_meta.js';
+import { routeByParam } from './_routing.js';
+// ---------------------------------------------------------------------------
+// AdminHandler
+// ---------------------------------------------------------------------------
+export class AdminHandler {
+    // -----------------------------------------------------------------------
+    // Query
+    // -----------------------------------------------------------------------
+    async query(operation, params) {
+        const projectRoot = getProjectRoot();
+        const startTime = Date.now();
+        try {
+            switch (operation) {
+                case 'version': {
+                    const result = await getVersion(projectRoot);
+                    return wrapResult(result, 'query', 'admin', operation, startTime);
+                }
+                case 'health': {
+                    const mode = params?.mode;
+                    if (mode === 'diagnose') {
+                        const result = await systemDoctor(projectRoot);
+                        return wrapResult(result, 'query', 'admin', operation, startTime);
+                    }
+                    const result = await systemHealth(projectRoot, params);
+                    return wrapResult(result, 'query', 'admin', operation, startTime);
+                }
+                case 'config.show': {
+                    const result = await configGet(projectRoot, params?.key);
+                    return wrapResult(result, 'query', 'admin', operation, startTime);
+                }
+                case 'config.presets': {
+                    const result = configListPresets();
+                    return wrapResult(result, 'query', 'admin', operation, startTime);
+                }
+                case 'stats': {
+                    const result = await systemStats(projectRoot, params);
+                    return wrapResult(result, 'query', 'admin', operation, startTime);
+                }
+                case 'context': {
+                    const result = systemContext(projectRoot, params);
+                    return wrapResult(result, 'query', 'admin', operation, startTime);
+                }
+                // T549 Wave 5-A: JIT task context pull — bundles task details + relevant
+                // brain entries + last handoff into a compact (~400-token) snapshot.
+                case 'context.pull': {
+                    const taskId = params?.taskId;
+                    if (!taskId) {
+                        return errorResult('query', 'admin', operation, 'E_INVALID_INPUT', 'taskId is required', startTime);
+                    }
+                    try {
+                        const { getAccessor, getLastHandoff, retrieveWithBudget } = await import('@cleocode/core/internal');
+                        const accessor = await getAccessor(projectRoot);
+                        const task = await accessor.loadSingleTask(taskId);
+                        if (!task) {
+                            return errorResult('query', 'admin', operation, 'E_NOT_FOUND', `Task ${taskId} not found`, startTime);
+                        }
+                        // Build a rich search query from all available task text fields so
+                        // FTS5 has the best chance of matching relevant brain entries. Budget
+                        // raised to 800 tokens (from 400) to accommodate richer result sets.
+                        const queryParts = [task.title, task.description].filter((v) => typeof v === 'string' && v.trim().length > 0);
+                        const query = queryParts.join(' ');
+                        const TOKEN_BUDGET = 800;
+                        const [memoriesResult, lastHandoffResult] = await Promise.all([
+                            retrieveWithBudget(projectRoot, query, TOKEN_BUDGET).catch(() => ({
+                                entries: [],
+                                tokensUsed: 0,
+                                tokensRemaining: TOKEN_BUDGET,
+                                excluded: 0,
+                            })),
+                            getLastHandoff(projectRoot).catch(() => null),
+                        ]);
+                        const topMemories = memoriesResult.entries.slice(0, 5);
+                        const pullResult = {
+                            task: {
+                                id: task.id,
+                                title: task.title,
+                                status: task.status,
+                                acceptance: task.acceptance ?? [],
+                            },
+                            relevantMemory: topMemories.map((e) => ({
+                                id: e.id,
+                                type: e.memoryType ?? 'unknown',
+                                summary: e.title,
+                            })),
+                            lastHandoff: lastHandoffResult?.handoff?.note?.substring(0, 200) ?? null,
+                            meta: {
+                                memoryTokensUsed: memoriesResult.tokensUsed,
+                                memoryEntriesExcluded: memoriesResult.excluded,
+                            },
+                        };
+                        return wrapResult({ success: true, data: pullResult }, 'query', 'admin', operation, startTime);
+                    }
+                    catch (err) {
+                        return handleErrorResult('query', 'admin', operation, err, startTime);
+                    }
+                }
+                case 'runtime': {
+                    const result = await systemRuntime(projectRoot, params);
+                    return wrapResult(result, 'query', 'admin', operation, startTime);
+                }
+                case 'paths': {
+                    const result = await systemPaths(projectRoot);
+                    return wrapResult(result, 'query', 'admin', operation, startTime);
+                }
+                // Merged: job.status + job.list → job via action param (T5615)
+                case 'job': {
+                    return routeByParam(params, 'action', {
+                        status: async () => {
+                            const { getJobManager } = await import('../lib/job-manager-accessor.js');
+                            const manager = getJobManager();
+                            if (!manager) {
+                                return errorResult('query', 'admin', operation, 'E_NOT_AVAILABLE', 'Job manager not available. Background jobs require a running CLEO daemon or long-lived process. Start one with `cleo daemon start` or use `cleo admin health` to check system status.', startTime);
+                            }
+                            const jobId = params?.jobId;
+                            if (!jobId) {
+                                return errorResult('query', 'admin', operation, 'E_INVALID_INPUT', 'jobId is required', startTime);
+                            }
+                            const job = manager.getJob(jobId);
+                            if (!job) {
+                                return errorResult('query', 'admin', operation, 'E_NOT_FOUND', `Job ${jobId} not found`, startTime);
+                            }
+                            return wrapResult({ success: true, data: job }, 'query', 'admin', operation, startTime);
+                        },
+                        list: async () => {
+                            const { getJobManager } = await import('../lib/job-manager-accessor.js');
+                            const mgr = getJobManager();
+                            if (!mgr) {
+                                return errorResult('query', 'admin', operation, 'E_NOT_AVAILABLE', 'Job manager not available. Background jobs require a running CLEO daemon or long-lived process. Start one with `cleo daemon start` or use `cleo admin health` to check system status.', startTime);
+                            }
+                            const statusFilter = params?.status;
+                            const { limit, offset } = getListParams(params);
+                            const allJobs = mgr.listJobs();
+                            const filteredJobs = statusFilter ? mgr.listJobs(statusFilter) : allJobs;
+                            const page = paginate(filteredJobs, limit, offset);
+                            return wrapResult({
+                                success: true,
+                                data: {
+                                    jobs: page.items,
+                                    count: filteredJobs.length,
+                                    total: allJobs.length,
+                                    filtered: filteredJobs.length,
+                                },
+                                page: page.page,
+                            }, 'query', 'admin', operation, startTime);
+                        },
+                    }, 'status');
+                }
+                case 'dash': {
+                    const blockedTasksLimit = typeof params?.blockedTasksLimit === 'number' ? params.blockedTasksLimit : undefined;
+                    const result = await systemDash(projectRoot, { blockedTasksLimit });
+                    return wrapResult(result, 'query', 'admin', operation, startTime);
+                }
+                case 'log': {
+                    const result = await systemLog(projectRoot, params);
+                    return wrapResult(result, 'query', 'admin', operation, startTime);
+                }
+                case 'sequence': {
+                    const action = params?.action;
+                    if (action && action !== 'show' && action !== 'check') {
+                        return errorResult('query', 'admin', operation, 'E_INVALID_INPUT', 'action must be show or check', startTime);
+                    }
+                    const result = await systemSequence(projectRoot, {
+                        action: action,
+                    });
+                    return wrapResult(result, 'query', 'admin', operation, startTime);
+                }
+                case 'help': {
+                    const tier = typeof params?.tier === 'number' ? params.tier : 0;
+                    const verbose = params?.verbose === true;
+                    const helpResult = computeHelp(OPERATIONS, tier, verbose);
+                    return {
+                        meta: dispatchMeta('query', 'admin', operation, startTime),
+                        success: true,
+                        data: helpResult,
+                    };
+                }
+                case 'adr.find': {
+                    const query = params?.query;
+                    if (query) {
+                        const result = await findAdrs(projectRoot, query, {
+                            topics: params?.topics,
+                            keywords: params?.keywords,
+                            status: params?.status,
+                        });
+                        return {
+                            meta: dispatchMeta('query', 'admin', operation, startTime),
+                            success: true,
+                            data: result,
+                        };
+                    }
+                    // No query — list all ADRs
+                    const { limit, offset } = getListParams(params);
+                    const result = await listAdrs(projectRoot, {
+                        status: params?.status,
+                        since: params?.since,
+                        limit,
+                        offset,
+                    });
+                    return {
+                        meta: dispatchMeta('query', 'admin', operation, startTime),
+                        success: true,
+                        data: result,
+                        page: paginate(Array.from({ length: result.filtered }), limit, offset).page,
+                    };
+                }
+                case 'adr.show': {
+                    const adrId = params?.adrId;
+                    if (!adrId) {
+                        return errorResult('query', 'admin', operation, 'E_INVALID_INPUT', 'adrId is required', startTime);
+                    }
+                    const adr = await showAdr(projectRoot, adrId);
+                    if (!adr) {
+                        return errorResult('query', 'admin', operation, 'E_NOT_FOUND', `ADR not found: ${adrId}`, startTime);
+                    }
+                    return {
+                        meta: dispatchMeta('query', 'admin', operation, startTime),
+                        success: true,
+                        data: adr,
+                    };
+                }
+                // Merged: token.summary + token.list + token.show → token via action param (T5615)
+                case 'token': {
+                    return routeByParam(params, 'action', {
+                        summary: async () => {
+                            const result = await summarizeTokenUsage({
+                                provider: params?.provider,
+                                transport: params?.transport,
+                                gateway: params?.gateway,
+                                domain: params?.domain,
+                                operation: params?.operationName,
+                                sessionId: params?.sessionId,
+                                taskId: params?.taskId,
+                                method: params?.method,
+                                confidence: params?.confidence,
+                                requestId: params?.requestId,
+                                since: params?.since,
+                                until: params?.until,
+                            }, projectRoot);
+                            return {
+                                meta: dispatchMeta('query', 'admin', operation, startTime),
+                                success: true,
+                                data: result,
+                            };
+                        },
+                        list: async () => {
+                            const { limit, offset } = getListParams(params);
+                            const result = await listTokenUsage({
+                                provider: params?.provider,
+                                transport: params?.transport,
+                                gateway: params?.gateway,
+                                domain: params?.domain,
+                                operation: params?.operationName,
+                                sessionId: params?.sessionId,
+                                taskId: params?.taskId,
+                                method: params?.method,
+                                confidence: params?.confidence,
+                                requestId: params?.requestId,
+                                since: params?.since,
+                                until: params?.until,
+                                limit,
+                                offset,
+                            }, projectRoot);
+                            return {
+                                meta: dispatchMeta('query', 'admin', operation, startTime),
+                                success: true,
+                                data: {
+                                    records: result.records,
+                                    total: result.total,
+                                    filtered: result.filtered,
+                                },
+                                page: paginate(Array.from({ length: result.filtered }), limit, offset).page,
+                            };
+                        },
+                        show: async () => {
+                            const tokenId = params?.tokenId;
+                            if (!tokenId) {
+                                return errorResult('query', 'admin', operation, 'E_INVALID_INPUT', 'tokenId is required', startTime);
+                            }
+                            const result = await showTokenUsage(tokenId, projectRoot);
+                            if (!result) {
+                                return errorResult('query', 'admin', operation, 'E_NOT_FOUND', `Token usage record not found: ${tokenId}`, startTime);
+                            }
+                            return {
+                                meta: dispatchMeta('query', 'admin', operation, startTime),
+                                success: true,
+                                data: result,
+                            };
+                        },
+                    }, 'summary');
+                }
+                // Merged: export + snapshot.export + export.tasks → export via scope param (T5615)
+                case 'export': {
+                    const scope = params?.scope;
+                    if (scope === 'snapshot') {
+                        const snapshot = await exportSnapshot(projectRoot);
+                        const outputPath = params?.output ?? getDefaultSnapshotPath(projectRoot);
+                        await writeSnapshot(snapshot, outputPath);
+                        return {
+                            meta: dispatchMeta('query', 'admin', operation, startTime),
+                            success: true,
+                            data: {
+                                exported: true,
+                                taskCount: snapshot._meta.taskCount,
+                                outputPath,
+                                checksum: snapshot._meta.checksum,
+                            },
+                        };
+                    }
+                    if (scope === 'tasks') {
+                        const result = await exportTasksPackage({
+                            taskIds: params?.taskIds,
+                            output: params?.output,
+                            subtree: params?.subtree,
+                            filter: params?.filter,
+                            includeDeps: params?.includeDeps,
+                            dryRun: params?.dryRun,
+                            cwd: projectRoot,
+                        });
+                        return {
+                            meta: dispatchMeta('query', 'admin', operation, startTime),
+                            success: true,
+                            data: result,
+                        };
+                    }
+                    // Default: standard export
+                    const result = await exportTasks({
+                        format: params?.format,
+                        output: params?.output,
+                        status: params?.status,
+                        parent: params?.parent,
+                        phase: params?.phase,
+                        cwd: projectRoot,
+                    });
+                    return {
+                        meta: dispatchMeta('query', 'admin', operation, startTime),
+                        success: true,
+                        data: result,
+                    };
+                }
+                case 'backup': {
+                    // Read-only: list available backups. The mutate gateway handles create/restore.
+                    const result = systemListBackups(projectRoot);
+                    if (!result.success || !result.data) {
+                        return wrapResult(result, 'query', 'admin', operation, startTime);
+                    }
+                    const backups = result.data;
+                    return wrapResult({ success: true, data: { backups, count: backups.length } }, 'query', 'admin', operation, startTime);
+                }
+                case 'map': {
+                    const { mapCodebase } = await import('../engines/codebase-map-engine.js');
+                    const result = await mapCodebase(projectRoot, {
+                        focus: params?.focus,
+                        storeToBrain: false,
+                    });
+                    return wrapResult(result, 'query', 'admin', operation, startTime);
+                }
+                case 'roadmap': {
+                    const result = await systemRoadmap(projectRoot, {
+                        includeHistory: params?.includeHistory,
+                        upcomingOnly: params?.upcomingOnly,
+                    });
+                    return wrapResult(result, 'query', 'admin', operation, startTime);
+                }
+                case 'smoke': {
+                    const result = await systemSmoke();
+                    return wrapResult(result, 'query', 'admin', operation, startTime);
+                }
+                case 'hooks.matrix': {
+                    const result = await systemHooksMatrix({
+                        providerIds: params?.providerIds,
+                        detectProvider: params?.detectProvider !== false,
+                    });
+                    return wrapResult(result, 'query', 'admin', operation, startTime);
+                }
+                default:
+                    return unsupportedOp('query', 'admin', operation, startTime);
+            }
+        }
+        catch (error) {
+            getLogger('domain:admin').error({ gateway: 'query', domain: 'admin', operation, err: error }, error instanceof Error ? error.message : String(error));
+            return handleErrorResult('query', 'admin', operation, error, startTime);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Mutate
+    // -----------------------------------------------------------------------
+    async mutate(operation, params) {
+        const projectRoot = getProjectRoot();
+        const startTime = Date.now();
+        try {
+            switch (operation) {
+                case 'init': {
+                    const result = await initProject(projectRoot, params);
+                    return wrapResult(result, 'mutate', 'admin', operation, startTime);
+                }
+                case 'scaffold-hub': {
+                    // Phase 1: create CleoOS Hub dirs and seed starter justfile
+                    const result = await systemScaffoldHub();
+                    return wrapResult(result, 'mutate', 'admin', operation, startTime);
+                }
+                // Merged: health (mutate) absorbs fix and doctor via mode param (T5615)
+                case 'health': {
+                    const mode = params?.mode;
+                    if (mode === 'diagnose') {
+                        const result = await systemDoctor(projectRoot);
+                        return wrapResult(result, 'mutate', 'admin', operation, startTime);
+                    }
+                    // Default: repair mode
+                    const result = await systemFix(projectRoot);
+                    return wrapResult(result, 'mutate', 'admin', operation, startTime);
+                }
+                case 'config.set': {
+                    const key = params?.key;
+                    if (!key) {
+                        return errorResult('mutate', 'admin', operation, 'E_INVALID_INPUT', 'key is required', startTime);
+                    }
+                    const result = await configSet(projectRoot, key, params?.value);
+                    return wrapResult(result, 'mutate', 'admin', operation, startTime);
+                }
+                case 'config.set-preset': {
+                    const preset = params?.preset;
+                    if (!preset) {
+                        return errorResult('mutate', 'admin', operation, 'E_INVALID_INPUT', 'preset is required (strict, standard, or minimal)', startTime);
+                    }
+                    const result = await configSetPreset(projectRoot, preset);
+                    return wrapResult(result, 'mutate', 'admin', operation, startTime);
+                }
+                // Merged: backup absorbs restore and backup.restore via action param (T5615)
+                case 'backup': {
+                    const action = params?.action;
+                    if (action === 'restore') {
+                        const backupId = params?.backupId;
+                        if (!backupId) {
+                            return errorResult('mutate', 'admin', operation, 'E_INVALID_INPUT', 'backupId is required', startTime);
+                        }
+                        const result = systemRestore(projectRoot, {
+                            backupId,
+                            force: params?.force,
+                        });
+                        return wrapResult(result, 'mutate', 'admin', operation, startTime);
+                    }
+                    if (action === 'restore.file') {
+                        const file = params?.file;
+                        if (!file) {
+                            return errorResult('mutate', 'admin', operation, 'E_INVALID_INPUT', 'file is required', startTime);
+                        }
+                        const result = await backupRestore(projectRoot, file, {
+                            dryRun: params?.dryRun,
+                        });
+                        return wrapResult(result, 'mutate', 'admin', operation, startTime);
+                    }
+                    // Default: create backup (T5158: async so tasks.db + brain.db
+                    // can be opened via drizzle accessors before VACUUM INTO runs).
+                    const result = await systemBackup(projectRoot, params);
+                    return wrapResult(result, 'mutate', 'admin', operation, startTime);
+                }
+                case 'migrate': {
+                    const result = await systemMigrate(projectRoot, params);
+                    return wrapResult(result, 'mutate', 'admin', operation, startTime);
+                }
+                case 'cleanup': {
+                    const target = params?.target;
+                    if (!target) {
+                        return errorResult('mutate', 'admin', operation, 'E_INVALID_INPUT', 'target is required', startTime);
+                    }
+                    const result = await systemCleanup(projectRoot, {
+                        target,
+                        olderThan: params?.olderThan,
+                        dryRun: params?.dryRun,
+                    });
+                    return wrapResult(result, 'mutate', 'admin', operation, startTime);
+                }
+                case 'job.cancel': {
+                    const { getJobManager } = await import('../lib/job-manager-accessor.js');
+                    const mgr = getJobManager();
+                    if (!mgr) {
+                        return errorResult('mutate', 'admin', operation, 'E_NOT_AVAILABLE', 'Job manager not available. Background jobs require a running CLEO daemon or long-lived process. Start one with `cleo daemon start` or use `cleo admin health` to check system status.', startTime);
+                    }
+                    const jobId = params?.jobId;
+                    if (!jobId) {
+                        return errorResult('mutate', 'admin', operation, 'E_INVALID_INPUT', 'jobId is required', startTime);
+                    }
+                    const cancelled = mgr.cancelJob(jobId);
+                    if (!cancelled) {
+                        return errorResult('mutate', 'admin', operation, 'E_NOT_FOUND', `Job ${jobId} not found or not running`, startTime);
+                    }
+                    return wrapResult({ success: true, data: { jobId, cancelled: true } }, 'mutate', 'admin', operation, startTime);
+                }
+                case 'safestop': {
+                    const result = await systemSafestop(projectRoot, params);
+                    return wrapResult(result, 'mutate', 'admin', operation, startTime);
+                }
+                case 'inject.generate': {
+                    const result = await systemInjectGenerate(projectRoot);
+                    return wrapResult(result, 'mutate', 'admin', operation, startTime);
+                }
+                // adr.sync absorbs adr.validate via validate flag (T5615)
+                case 'adr.sync': {
+                    const validate = params?.validate;
+                    if (validate) {
+                        const result = await validateAllAdrs(projectRoot);
+                        return {
+                            meta: dispatchMeta('mutate', 'admin', operation, startTime),
+                            success: result.valid,
+                            data: result,
+                            ...(result.valid
+                                ? {}
+                                : {
+                                    error: {
+                                        code: 'E_ADR_VALIDATION',
+                                        message: `${result.errors.length} ADR validation error(s) found`,
+                                    },
+                                }),
+                        };
+                    }
+                    const result = await syncAdrsToDb(projectRoot);
+                    const hasErrors = result.errors.length > 0;
+                    return {
+                        meta: dispatchMeta('mutate', 'admin', operation, startTime),
+                        success: !hasErrors,
+                        data: result,
+                        ...(hasErrors
+                            ? {
+                                error: {
+                                    code: 'E_ADR_SYNC',
+                                    message: `${result.errors.length} ADR sync error(s) occurred`,
+                                },
+                            }
+                            : {}),
+                    };
+                }
+                // Merged: import + snapshot.import + import.tasks → import via scope param (T5615)
+                case 'import': {
+                    const scope = params?.scope;
+                    if (scope === 'snapshot') {
+                        const file = params?.file;
+                        if (!file) {
+                            return errorResult('mutate', 'admin', operation, 'E_INVALID_INPUT', 'file is required', startTime);
+                        }
+                        const snapshot = await readSnapshot(file);
+                        if (params?.dryRun) {
+                            return {
+                                meta: dispatchMeta('mutate', 'admin', operation, startTime),
+                                success: true,
+                                data: {
+                                    dryRun: true,
+                                    source: snapshot._meta.source,
+                                    taskCount: snapshot._meta.taskCount,
+                                    createdAt: snapshot._meta.createdAt,
+                                },
+                            };
+                        }
+                        const result = await importSnapshot(snapshot, projectRoot);
+                        return {
+                            meta: dispatchMeta('mutate', 'admin', operation, startTime),
+                            success: true,
+                            data: {
+                                imported: true,
+                                added: result.added,
+                                updated: result.updated,
+                                skipped: result.skipped,
+                                conflicts: result.conflicts.length > 0 ? result.conflicts : undefined,
+                            },
+                        };
+                    }
+                    if (scope === 'tasks') {
+                        const file = params?.file;
+                        if (!file) {
+                            return errorResult('mutate', 'admin', operation, 'E_INVALID_INPUT', 'file is required', startTime);
+                        }
+                        const result = await importTasksPackage({
+                            file,
+                            dryRun: params?.dryRun,
+                            parent: params?.parent,
+                            phase: params?.phase,
+                            addLabel: params?.addLabel,
+                            provenance: params?.provenance,
+                            resetStatus: params?.resetStatus,
+                            onConflict: params?.onConflict,
+                            onMissingDep: params?.onMissingDep,
+                            force: params?.force,
+                            cwd: projectRoot,
+                        });
+                        return {
+                            meta: dispatchMeta('mutate', 'admin', operation, startTime),
+                            success: true,
+                            data: result,
+                        };
+                    }
+                    // Default: standard import
+                    const file = params?.file;
+                    if (!file) {
+                        return errorResult('mutate', 'admin', operation, 'E_INVALID_INPUT', 'file is required', startTime);
+                    }
+                    const result = await importTasks({
+                        file,
+                        parent: params?.parent,
+                        phase: params?.phase,
+                        onDuplicate: params?.onDuplicate,
+                        addLabel: params?.addLabel,
+                        dryRun: params?.dryRun,
+                        cwd: projectRoot,
+                    });
+                    return {
+                        meta: dispatchMeta('mutate', 'admin', operation, startTime),
+                        success: true,
+                        data: result,
+                    };
+                }
+                case 'detect': {
+                    const { ensureProjectContext, ensureContributorMcp: ensureContributorDev } = await import('@cleocode/core/internal');
+                    const contextResult = await ensureProjectContext(projectRoot, { force: true });
+                    const devResult = await ensureContributorDev(projectRoot);
+                    return wrapResult({
+                        success: true,
+                        data: { context: contextResult, devChannel: devResult },
+                    }, 'mutate', 'admin', operation, startTime);
+                }
+                // Merged: token.record + token.delete + token.clear → token via action param (T5615)
+                case 'token': {
+                    return routeByParam(params, 'action', {
+                        record: async () => {
+                            const result = await recordTokenExchange({
+                                provider: params?.provider,
+                                model: params?.model,
+                                transport: params?.transport,
+                                gateway: params?.gateway,
+                                domain: params?.domain,
+                                operation: params?.operationName,
+                                sessionId: params?.sessionId,
+                                taskId: params?.taskId,
+                                requestId: params?.requestId,
+                                requestPayload: params?.requestPayload,
+                                responsePayload: params?.responsePayload,
+                                metadata: params?.metadata,
+                                cwd: projectRoot,
+                            });
+                            return {
+                                meta: dispatchMeta('mutate', 'admin', operation, startTime),
+                                success: true,
+                                data: result,
+                            };
+                        },
+                        delete: async () => {
+                            const tokenId = params?.tokenId;
+                            if (!tokenId) {
+                                return errorResult('mutate', 'admin', operation, 'E_INVALID_INPUT', 'tokenId is required', startTime);
+                            }
+                            const result = await deleteTokenUsage(tokenId, projectRoot);
+                            return {
+                                meta: dispatchMeta('mutate', 'admin', operation, startTime),
+                                success: true,
+                                data: result,
+                            };
+                        },
+                        clear: async () => {
+                            const result = await clearTokenUsage({
+                                provider: params?.provider,
+                                transport: params?.transport,
+                                gateway: params?.gateway,
+                                domain: params?.domain,
+                                operation: params?.operationName,
+                                sessionId: params?.sessionId,
+                                taskId: params?.taskId,
+                                method: params?.method,
+                                confidence: params?.confidence,
+                                requestId: params?.requestId,
+                                since: params?.since,
+                                until: params?.until,
+                            }, projectRoot);
+                            return {
+                                meta: dispatchMeta('mutate', 'admin', operation, startTime),
+                                success: true,
+                                data: result,
+                            };
+                        },
+                    }, 'record');
+                }
+                // admin.context.inject — moved from session domain (T5615)
+                case 'context.inject': {
+                    const protocolType = params?.protocolType;
+                    if (!protocolType) {
+                        return errorResult('mutate', 'admin', operation, 'E_INVALID_INPUT', 'protocolType is required', startTime);
+                    }
+                    const result = sessionContextInject(protocolType, {
+                        taskId: params?.taskId,
+                        variant: params?.variant,
+                    }, projectRoot);
+                    return wrapResult(result, 'mutate', 'admin', operation, startTime);
+                }
+                case 'map': {
+                    const { mapCodebase } = await import('../engines/codebase-map-engine.js');
+                    const result = await mapCodebase(projectRoot, {
+                        focus: params?.focus,
+                        storeToBrain: true,
+                    });
+                    return wrapResult(result, 'mutate', 'admin', operation, startTime);
+                }
+                // admin.install.global — refresh global CLEO setup (T4916)
+                case 'install.global': {
+                    const { ensureGlobalScaffold, ensureGlobalTemplates } = await import('@cleocode/core/internal');
+                    const scaffoldResult = await ensureGlobalScaffold();
+                    const templateResult = await ensureGlobalTemplates();
+                    return wrapResult({
+                        success: true,
+                        data: { scaffold: scaffoldResult, templates: templateResult },
+                    }, 'mutate', 'admin', operation, startTime);
+                }
+                default:
+                    return unsupportedOp('mutate', 'admin', operation, startTime);
+            }
+        }
+        catch (error) {
+            getLogger('domain:admin').error({ gateway: 'mutate', domain: 'admin', operation, err: error }, error instanceof Error ? error.message : String(error));
+            return handleErrorResult('mutate', 'admin', operation, error, startTime);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Supported operations
+    // -----------------------------------------------------------------------
+    getSupportedOperations() {
+        return {
+            query: [
+                'version',
+                'health',
+                'config.show',
+                'config.presets',
+                'stats',
+                'context',
+                'context.pull',
+                'runtime',
+                'paths',
+                'job',
+                'dash',
+                'log',
+                'sequence',
+                'help',
+                'token',
+                'adr.show',
+                'adr.find',
+                'backup',
+                'export',
+                'map',
+                'roadmap',
+                'smoke',
+                'hooks.matrix',
+            ],
+            mutate: [
+                'init',
+                'scaffold-hub',
+                'config.set',
+                'config.set-preset',
+                'backup',
+                'migrate',
+                'cleanup',
+                'job.cancel',
+                'safestop',
+                'inject.generate',
+                'install.global',
+                'token',
+                'adr.sync',
+                'health',
+                'context.inject',
+                'import',
+                'detect',
+                'map',
+            ],
+        };
+    }
+}
+//# sourceMappingURL=admin.js.map